Unless you were a Math Geek or an Ancient Greek, Geometry probably wasn’t your favorite subject in school. More likely, you were that kid in class who dutifully programmed all of those necessary formulæ into your TI-8X calculator to avoid rote memorization.

So for those of you who spent more time learning TI-BASIC than Euclid, here’s the cheat-sheet for how geometry works in Quartz 2D, the drawing system used by Apple platforms:

• A CGFloat represents a scalar quantity.
• A CGPoint represents a location in a two-dimensional coordinate system and is defined by x and y scalar components.
• A CGSize represents the extent of a figure in 2D space and is defined by width and height scalar components.
• A CGVector represents a change in position in 2D space and is defined by dx and dy scalar components.
• A CGRect represents a rectangle and is defined by an origin point (CGPoint) and a size (CGSize).

importCoreGraphicsletfloat:CGFloat=1.0letpoint=CGPoint(x:1.0,y:2.0)letsize=CGSize(width:4.0,height:3.0)letvector=CGVector(dx:4.0,dy:3.0)varrectangle=CGRect(origin:point,size:size)

On iOS, the origin is located at the top-left corner of a window, so x and y values increase as they move down and to the right. macOS, by default, orients (0, 0) at the bottom left corner of a window, such that y values increase as they move up.

Every view in an iOS or macOS app has a frame represented by a CGRect value, so one would do well to learn the fundamentals of these geometric primitives.

In this week’s article, we’ll do a quick run through the APIs with which every app developer should be familiar.

Introspection

“First, know thyself.” So goes the philosophical aphorism. And it remains practical guidance as we begin our survey of CoreGraphics API.

As structures, you can access the member values of geometric types directly through their stored properties:

point.x// 1.0point.y// 2.0size.width// 4.0size.height// 3.0rectangle.origin// {x 1 y 2}rectangle.size// {w 4 h 3}

You can mutate variables by reassignment or by using mutating operators like *= and +=:

varmutableRectangle=rectangle// {x 1 y 2 w 4 h 3}mutableRectangle.origin.x=7.0mutableRectangle.size.width*=2.0mutableRectangle.size.height+=3.0mutableRectangle// {x 7 y 2 w 8 h 6}

For convenience, rectangles also expose width and height as top-level, computed properties; (x and y coordinates must be accessed through the intermediary origin):

rectangle.origin.xrectangle.origin.yrectangle.widthrectangle.height

Accessing Minimum, Median, and Maximum Values

Although a rectangle can be fully described by a location (CGPoint) and an extent (CGSize), that’s just one side of the story.

For the other 3 sides, use the built-in convenience properties to get the minimum (min), median (mid), and maximum (max) values in the x and y dimensions:

rectangle.minX// 1.0rectangle.midX// 3.0rectangle.maxX// 5.0rectangle.minY// 2.0rectangle.midY// 3.5rectangle.maxY// 5.0

Computing the Center of a Rectangle

It’s often useful to compute the center point of a rectangle. Although this isn’t provided by the framework SDK, you can easily extend CGRect to implement it using the midX and midY properties:

extensionCGRect{varcenter:CGPoint{returnCGPoint(x:midX,y:midY)}}

Normalization

Things can get a bit strange when you use non-integral or negative values in geometric calculations. Fortunately, CoreGraphics has just the APIs you need to keep everything in order.

Standardizing Rectangles

We expect that a rectangle’s origin is situated at its top-left corner. However, if its size has a negative width or height, the origin could become any of the other corners instead.

For example, consider the following bizarro rectangle that extends leftwards and upwards from its origin.

letǝןƃuɐʇɔǝɹ=CGRect(origin:point,size:CGSize(width:-4.0,height:-3.0))ǝןƃuɐʇɔǝɹ// {x 1 y 2 w -4 h -3}

We can use the standardized property to get the equivalent rectangle with non-negative width and height. In the case of the previous example, the standardized rectangle has a width of 4 and height of 3 and is situated at the point (-3, -1):

ǝןƃuɐʇɔǝɹ.standardized// {x -3 y -1 w 4 h 3}

Integrating Rectangles

It’s generally a good idea for all CGRect values to be rounded to the nearest whole point. Fractional values can cause the frame to be drawn on a pixel boundary. Because pixels are atomic units, a fractional value causes drawing to be averaged over the neighboring pixels. The result: blurry lines that don’t look great.

The integral property takes the floor each origin value and the ceil each size value. This ensures that your drawing code aligns on pixel boundaries crisply.

letblurry=CGRect(x:0.1,y:0.5,width:3.3,height:2.7)blurry// {x 0.1 y 0.5 w 3.3 h 2.7}blurry.integral// {x 0 y 0 w 4 h 4}

Transformations

While it’s possible to mutate a rectangle by performing member-wise operations on its origin and size, the CoreGraphics framework offers better solutions by way of the APIs discussed below.

Translating Rectangles

Translation describes the geometric operation of moving a shape from one location to another.

Use the offsetBy method (or CGRectOffset function in Objective-C) to translate a rectangle’s origin by a specified x and y distance.

rectangle.offsetBy(dx:2.0,dy:2.0)// {x 3 y 4 w 4 h 3}

Consider using this method whenever you shift a rectangle’s position. Not only does it save a line of code, but it more semantically represents intended operation than manipulating the origin values individually.

Contracting and Expanding Rectangles

Other common transformations for rectangles include contraction and expansion around a center point. The insetBy(dx:dy:) method can accomplish both.

When passed a positive value for either component, this method returns a rectangle that shrinks by the specified amount from each side as computed from the center point. For example, when inset by 1.0 horizontally (dy = 0.0), a rectangle originating at (1, 2) with a width of 4 and height equal to 3, produces a new rectangle originating at (2, 2) with width equal to 2 and height equal to 3. Which is to say: the result of insetting a rectangle by 1 point horizontally is a rectangle whose width is 2 points smaller than the original.

rectangle// {x 1 y 2 w 4 h 3}rectangle.insetBy(dx:1.0,dy:0.0)// {x 2 y 2 w 2 h 3}

When passed a negative value for either component, the rectangle grows by that amount from each side. When passed a non-integral value, this method may produce a rectangle with non-integral components.

rectangle.insetBy(dx:-1.0,dy:0.0)// {x 0 y 2 w 6 h 3}rectangle.insetBy(dx:0.5,dy:0.0)// {x 1.5 y 2 w 3 h 3}

Identities and Special Values

Points, sizes, and rectangles each have a zero property, which defines the identity value for each respective type:

CGPoint.zero// {x 0 y 0}CGSize.zero// {w 0 h 0}CGRect.zero// {x 0 y 0 w 0 h 0}

Swift shorthand syntax allows you to pass .zero directly as an argument for methods and initializers, such as CGRect.init(origin:size:):

letsquare=CGRect(origin:.zero,size:CGSize(width:4.0,height:4.0))

CGRect has two additional special values: infinite and null:

CGRect.infinite// {x -∞ y -∞ w +∞ h +∞}CGRect.null// {x +∞ y +∞ w 0 h 0}

CGRect.null is conceptually similar to NSNotFound, in that it represents the absence of an expected value, and does so using the largest representable number to exclude all other values.

CGRect.infinite has even more interesting properties, as it intersects with all points and rectangles, contains all rectangles, and its union with any rectangle is itself.

CGRect.infinite.contains(any point)// trueCGRect.infinite.intersects(any other rectangle)// trueCGRect.infinite.union(any other rectangle)// CGRect.infinite

Use isInfinite to determine whether a rectangle is, indeed, infinite.

CGRect.infinite.isInfinite// true

But to fully appreciate why these values exist and how they’re used, let’s talk about geometric relationships:

Relationships

Up until this point, we’ve been dealing with geometries in isolation. To round out our discussion, let’s consider what’s possible when evaluating two or more rectangles.

Intersection

Two rectangles intersect if they overlap. Their intersection is the smallest rectangle that encompasses all points contained by both rectangles.

In Swift, you can use the intersects(_:) and intersection(_:) methods to efficiently compute the intersection of two CGRect values:

letsquare=CGRect(origin:.zero,size:CGSize(width:4.0,height:4.0))square// {x 0 y 0 w 4 h 4}rectangle.intersects(square)// truerectangle.intersection(square)// {x 1 y 2 w 3 h 2}

If two rectangles don’t intersect, the intersection(_:) method produces CGRect.null:

rectangle.intersects(.zero)// falserectangle.intersection(.zero)// CGRect.null

Union

The union of two rectangles is the smallest rectangle that encompasses all of the points contained by either rectangle.

In Swift, the aptly-named union(_:) method does just this for two CGRect values:

rectangle.union(square)// {x 0 y 0 w 5 h 5}

So what if you didn’t pay attention in Geometry class — this is the real world. And in the real world, you have CGGeometry.h and all of the types and functions it provides.

Know it well, and you’ll be on your way to discovering great new user interfaces in your apps. Do a good enough job with that, and you may encounter the best arithmetic problem of all: adding up all the money you’ve made with your awesome new app. Mathematical!

Back in the early days of Swift 1, we didn’t have much in the way of error handling. But we did have Optional, and it felt awesome! By making null checks explicit and enforced, bombing out of a function by returning nil suddenly felt less like a code smell and more like a language feature.

Here’s how we might write a little utility to grab Keychain data returning nil for any errors:

funckeychainData(service:String)->Data?{letquery:NSDictionary=[kSecClass:kSecClassGenericPassword,kSecAttrService:service,kSecReturnData:true]varref:CFTypeRef?=nilswitchSecItemCopyMatching(query,&ref){case errSecSuccess:
        returnrefas?Datadefault:returnnil}}

We set up a query, pass an an empty inout reference to SecItemCopyMatching and then, depending on the status code we get back, either return the reference as data or nil if there was an error.

At the call site, we can tell if something has exploded by unwrapping the optional:

ifletmyData=keychainData(service:"My Service"){do something with myData...}else{fatalError("Something went wrong with... something?")}

Getting Results

There’s a certain binary elegance to the above, but it conceals an achilles heel. At its heart, Optional is just an enum that holds either some wrapped value or nothing:

enumOptional<Wrapped>{case some(Wrapped)
        case none
        }

This works just fine for our utility when everything goes right — we just return our value. But most operations that involve I/O can go wrong (SecItemCopyMatching, in particular, can go wrong many, many ways), and Optional ties our hands when it comes to signaling something’s gone sideways. Our only option is to return nothing.

Meanwhile, at the call site, we’re wondering what the issue is and all we’ve got to work with is this empty .none. It’s difficult to write robust software when every non-optimal condition is essentially reduced to ¯\_(ツ)_/¯. How could we improve this situation?

One way would be to add some language-level features that let functions throw errors in addition to returning values. And this is, in fact, exactly what Swift did in version 2 with its throws/throw and do/catch syntax.

But let’s stick with our Optional line of reasoning for just a moment. If the issue is that Optional can only hold a value or nil, and in the event of an error nil isn’t expressive enough, maybe we can address the issue simply by making a new Optional that holds either a value or an error?

Well, congratulations are in order: change a few names, and we see we just invented the new Result type, now available in the Swift 5 standard library!

enumResult<Success,Failure:Error>{case success(Success)
        case failure(Failure)
        }

Result holds either a successful value or an error. And we can use it to improve our little keychain utility.

First, let’s define a custom Error type with some more descriptive cases than a simple nil:

enumKeychainError:Error{case notData
        case notFound(name: String)
        case ioWentBad
        ...}

Next we change our keychainData definition to return Result<Data, Error> instead of Data?. When everything goes right we return our data as the associated value of a .success. What happens if any of SecItemCopyMatching’s many and varied disasters strike? Rather than returning nil we return one of our specific errors wrapped in a .failure:

funckeychainData(service:String)->Result<Data,Error>{letquery:NSDictionary=[...]varref:CFTypeRef?=nilswitchSecItemCopyMatching(query,&ref){case errSecSuccess:
        guardletdata=refas?Dataelse{return.failure(KeychainError.notData)}return.success(data)case errSecItemNotFound:
        return.failure(KeychainError.notFound(name:service))case errSecIO:
        return.failure(KeychainError.ioWentBad)...}}

Now we have a lot more information to work with at the call site! We can, if we choose, switch over the result, handling both success and each error case individually:

switchkeychainData(service:"My Service"){case .success(let data):
        do something with data...case .failure(KeychainError.notFound(let name)):
        print(""\(name)" not found in keychain.")case .failure(KeychainError.io):
        print("Error reading from the keychain.")case .failure(KeychainError.notData):
        print("Keychain is broken.")...}

All things considered, Result seems like a pretty useful upgrade to Optional. How on earth did it take it five years to be added to the standard library?

Three’s a Crowd

Alas, Result is also cursed with an achilles heel — we just haven’t noticed it yet because, up until now, we’ve only been working with a single call to a single function. But imagine we add two more error-prone operations to our list of Result-returning utilities:

funcmakeAvatar(fromuser:Data)->Result<UIImage,Error>{Return avatar made from user's initials...or return failure...}funcsave(image:UIImage)->Result<Void,Error>{Save image and return success...or returns failure...}

In our example, the first function generates an avatar from user data, and the second writes an image to disk. The implementations don’t matter so much for our purposes, just that they return a Result type.

Now, how would we write something that fetches user data from the keychain, uses it to create an avatar, saves that avatar to disk, and handles any errors that might occur along the way?

We might try something like:

switchkeychainData(service:"UserData"){case .success(let userData):
        switchmakeAvatar(from:userData){case .success(let avatar):
        switchsave(image:avatar){case .success:
        break// continue on with our program...case .failure(FileSystemError.readOnly):
        print("Can't write to disk.")...}case .failure(AvatarError.invalidUserFormat):
        print("Unable to generate avatar from given user.")...}case .failure(KeychainError.notFound(let name)):
        print(""\(name)" not found in keychain.")...}

But whooo boy. Adding just two functions has led to an explosion of nesting, dislocated error handling, and woe.

Falling Flat

Thankfully, we can clean this up by taking advantage of the fact that, like Optional, Result implements flatMap. Specifically, flatMap on a Result will, in the case of .success, apply the given transform to the associated value and return the newly produced Result. In the case of a .failure, however, flatMap simply passes the .failure and its associated error along without modification.

Because it passes errors through in this manner, we can use flatMap to combine our operations together without checking for .failure each step of the way. This lets us minimize nesting and keep our error handling and operations distinct:

letresult=keychainData(service:"UserData").flatMap(makeAvatar).flatMap(save)switchresult{case .success:
        break// continue on with our program...case .failure(KeychainError.notFound(let name)):
        print(""\(name)" not found in keychain.")case .failure(AvatarError.invalidUserFormat):
        print("Unable to generate avatar from given user.")case .failure(FileSystemError.readOnly):
        print("Can't write to disk.")...}

This is, without a doubt, an improvement. But it requires us (and anyone reading our code) to be familiar enough with .flatMap to follow its somewhat unintuitive semantics.

Compare this to the do/catch syntax from all the way back in Swift 2 that we alluded to a little earlier:

do{letuserData=trykeychainData(service:"UserData")letavatar=trymakeAvatar(from:userData)trysave(image:avatar)}catchKeychainError.notFound(letname){print(""\(name)" not found in keychain.")}catchAvatarError.invalidUserFormat{print("Not enough memory to create avatar.")}catchFileSystemError.readOnly{print("Could not save avatar to read-only media.")}...

The first thing that might stand out is how similar these two pieces of code are. They both have a section up top for executing our operations. And both have a section down below for matching errors and handling them.

Whereas the Result version has us piping operations through chained calls to flatMap, we write the do/catch code more or less exactly as we would if no error handling were involved. While the Result version requires we understand the internals of its enumeration and explicitly switch over it to match errors, the do/catch version lets us focus on the part we actually care about: the errors themselves.

By having language-level syntax for error handling, Swift effectively masks all the Result-related complexities it took us the first half of this post to digest: enumerations, associated values, generics, flatMap, monads… In some ways, Swift added error-handling syntax back in version 2 specifically so we wouldn’t have to deal with Result and its eccentricities.

Yet here we are, five years later, learning all about it. Why add it now?

Error’s Ups and Downs

Well, as it should happen, do/catch has this little thing we might call an achilles heel…

See, throw, like return, only works in one direction; up. We can throw an error “up” to the caller, but we can’t throw an error “down” as a parameter to another function we call.

This “up”-only behavior is typically what we want. Our keychain utility, rewritten once again with error handling, is all returns and throws because its only job is passing either our data or an error back up to the thing that called it:

funckeychainData(service:String)throws->Data{letquery:NSDictionary=[...]varref:CFTypeRef?=nilswitchSecItemCopyMatching(query,&ref){case errSecSuccess:
        guardletdata=refas?Dataelse{throwKeychainError.notData}returndatacase errSecItemNotFound:
        throwKeychainError.notFound(name:service)case errSecIO:
        throwKeychainError.ioWentBad...}}

But what if, instead of fetching user data from the keychain, we want to get it from a cloud service? Even on a fast, reliable connection, loading data over a network can take a long time compared to reading it from disk. We don’t want to block the rest of our application while we wait, of course, so we’ll make it asynchronous.

But that means we’re no longer returning anything“up”. Instead we’re calling “down” into a closure on completion:

funcuserData(foruserID:String,completion:(Data)->Void){get data from the network// Then, sometime later:completion(myData)}

Now network operations can fail with all sorts of different errors, but we can’t throw them “down” into completion. So the next best option is to pass any errors along as a second (optional) parameter:

funcuserData(foruserID:String,completion:(Data?,Error?)->Void){Fetch data over the network...guardmyError==nilelse{completion(nil,myError)}completion(myData,nil)}

But now the caller, in an effort to make sense of this cartesian maze of possible parameters, has to account for many impossible scenarios in addition to the ones we actually care about:

userData(for:"jemmons"){maybeData,maybeErrorinswitch(maybeData,maybeError){case let (data?, nil):
        do something with data...case (nil, URLError.timedOut?):
        print("Connection timed out.")case (nil, nil):
        fatalError("🤔Hmm. This should never happen.")case (_?, _?):
        fatalError("😱What would this even mean?")...}}

It’d be really helpful if, instead of this mishmash of “data or nil and error or nil” we had some succinct way to express simply “data or error”.

Stop Me If You’ve Heard This One…

Wait, data or error? That sounds familiar. What if we used a Result?

funcuserData(foruserID:String,completion:(Result<Data,Error>)->Void){// Everything went well:completion(.success(myData))// Something went wrong:completion(.failure(myError))}

And at the call site:

userData(for:"jemmons"){resultinswitch(result){case (.success(let data)):
        do something with data...case (.failure(URLError.timedOut)):
        print("Connection timed out.")...}

Ah ha! So we see that the Result type can serve as a concrete reification of Swift’s abstract idea of “that thing that’s returned when a function is marked as throws.” And as such, we can use it to deal with asynchronous operations that require concrete types for parameters passed to their completion handlers.

So, while the shape of Result has been implied by error handling since Swift 2 (and, indeed, quite a few developers have created their own versions of it in the intervening years), it’s now officially added to the standard library in Swift 5 — primarily as a way to deal with asynchronous errors.

Which is undoubtedly better than passing the double-optional (Value?, Error?) mess we saw earlier. But didn’t we just get finished making the case that Result tended to be overly verbose, nesty, and complex when dealing with more than one error-capable call? Yes we did.

And, in fact, this is even more of an issue in the async space since flatMap expects its transform to return synchronously. So we can’t use it to compose asynchronous operations:

userData(for:"jemmons"){userResultinswitchuserResult{case .success(let user):
        fetchAvatar(for:user){avatarResultinswitchavatarResult{case .success(let avatar):
        cloudSave(image:avatar){saveResultinswitchsaveResult{case .success:
        // All done!case .failure(URLError.timedOut)
        print("Operation timed out.")...}}case .failure(AvatarError.invalidUserFormat):
        print("User not recognized.")...}}case .failure(URLError.notConnectedToInternet):
        print("No internet detected.")...}

Awaiting the Future

In the near term, we just have to lump it. It’s better than the other alternatives native to the language, and chaining asynchronous calls isn’t as common as for synchronous calls.

But in the future, just as Swift used do/catch syntax to define away Result nesting problems in synchronous error handling, there are many proposals being considered to do the same for asynchronous errors (and asynchronous processing, generally).

The async/await proposal is one such animal. If adopted it would reduce the above to:

do{letuser=tryawaituserData(for:"jemmons")letavatar=tryawaitfetchAvatar(for:user)tryawaitcloudSave(image:avatar)}catchAvatarError.invalidUserFormat{print("User not recognized.")}catchURLError.timedOut{print("Operation timed out.")}catchURLError.notConnectedToInternet{print("No internet detected.")}...

Which, holy moley! As much as I love Result, I, for one, cannot wait for it to be made completely irrelevant by our glorious async/await overlords.

Meanwhile? Let us rejoice! For we finally have a concrete Result type in the standard library to light the way through these, the middle ages of async error handling in Swift.

Apple is nothing if not consistent. From Pentalobular screws to Sandboxing, customers are simply expected to relinquish a fair amount of control when they choose to buy a Mac or iPhone. Whether these design decisions are made to ensure a good user experience, or this control is exercised as an end in itself is debatable, but the reality is that in both hardware and software, Apple prefers an ivory tower to a bazaar.

No better example of this can be found with Xcode: the very software that software developers use to build software for the walled ecosystems of iOS & OS X software, is itself a closed ecosystem.

Indeed, significant progress has been made in recent years to break open the developer workflow, from alternative IDEs like AppCode to build tools like CocoaPods, xctool and nomad. However, the notion that Xcode itself could be customized and extended by mere mortals is extremely recent, and just now starting to pick up steam.

Xcode has had a plugin architecture going back to when Interface Builder was its own separate app. However, this system was relatively obscure, undocumented, and not widely used by third parties. Despite this, developers like Delisa Mason and Marin Usalj have done incredible work creating a stable and vibrant ecosystem of third-party Xcode extensions.

Simply install Alcatraz, and pull down all of the plugins (and color schemes and templates) that you desire.

This week on NSHipster: a roundup of some of the most useful and exciting plugins for Xcode—ready for you to try out yourself today!

And since these question come up every time there’s an article with pictures:

1. The color scheme is Tomorrow Night
2. The app used to make animated GIFs is LICEcap

Making Xcode More Like X

Just as New York became a melting pot of cultures from immigrants arriving at Ellis Island, Xcode has welcomed the tired, poor, huddled masses of developers from every platform and language imaginable. Like those first wave Americans, who settled into their respective ethnic neighborhoods to re-establish their traditions in a new land, so too have new iOS developers brought over their preferred workflows and keybindings.

Perhaps you would appreciate a taste of home in the land of Cupertino.

Vim

Finding it too easy to quit Xcode? Try XVim, an experimental plugin that adds all of your favorite Vim keybindings.

SublimeText

Do you miss having a code minimap along the right gutter of your editor to put things into perspective? Install SCXcodeMiniMap and never again miss the tree nodes for the forest.

Atom

Looking to be more in tune with GitHub? Add the Show in GitHub / BitBucket plugin to open to the selected lines of a file online.

Fixing Xcode

Rather than waiting with crossed fingers and clenched teeth each June, as Apple engineers unveil the next version of Xcode, developers now have the ability to tailor the de facto editor to their particular needs (and most importantly, fix what’s broken).

Add Line Breaks to Issue Navigator

An annoyance going back to Xcode 4 has been the truncation of items in the Issues Navigator. Never again be frustrated by surprise ellipses when compiler warnings were just starting to get interesting, with BBUFullIssueNavigator.

Dismiss Debugging Console When Typing

Another annoyance going back to Xcode 4 is how the debugging console seems to always get in the way. No more, with BBUDebuggerTuckAway. As soon as you start typing in the editor, the debugging window will get out of your way.

Add ANSI Color Support to Debugging Console

ncurses enthusiasts will no doubt be excited by the XcodeColors plugin, which adds support for ANSI colors to appear in the debugging console.

Hide @property Methods in Source Navigator

Finding that @property synthesizers are creating a low signal-to-noise ratio in the Source Navigator? Let Xprop excise the cruft, and let the functions and methods shine through.

Blow Away DerivedData Folder

Xcode texting you again?rm -rf-ing the heck out of “Library/Developer/Xcode/DerivedData” does the trick every time, 90% of the time. Add a convenient button to your Xcode window to do this for you, with the DerivedData Exterminator.

Turbocharging Xcode

Not being the most verbose language in existence, Objective-C can use all the help it can get when it comes to autocompletion. Xcode does a lot of heavy lifting when it comes to class and method completion, but these plugins extend it even further:

Autocomplete switch Statements

Fact: switch statements and NS_ENUM go together like mango and sweet sticky rice. The only way it could be improved would be with SCXcodeSwitchExpander with automagically fills out a case statement for each value in the enumeration.

Autocomplete Documentation

Documentation adds a great deal of value to a code base, but it’s a tough habit to cultivate. The VVDocumenter-Xcode plugin does a great deal to reduce the amount of work necessary to add appledoc-compatible header documentation. Install it and wrap your code in a loving lexical embrace.

Formatting Xcode

“Code organization is a matter of hygiene”, so you owe it to yourself and your team to keep whitespace consistent in your code base. Make it easier on yourself by automating the process with these plugins.

Code Formatting with ClangFormat

ClangFormat-Xcode is a convenient wrapper around the ClangFormat tool, which automatically formats whitespace according to a specified set of style guidelines. Eliminate begrudging formatting commits forever with this plugin.

Statement Alignment

Fancy yourself a code designer, automated formatters be damned? XAlign automatically aligns assignments just so, to appease your most egregious OCD tendencies.

Extending Xcode

In a similar vein to what Bret Victor writes about Learnable Programming, these plugins push the boundaries of what we should expect from our editors, adding context and understanding to code without obscuring the meaning.

Inspect NSColor / UIColor Instances

Telling what a color is from its RGB values alone is a hard-won skill, so faced with an NSColor or UIColor value, we have little recourse to know what it’ll look like until the code is built and run. Enter ColorSense for Xcode

Quoth the README:

When you put the caret on one of your colors, it automatically shows the actual color as an overlay, and you can even adjust it on-the-fly with the standard OS X color picker.

Autocomplete Images from Project Bundle

Similar to the ColorSense plugin, KSImageNamed will preview and autocomplete images in [UIImage imageNamed:] declarations.

Semantics Highlighting

Any editor worth its salt is expected to have some form of syntax highlighting. But this recent post by Evan Brooks presents the idea of semantic highlighting in editors. The idea is that each variable within a scope would be assigned a particular color, which would be consistent across references. This way, one could easily tell the difference between two instance variables in the same method.

Polychromatic is a fascinating initial implementation of this for Xcode, and worth a look. The one downside is that this plugin requires the use of special desaturated color schemes—something that may be addressed in a future release, should this idea of semantic highlighting start to pick up mind share.

Localization

It’s no secret that NSHipster has a soft spot for localization. For this reason, this publication is emphatic in its recommendation of Lin, a clever Xcode plugin that brings the localization editor to your code.

Xcode’s plugin architecture is based on a number of private frameworks specific to Xcode, including DVTKit & IDEKit. A complete list can be derived by running class-dump on the Xcode app bundle.

Using private frameworks would be, of course, verboten on the AppStore, but since plugins aren’t distributed through these channels, developers are welcome to use whatever they want, however they want to.

To get started on your own plugin, download the Xcode5 Plugin Template, using the other available plugins and class-dump’d headers as a guide for what can be done, and how to do it.

Since time immemorial, iOS developers have been perplexed by a singular question:

“How do you resize an image?”

It’s a question of beguiling clarity, spurred on by a mutual mistrust of developer and platform. Myriad code samples litter Stack Overflow, each claiming to be the One True Solution™ — all others, mere pretenders.

In this week’s article, we’ll look at 5 distinct techniques to image resizing on iOS (and macOS, making the appropriate UIImage→ NSImage conversions). But rather than prescribe a single approach for every situation, we’ll weigh ergonomics against performance benchmarks to better understand when to use one approach over another.

When and Why to Scale Images

Before we get too far ahead of ourselves, let’s establish why you’d need to resize images in the first place. After all, UIImageView automatically scales and crops images according to the behavior specified by its contentMode property. And in the vast majority of cases, .scaleAspectFit, .scaleAspectFill, or .scaleToFill provides exactly the behavior you need.

imageView.contentMode=.scaleAspectFitimageView.image=image

So when does it make sense to resize an image?
When it’s significantly larger than the image view that’s displaying it.

Consider this stunning image of the Earth, from NASA’s Visible Earth image catalog:

At its full resolution, this image measures 12,000 px square and weighs in at a whopping 20 MB of JPEG data. 20MB of memory is nothing on today’s hardware, but that’s just its compressed size. To display it, the UIImageView needs to decode that JPEG into a bitmap. Set that full-sized image on an image view as-is, and your app’s memory usage will balloon to hundreds of Megabytes of memory, with no appreciable benefit to the user (a screen can only display so many pixels, after all). Not only that, because that’s happening on the main thread, it can cause your app to freeze for a couple seconds.

By simply resizing that image to the size of the image view before setting its image property, you can use an order-of-magnitude less RAM and CPU time:

This technique is known as downsampling, and can significantly improve the performance of your app in these kinds of situations. If you’re interested in some more information about downsampling and other image and graphics best practices, please refer to this excellent session from WWDC 2018.

Now, few apps would ever try to load an image this large… but it’s not too far off from some of the assets I’ve gotten back from design. (Seriously, a 10MB PNG of a color gradient?) So with that in mind, let’s take a look at the various ways that you can go about resizing and downsampling images.

Image Resizing Techniques

There are a number of different approaches to resizing an image, each with different capabilities and performance characteristics. And the examples we’re looking at in this article span frameworks both low- and high-level, from Core Graphics, vImage, and Image I/O to Core Image and UIKit:

1. Drawing to a UIGraphicsImageRenderer
2. Drawing to a Core Graphics Context
3. Creating a Thumbnail with Image I/O
4. Lanczos Resampling with Core Image
5. Image Scaling with vImage

For consistency, each of the following techniques share a common interface:

funcresizedImage(aturl:URL,forsize:CGSize)->UIImage?{...}imageView.image=resizedImage(at:url,for:size)

Here, size is a measure of point size, rather than pixel size. To calculate the equivalent pixel size for your resized image, scale the size of your image view frame by the scale of your main UIScreen:

letscaleFactor=UIScreen.main.scaleletscale=CGAffineTransform(scaleX:scaleFactor,y:scaleFactor)letsize=imageView.bounds.size.applying(scale)

Technique #1: Drawing to a UIGraphicsImageRenderer

The highest-level APIs for image resizing are found in the UIKit framework. Given a UIImage, you can draw into a UIGraphicsImageRenderer context to render a scaled-down version of that image:

importUIKit// Technique #1funcresizedImage(aturl:URL,forsize:CGSize)->UIImage?{guardletimage=UIImage(contentsOfFile:url.path)else{returnnil}letrenderer=UIGraphicsImageRenderer(size:size)returnrenderer.image{(context)inimage.draw(in:CGRect(origin:.zero,size:size))}}

UIGraphicsImageRenderer is a relatively new API, introduced in iOS 10 to replace the older, UIGraphicsBeginImageContextWithOptions / UIGraphicsEndImageContext APIs. You construct a UIGraphicsImageRenderer by specifying a point size. The image method takes a closure argument and returns a bitmap that results from executing the passed closure. In this case, the result is the original image scaled down to draw within the specified bounds.

Technique #2: Drawing to a Core Graphics Context

Core Graphics / Quartz 2D offers a lower-level set of APIs that allow for more advanced configuration.

Given a CGImage, a temporary bitmap context is used to render the scaled image, using the draw(_:in:) method:

importUIKitimportCoreGraphics// Technique #2funcresizedImage(aturl:URL,forsize:CGSize)->UIImage?{guardletimageSource=CGImageSourceCreateWithURL(urlasNSURL,nil),letimage=CGImageSourceCreateImageAtIndex(imageSource,0,nil)else{returnnil}letcontext=CGContext(data:nil,width:Int(size.width),height:Int(size.height),bitsPerComponent:image.bitsPerComponent,bytesPerRow:image.bytesPerRow,space:image.colorSpace??CGColorSpace(name:CGColorSpace.sRGB)!,bitmapInfo:image.bitmapInfo.rawValue)context?.interpolationQuality=.highcontext?.draw(image,in:CGRect(origin:.zero,size:size))guardletscaledImage=context?.makeImage()else{returnnil}returnUIImage(cgImage:scaledImage)}

This CGContext initializer takes several arguments to construct a context, including the desired dimensions and the amount of memory for each channel within a given color space. In this example, these parameters are fetched from the CGImage object. Next, setting the interpolationQuality property to .high instructs the context to interpolate pixels at a 👌 level of fidelity. The draw(_:in:) method draws the image at a given size and position, a allowing for the image to be cropped on a particular edge or to fit a set of image features, such as faces. Finally, the makeImage() method captures the information from the context and renders it to a CGImage value (which is then used to construct a UIImage object).

Technique #3: Creating a Thumbnail with Image I/O

Image I/O is a powerful (albeit lesser-known) framework for working with images. Independent of Core Graphics, it can read and write between many different formats, access photo metadata, and perform common image processing operations. The framework offers the fastest image encoders and decoders on the platform, with advanced caching mechanisms — and even the ability to load images incrementally.

The important CGImageSourceCreateThumbnailAtIndex offers a concise API with different options than found in equivalent Core Graphics calls:

importImageIO// Technique #3funcresizedImage(aturl:URL,forsize:CGSize)->UIImage?{letoptions:[CFString:Any]=[kCGImageSourceCreateThumbnailFromImageIfAbsent:true,kCGImageSourceCreateThumbnailWithTransform:true,kCGImageSourceShouldCacheImmediately:true,kCGImageSourceThumbnailMaxPixelSize:max(size.width,size.height)]guardletimageSource=CGImageSourceCreateWithURL(urlasNSURL,nil),letimage=CGImageSourceCreateThumbnailAtIndex(imageSource,0,optionsasCFDictionary)else{returnnil}returnUIImage(cgImage:image)}

Given a CGImageSource and set of options, the CGImageSourceCreateThumbnailAtIndex(_:_:_:) function creates a thumbnail of an image. Resizing is accomplished by the kCGImageSourceThumbnailMaxPixelSize option, which specifies the maximum dimension used to scale the image at its original aspect ratio. By setting either the kCGImageSourceCreateThumbnailFromImageIfAbsent or kCGImageSourceCreateThumbnailFromImageAlways option, Image I/O automatically caches the scaled result for subsequent calls.

Technique #4: Lanczos Resampling with Core Image

Core Image provides built-in Lanczos resampling functionality by way of the eponymous CILanczosScaleTransform filter. Although arguably a higher-level API than UIKit, the pervasive use of key-value coding in Core Image makes it unwieldy.

That said, at least the pattern is consistent.

The process of creating a transform filter, configuring it, and rendering an output image is no different from any other Core Image workflow:

importUIKitimportCoreImageletsharedContext=CIContext(options:[.useSoftwareRenderer:false])// Technique #4funcresizedImage(aturl:URL,scale:CGFloat,aspectRatio:CGFloat)->UIImage?{guardletimage=CIImage(contentsOf:url)else{returnnil}letfilter=CIFilter(name:"CILanczosScaleTransform")filter?.setValue(image,forKey:kCIInputImageKey)filter?.setValue(scale,forKey:kCIInputScaleKey)filter?.setValue(aspectRatio,forKey:kCIInputAspectRatioKey)guardletoutputCIImage=filter?.outputImage,letoutputCGImage=sharedContext.createCGImage(outputCIImage,from:outputCIImage.extent)else{returnnil}returnUIImage(cgImage:outputCGImage)}

The Core Image filter named CILanczosScaleTransform accepts an inputImage, an inputScale, and an inputAspectRatio parameter, each of which are pretty self-explanatory.

More interestingly, a CIContext is used here to create a UIImage (by way of a CGImageRef intermediary representation), since UIImage(CIImage:) doesn’t often work as expected. Creating a CIContext is an expensive operation, so a cached context is used for repeated resizing.

Technique #5: Image Scaling with vImage

Last up, it’s the venerable Accelerate framework— or more specifically, the vImage image-processing sub-framework.

vImage comes with a bevy of different functions for scaling an image buffer. These lower-level APIs promise high performance with low power consumption, but at the cost of managing the buffers yourself (not to mention, signficantly more code to write):

importUIKitimportAccelerate.vImage// Technique #5funcresizedImage(aturl:URL,forsize:CGSize)->UIImage?{// Decode the source imageguardletimageSource=CGImageSourceCreateWithURL(urlasNSURL,nil),letimage=CGImageSourceCreateImageAtIndex(imageSource,0,nil),letproperties=CGImageSourceCopyPropertiesAtIndex(imageSource,0,nil)as?[CFString:Any],letimageWidth=properties[kCGImagePropertyPixelWidth]as?vImagePixelCount,letimageHeight=properties[kCGImagePropertyPixelHeight]as?vImagePixelCountelse{returnnil}// Define the image formatvarformat=vImage_CGImageFormat(bitsPerComponent:8,bitsPerPixel:32,colorSpace:nil,bitmapInfo:CGBitmapInfo(rawValue:CGImageAlphaInfo.first.rawValue),version:0,decode:nil,renderingIntent:.defaultIntent)varerror:vImage_Error// Create and initialize the source buffervarsourceBuffer=vImage_Buffer()defer{sourceBuffer.data.deallocate()}error=vImageBuffer_InitWithCGImage(&sourceBuffer,&format,nil,image,vImage_Flags(kvImageNoFlags))guarderror==kvImageNoErrorelse{returnnil}// Create and initialize the destination buffervardestinationBuffer=vImage_Buffer()error=vImageBuffer_Init(&destinationBuffer,vImagePixelCount(size.height),vImagePixelCount(size.width),format.bitsPerPixel,vImage_Flags(kvImageNoFlags))guarderror==kvImageNoErrorelse{returnnil}// Scale the imageerror=vImageScale_ARGB8888(&sourceBuffer,&destinationBuffer,nil,vImage_Flags(kvImageHighQualityResampling))guarderror==kvImageNoErrorelse{returnnil}// Create a CGImage from the destination bufferguardletresizedImage=vImageCreateCGImageFromBuffer(&destinationBuffer,&format,nil,nil,vImage_Flags(kvImageNoAllocate),&error)?.takeRetainedValue(),error==kvImageNoErrorelse{returnnil}returnUIImage(cgImage:resizedImage)}

The Accelerate APIs used here clearly operate at a much lower-level than any of the other resizing methods discussed so far. But get past the unfriendly-looking type and function names, and you’ll find that this approach is rather straightforward.

• First, create a source buffer from your input image,
• Then, create a destination buffer to hold the scaled image
• Next, scale the image data in the source buffer to the destination buffer,
• Finally, create an image from the resulting image data in the destination buffer.

Performance Benchmarks

So how do these various approaches stack up to one another?

Here are the results of some performance benchmarks performed on an iPhone 7 running iOS 12.2, in this project.

The following numbers show the average runtime across multiple iterations for loading, scaling, and displaying that jumbo-sized picture of the earth from before:

¹  Results were consistent across different values of CGInterpolationQuality, with negligible differences in performance benchmarks.

²  Setting kCIContextUseSoftwareRenderer to true on the options passed on CIContext creation yielded results an order of magnitude slower than base results.

Conclusions

• UIKit, Core Graphics, and Image I/O all perform well for scaling operations on most images. If you had to choose one (on iOS, at least), UIGraphicsImageRenderer is typically your best bet.
• Core Image is outperformed for image scaling operations. In fact, according to Apple’s Performance Best Practices section of the Core Image Programming Guide, you should use Core Graphics or Image I/O functions to crop and downsampling images instead of Core IMage.
• Unless you’re already working with vImage, the extra work necessary to use the low-level Accelerate APIs probably isn’t justified in most circumstances.

Software development best practices prescribe strict separation of configuration from code. Yet developers on Apple platforms often struggle to square these guidelines with Xcode’s project-heavy workflow.

Understanding what each project setting does and how they all interact with one another is a skill that can take years to hone. And the fact that much of this information is buried deep within the GUIs os Xcode does us no favors.

Navigate to the “Build Settings” tab of the project editor, and you’ll be greeted by hundreds of build settings spread across layers of projects, targets, and configurations — and that’s to say nothing of the other six tabs!

Fortunately, there’s a better way to manage all of this configuration that doesn’t involve clicking through a maze of tabs and disclosure arrows.

This week, we’ll show you how you can use text-based xcconfig files to externalize build settings from Xcode to make your projects more compact, comprehensible, and powerful.

Xcode build configuration files, more commonly known by their xcconfig file extension, allow build settings for your app to be declared and managed without Xcode. They’re plain text, which means they’re much friendlier to source control systems and can be modified with any editor.

Fundamentally, each configuration file consists of a sequence of key-value assignments with the following syntax:

BUILD_SETTING_NAME = value

For example, to specify the Swift language version for a project, you’d specify the SWIFT_VERSION build setting like so:

SWIFT_VERSION = 5.0
        

At first glance, xcconfig files bear a striking resemblance to .env files, with their simple, newline-delimited syntax. But there’s more to Xcode build configuration files than meets the eye. Behold!

Retaining Existing Values

To append rather than replace existing definitions, use the $(inherited) variable like so:

BUILD_SETTING_NAME = $(inherited)additional value

You typically do this to build up lists of values, such as the paths in which the compiler searches for frameworks to find included header files (FRAMEWORK_SEARCH_PATHS):

FRAMEWORK_SEARCH_PATHS = $(inherited) $(PROJECT_DIR)
        

Xcode assigns inherited values in the following order (from lowest to highest precedence):

• Platform Defaults
• Xcode Project File Build Settings
• xcconfig File for the Xcode Project
• Active Target Build Settings
• xcconfig File for the Active Target

Referencing Values

You can substitute values from other settings by their declaration name with the following syntax:

BUILD_SETTING_NAME = $(ANOTHER_BUILD_SETTING_NAME)
        

Substitutions can be used to define new variables according to existing values, or inline to build up new values dynamically.

OBJROOT = $(SYMROOT)
        CONFIGURATION_BUILD_DIR = $(BUILD_DIR)/$(CONFIGURATION)-$(PLATFORM_NAME)
        

Conditionalizing

You can conditionalize build settings according to their SDK (sdk), architecture (arch), and / or configuration (config) according to the following syntax:

BUILD_SETTING_NAME[sdk=sdk] = value for specified sdkBUILD_SETTING_NAME[arch=architecture] = value for specified architectureBUILD_SETTING_NAME[config=configuration] = value for specified configuration

Given a choice between multiple definitions of the same build setting, the compiler resolves according to specificity.

BUILD_SETTING_NAME[sdk=sdk][arch=architecture] = value for specified sdk and architecturesBUILD_SETTING_NAME[sdk=*][arch=architecture] = value for all other sdks with specified architecture

For example, you might specify the following build setting to speed up local builds by only compiling for the active architecture:

ONLY_ACTIVE_ARCH[config=Debug][sdk=*][arch=*] = YES
        

Including Settings from Other Configuration Files

A build configuration file can include settings from other configuration files using the same #include syntax as the equivalent C directive on which this functionality is based:

#include "path/to/File.xcconfig"

As we’ll see later on in the article, you can take advantage of this to build up cascading lists of build settings in really powerful ways.

Creating Build Configuration Files

To create a build configuration file, select the “File > New File…” menu item (⌘N), scroll down to the section labeled “Other”, and select the Configuration Settings File template. Next, save it somewhere in your project directory, making sure to add it to your desired targets

Once you’ve created an xcconfig file, you can assign it to one or more build configurations for its associated targets.

Now that we’ve covered the basics of using Xcode build configuration files let’s look at a couple of examples of how you can use them to manage development, stage, and production environments.

Customizing App Name and Icon for Internal Builds

Developing an iOS app usually involves juggling various internal builds on your simulators and test devices (as well as the latest version from the App Store, to use as a reference).

You can make things easier on yourself with xcconfig files that assign each configuration a distinct name and app icon.

// Development.xcconfig
        PRODUCT_NAME = $(inherited) α
        ASSETCATALOG_COMPILER_APPICON_NAME = AppIcon-Alpha
        ---
        // Staging.xcconfig
        PRODUCT_NAME = $(inherited) β
        ASSETCATALOG_COMPILER_APPICON_NAME = AppIcon-Beta
        

Managing Constants Across Different Environments

If your backend developers comport themselves according to the aforementioned 12 Factor App philosophy, then they’ll have separate endpoints for development, stage, and production environments.

On iOS, perhaps the most common approach to managing these environments is to use conditional compilation statements with build settings like DEBUG.

importFoundation#if DEBUG
        let apiBaseURL = URL(string: "https://api.example.dev")!letapiKey="9e053b0285394378cf3259ed86cd7504"#else
        let apiBaseURL = URL(string: "https://api.example.com")!letapiKey="4571047960318d233d64028363dfa771"#endif
        

This gets the job done, but runs afoul of the canon of code / configuration separation.

An alternative approach takes these environment-specific values and puts them where they belong — into xcconfig files.

# Development.xcconfig
        API_BASE_URL = api.example.dev
        API_KEY = 9e053b0285394378cf3259ed86cd7504
        ---
        # Production.xcconfig
        API_BASE_URL = api.example.com
        API_KEY = 4571047960318d233d64028363dfa771
        

However, to pull these values programmatically, we’ll need to take one additional step:

Accessing Build Settings from Swift

Build settings defined by the Xcode project file, xcconfig files, and environment variables, are only available at build time. When you run the compiled app, none of that surrounding context is available. (And thank goodness for that!)

But wait a sec — don’t you remember seeing some of those build settings before in one of those other tabs? Info, was it?

As it so happens, that info tab is actually just a fancy presentation of the target’s Info.plist file. At build time, that Info.plist file is compiled according to the build settings provided and copied into the resulting app bundle. Therefore, by adding references to $(API_BASE_URL) and $(API_KEY), you can access the values for those settings through the infoDictionary property of Foundation’s Bundle API. Neat!

Following this approach, we might do something like the following:

importFoundationenumConfiguration{staticfuncvalue<T>(forkey:String)->T{guardletvalue=Bundle.main.infoDictionary?[key]as?Telse{fatalError("Invalid or missing Info.plist key: \(key)")}returnvalue}}enumAPI{staticvarbaseURL:URL{returnURL(string:"https://"+Configuration.value(for:"API_BASE_URL"))!}staticvarkey:String{returnConfiguration.value(for:"API_KEY")}}

When viewed from the call site, we find that this approach harmonizes beautifully with our best practices — not a single hard-coded constant in sight!

leturl=URL(string:path,relativeTo:API.baseURL)!varrequest=URLRequest(url:url)request.httpMethod=methodrequest.addValue(API.key,forHTTPHeaderField:"X-API-KEY")

Xcode projects are monolithic, fragile, and opaque. They’re a source of friction for collaboration among team members and generally a drag to work with.

Fortunately, xcconfig files go a long way to address these pain points. Moving configuration out of Xcode and into xcconfig files confers a multitude of benefits and offers a way to distance your project from the particulars of Xcode without leaving a Cupertino-approved happy path.

I just left a hipster coffee shop. It was packed with iOS devs, whispering amongst each other about how they can’t wait for Apple to release an official style guide and formatter for Swift.

Lately, the community has been buzzing about the proposal from Tony Allevato and Dave Abrahams to adopt an official style guide and formatting tool for the Swift language.

Hundreds of community members have weighed in on the initial pitch and proposal. As with all matters of style, opinions are strong, and everybody has one. Fortunately, the discourse from the community has been generally constructive and insightful, articulating a diversity of viewpoints, use cases, and concerns.

Since our article was first published back in March, the proposal, “SE-0250: Swift Code Style Guidelines and Formatter” started formal review; that process was later suspended, to be reconsidered sometime in the future.

In spite of this, Swift code formatting remains a topic of interest to many developers. So this week on NSHipster, we’re taking another look at the current field of Swift formatters available today — including the swift-format tool released as part of the proposal — and see how they all stack up. From there, we’ll take a step back and try to put everything in perspective.

But first, let’s start with a question:

What is Code Formatting?

For our purposes, we’ll define code formatting as any change made to code that makes it easier to understand without changing its behavior. Although this definition extends to differences in equivalent forms, (e.g. [Int] vs. Array<Int>), we’ll limit our discussion here to whitespace and punctuation.

Swift, like many other programming languages, is quite liberal in its acceptance of newlines, tabs, and spaces. Most whitespace is insignificant, having no effect on the code around from the compiler’s point of view.

When we use whitespace to make code more comprehensible without changing its behavior, that’s an example of secondary notation; the primary notation, of course, being the code itself.

Put enough semicolons in the right places, and you can write pretty much anything in a single line of code. But all things being equal, why not use horizontal and vertical whitespace to visually structure code in a way that’s easier for us to understand, right?

Unfortunately, the ambiguity created by the compiler’s accepting nature of whitespace can often cause confusion and disagreement among programmers: “Should I add a newline before a curly bracket? How do I break up statements that extend beyond the width of the editor?”

Organizations often codify guidelines for how to deal with these issues, but they’re often under-specified, under-enforced, and out-of-date. The role of a code formatter is to automatically enforce a set of conventions so that programmers can set aside their differences and get to work solving actual problems.

Formatter Tool Comparison

The Swift community has considered questions of style from the very beginning. Style guides have existed from the very first days of Swift, as have various open source tools to automate the process of formatting code to match them.

To get a sense of the current state of Swift code formatters, we’ll take a look at the following four tools:

To establish a basis of comparison, we’ve contrived the following code sample to evaluate each tool (using their default configuration):

structShippingAddress:Codable{varrecipient:StringvarstreetAddress:Stringvarlocality:Stringvarregion:String;varpostalCode:Stringvarcountry:Stringinit(recipient:String,streetAddress:String,locality:String,region:String,postalCode:String,country:String){self.recipient=recipientself.streetAddress=streetAddressself.locality=localityself.region=region;self.postalCode=postalCodeguardcountry.count==2,country==country.uppercased()else{fatalError("invalid country code")}self.country=country}}letapplePark=ShippingAddress(recipient:"Apple, Inc.",streetAddress:"1 Apple Park Way",locality:"Cupertino",region:"CA",postalCode:"95014",country:"US")

Although code formatting encompasses a wide range of possible syntactic and semantic transformations, we’ll focus on newlines and indentation, which we believe to be baseline requirements for any code formatter.

SwiftFormat

First up is SwiftFormat, a tool as helpful as it is self-descriptive.

Installation

SwiftFormat is distributed via Homebrew as well as Mint and CocoaPods.

You can install it by running the following command:

$ brew install swiftformat
        

In addition, SwiftFormat also provides an Xcode Source Editor Extension, found in the EditorExtension, which you can use to reformat code in Xcode. Or, if you’re a user of VSCode, you can invoke SwiftFormat with this plugin.

Usage

The swiftformat command formats each Swift file found in the specified file and directory paths.

$ swiftformat Example.swift
        

SwiftFormat has a variety of rules that can be configured either individually via command-line options or using a configuration file.

Example Output

Running the swiftformat command on our example using the default set of rules produces the following result:

// swiftformat version 0.40.8structShippingAddress:Codable{varrecipient:StringvarstreetAddress:Stringvarlocality:Stringvarregion:String;varpostalCode:Stringvarcountry:Stringinit(recipient:String,streetAddress:String,locality:String,region:String,postalCode:String,country:String){self.recipient=recipientself.streetAddress=streetAddressself.locality=localityself.region=region;self.postalCode=postalCodeguardcountry.count==2,country==country.uppercased()else{fatalError("invalid country code")}self.country=country}}letapplePark=ShippingAddress(recipient:"Apple, Inc.",streetAddress:"1 Apple Park Way",locality:"Cupertino",region:"CA",postalCode:"95014",country:"US")

As you can see, this is a clear improvement over the original. Each line is indented according to its scope, and each declaration has consistent spacing between punctuation. Both the semicolon in the property declarations and the newline in the initializer parameters are preserved; however, the closing curly braces aren’t moved to separate lines as might be expectedthis is fixed in 0.39.5. Great work, Nick!

Performance

SwiftFormat is consistently the fastest of the tools tested in this article, completing in a few milliseconds.

$time swiftformat Example.swift
                0.03 real         0.01 user         0.01 sys
        

SwiftLint

Next up is, SwiftLint, a mainstay of the Swift open source community. With over 100 built-in rules, SwiftLint can perform a wide variety of checks on your code — everything from preferring AnyObject over class for class-only protocols to the so-called “Yoda condition rule”, which prescribes variables to be placed on the left-hand side of comparison operators (that is, if n == 42 not if 42 == n).

As its name implies, SwiftLint is not primarily a code formatter; it’s really a diagnostic tool for identifying convention violation and API misuse. However, by virtue of its auto-correction faculties, it’s frequently used to format code.

Installation

You can install SwiftLint using Homebrew with the following command:

$ brew install swiftlint
        

Alternatively, you can install SwiftLint with CocoaPods, Mint, or as a standalone installer package (.pkg).

Usage

To use SwiftLint as a code formatter, run the autocorrect subcommand passing the --format option and the files or directories to correct.

$ swiftlint autocorrect --format--path Example.swift
        

Example Output

Running the previous command on our example yields the following:

// swiftlint version 0.32.0structShippingAddress:Codable{varrecipient:StringvarstreetAddress:Stringvarlocality:Stringvarregion:String;varpostalCode:Stringvarcountry:Stringinit(recipient:String,streetAddress:String,locality:String,region:String,postalCode:String,country:String){self.recipient=recipientself.streetAddress=streetAddressself.locality=localityself.region=region;self.postalCode=postalCodeguardcountry.count==2,country==country.uppercased()else{fatalError("invalid country code")}self.country=country}}letapplePark=ShippingAddress(recipient:"Apple, Inc.",streetAddress:"1 Apple Park Way",locality:"Cupertino",region:"CA",postalCode:"95014",country:"US")

SwiftLint cleans up the worst of the indentation and inter-spacing issues but leaves other, extraneous whitespace intact (though it does strip the file’s leading newline, which is nice). Again, it’s worth noting that formatting isn’t SwiftLint’s primary calling; if anything, it’s merely incidental to providing actionable code diagnostics. And taken from the perspective of “first, do no harm”, it’s hard to complain about the results here.

Performance

For everything that SwiftLint checks for, it’s remarkably snappy — completing in a fraction of a second for our example.

$time swiftlint autocorrect --quiet--format--path Example.swift
                0.09 real         0.04 user         0.01 sys
        

Prettier with Swift Plugin

$ brew install yarn
        $ yarn global add prettier prettier/plugin-swift
        

$ prettier Example.swift
        

// Swift version 4.2// prettier version 1.17.1// prettier/plugin-swift version 0.0.0 (bdf8726)structShippingAddress:Codable{varrecipient:StringvarstreetAddress:Stringvarlocality:Stringvarregion:StringvarpostalCode:Stringvarcountry:Stringinit(recipient:String,streetAddress:String,locality:String,region:String,postalCode:String,country:String){self.recipient=recipientself.streetAddress=streetAddressself.locality=localityself.region=region;self.postalCode=postalCodeguardcountry.count==2,country==country.uppercased()else{fatalError("invalid country code")}self.country=country}}letapplePark=ShippingAddress(recipient:"Apple, Inc.",streetAddress:"1 Apple Park Way",locality:"Cupertino",region:"CA",postalCode:"95014",country:"US")

$time prettier Example.swift
                0.60 real         0.40 user         0.18 sys
        

swift-format

Having looked at the current landscape of available Swift formatters, we now have a reasonable baseline for evaluating the swift-format tool proposed by Tony Allevato and Dave Abrahams.

Installation

The code for swift-format is currently hosted on the format branch of Google’s fork of the Swift project. You can check it out and build it from source by running the following commands:

$ git clone https://github.com/google/swift.git swift-format
        $cd swift-format
        $ git submodule update --init$ swift build
        

For your convenience, we’re providing a Homebrew formula that builds from our own fork of Google’s fork, which you can install with the following command:

$ brew install nshipster/formulae/swift-format
        

Usage

Run the swift-format command, passing one or more file and directory paths to Swift files that you want to format.

$ swift-format Example.swift
        

The swift-format command also takes a --configuration option, which takes a path to a JSON file. For now, the easiest way to customize swift-format behavior is to dump the default configuration to a file and go from there.

$ swift-format -m dump-configuration .swift-format.json
        

Running the command above populates the specified file with the following JSON:

{"blankLineBetweenMembers":{"ignoreSingleLineProperties":true},"indentation":{"spaces":2},"lineBreakBeforeControlFlowKeywords":false,"lineBreakBeforeEachArgument":true,"lineLength":100,"maximumBlankLines":1,"respectsExistingLineBreaks":true,"rules":{"AllPublicDeclarationsHaveDocumentation":true,"AlwaysUseLowerCamelCase":true,"AmbiguousTrailingClosureOverload":true,"AvoidInitializersForLiterals":true,"BeginDocumentationCommentWithOneLineSummary":true,"BlankLineBetweenMembers":true,"CaseIndentLevelEqualsSwitch":true,"DoNotUseSemicolons":true,"DontRepeatTypeInStaticProperties":true,"FullyIndirectEnum":true,"GroupNumericLiterals":true,"IdentifiersMustBeASCII":true,"MultiLineTrailingCommas":true,"NeverForceUnwrap":true,"NeverUseForceTry":true,"NeverUseImplicitlyUnwrappedOptionals":true,"NoAccessLevelOnExtensionDeclaration":true,"NoBlockComments":true,"NoCasesWithOnlyFallthrough":true,"NoEmptyAssociatedValues":true,"NoEmptyTrailingClosureParentheses":true,"NoLabelsInCasePatterns":true,"NoLeadingUnderscores":true,"NoParensAroundConditions":true,"NoVoidReturnOnFunctionSignature":true,"OneCasePerLine":true,"OneVariableDeclarationPerLine":true,"OnlyOneTrailingClosureArgument":true,"OrderedImports":true,"ReturnVoidInsteadOfEmptyTuple":true,"UseEnumForNamespacing":true,"UseLetInEveryBoundCaseVariable":true,"UseOnlyUTF8":true,"UseShorthandTypeNames":true,"UseSingleLinePropertyGetter":true,"UseSpecialEscapeSequences":true,"UseSynthesizedInitializer":true,"UseTripleSlashForDocumentationComments":true,"ValidateDocumentationComments":true},"tabWidth":8,"version":1}

After fiddling with the configuration — such as setting lineLength to the correct value of 80 (don’t @ me)— you can apply it thusly:

$ swift-format Example.swift --configuration .swift-format.json
        

Example Output

Using its default configuration, here’s how swift-format formats our example:

// swift-format 0.0.1 (2019-05-15, 115870c)structShippingAddress:Codable{varrecipient:StringvarstreetAddress:Stringvarlocality:Stringvarregion:String;varpostalCode:Stringvarcountry:Stringinit(recipient:String,streetAddress:String,locality:String,region:String,postalCode:String,country:String){self.recipient=recipientself.streetAddress=streetAddressself.locality=localityself.region=regionself.postalCode=postalCodeguardcountry.count==2,country==country.uppercased()else{fatalError("invalid country code")}self.country=country}}letapplePark=ShippingAddress(recipient:"Apple, Inc.",streetAddress:"1 Apple Park Way",locality:"Cupertino",region:"CA",postalCode:"95014",country:"US")

Be still my heart!😍 We could do without the original semicolon, but overall, this is pretty unobjectionable — which is exactly what you’d want from an official code style tool.

importUIKit@UIApplicationMainclassAppDelegate:UIResponder,UIApplicationDelegate{varwindow:UIWindow?funcapplication(_application:UIApplication,didFinishLaunchingWithOptionslaunchOptions:[UIApplication.LaunchOptionsKey:Any]?)->Bool{leturl=URL(string:"https://nshipster.com/swift-format")!URLSession.shared.dataTask(with:url,completionHandler:{(data,response,error)inguarderror==nil,letdata=data,letresponse=responseas?HTTPURLResponse,(200..<300).contains(response.statusCode)else{fatalError(error?.localizedDescription??"Unknown error")}iflethtml=String(data:data,encoding:.utf8){print(html)}}).resume()// Override point for customization after application launch.returntrue}}

importUIKit@UIApplicationMainclassAppDelegate:UIResponder,UIApplicationDelegate{varwindow:UIWindow?funcapplication(_application:UIApplication,didFinishLaunchingWithOptionslaunchOptions:[UIApplication.LaunchOptionsKey:Any]?)->Bool{leturl=URL(string:"https://nshipster.com/swift-format")!URLSession.shared.dataTask(with:url,completionHandler:{(data,response,error)inguarderror==nil,letdata=data,letresponse=responseas?HTTPURLResponse,(200..<300).contains(response.statusCode)else{fatalError(error?.localizedDescription??"Unknown error")}iflethtml=String(data:data,encoding:.utf8){print(html)}}).resume()// Override point for customization after application launch.returntrue}}

importUIKit@UIApplicationMainclassAppDelegate:UIResponder,UIApplicationDelegate{varwindow:UIWindow?funcapplication(_application:UIApplication,didFinishLaunchingWithOptionslaunchOptions:[UIApplication.LaunchOptionsKey:Any]?)->Bool{leturl=URL(string:"https://nshipster.com/swift-format")!URLSession.shared.dataTask(with:url,completionHandler:{(data,response,error)inguarderror==nil,letdata=data,letresponse=responseas?HTTPURLResponse,(200..<300).contains(response.statusCode)else{fatalError(error?.localizedDescription??"Unknown error")}iflethtml=String(data:data,encoding:.utf8){print(html)}}).resume()// Override point for customization after application launch.returntrue}}

importUIKit@UIApplicationMainclassAppDelegate:UIResponder,UIApplicationDelegate{varwindow:UIWindow?funcapplication(_application:UIApplication,didFinishLaunchingWithOptionslaunchOptions:[UIApplication.LaunchOptionsKey:Any]?)->Bool{leturl=URL(string:"https://nshipster.com/swift-format")!URLSession.shared.dataTask(with:url,completionHandler:{(data,response,error)inguarderror==nil,letdata=data,letresponse=responseas?HTTPURLResponse,(200..<300).contains(response.statusCode)else{fatalError(error?.localizedDescription??"Unknown error")}iflethtml=String(data:data,encoding:.utf8){print(html)}}).resume()// Override point for customization after application launch.returntrue}}

importUIKit@UIApplicationMainclassAppDelegate:UIResponder,UIApplicationDelegate{varwindow:UIWindow?funcapplication(_application:UIApplication,didFinishLaunchingWithOptionslaunchOptions:[UIApplication.LaunchOptionsKey:Any]?)->Bool{leturl=URL(string:"https://nshipster.com/swift-format")!URLSession.shared.dataTask(with:url,completionHandler:{(data,response,error)inguarderror==nil,letdata=data,letresponse=responseas?HTTPURLResponse,(200..<300).contains(response.statusCode)else{fatalError(error?.localizedDescription??"Unknown error")}iflethtml=String(data:data,encoding:.utf8){print(html)}}).resume()// Override point for customization after application launch.returntrue}}

$time swift-format Example.swift
                0.24 real         0.16 user         0.14 sys
        

Apple’s press release announcing the company’s annual developer conference featured an illustration of a robot head (🤖) bursting with code symbols, emoji, and Apple iconography.

All last week, attendees saw this motif in slides and signage throughout McEnery Convention Center, with variations featuring heads of monkeys (🐵), aliens (👽), skulls (💀), and other Animoji characters.

Beyond presenting a compelling case for several 🤯-based additions to Unicode’s recommended emoji ZWJ sequences, these banners reinforced a central theme of the conference: “Write code. Blow minds.” Apple’s slogan was accurate but ambiguous; it wasn’t us that was writing code, but Apple. We were the ones getting our #mindsblown.

The problem with having your mind blown is that you can’t think straight.

Now that we’re safely removed from the Reality Distortion Field™ (some of us recovering from #dubdubflu🤒, perhaps), let’s take a moment to process the announcements from last week as a whole, and consider what they mean for next week, next month, next year, and the years to come.

SwiftUI, Swift, and Open Source

SwiftUI is the most exciting announcement from Apple since unveiling the Swift language itself five years prior.

That said, for a language being developed in the open with a rigorous process for vetting proposed changes, many of us in the community thought Swift was immune from surprise announcements at WWDC. For better or for worse, we were wrong.

At the Platforms State of the Union, few of us in the audience recognized the SwiftUI code. It looked like the Swift we know and love, but it had a bunch of new adornments and seemed to play fast and loose with our understanding of syntax rules.

importSwiftUIstructContent:View{@Statevarmodel=...varbody:someView{...}}

Even if you ardently followed the Swift Forums and knew about the proposals for property delegates, implicit returns for single-line expressions, and opaque result types… you still might struggle to make sense of everything you saw.

Apple’s language

The SwiftUI announcement serves a reminder that Swift is Apple’s language.

Fortunately, this arrangement has worked out pretty well so far — thanks in large part to good faith efforts from Apple engineers to communicate openly and take their responsibility as stewards of the language seriously. Case in point: within hours of the Keynote, Swift’s project leader, Ted Kremenek, posted a message outlining the situation, and proposals for the new features were submitted for review the same day (though one might wonder what that means in practice). Also, to their credit, the rest of the Core Team has done an outstanding job communicating with attendees at labs and answering questions on social media.

What happened at WWDC this year underscores a central tension between open community-driven contributions and the closed product-driven development within Apple. There’s already an active discussion about how this dynamic can and should play out for SwiftUI and Combine.

Ultimately, it’s up to Apple to decide whether these technologies will be incorporated into the Swift open source project. However, I’m optimistic that they’ll make the right choice in due course.

SwiftUI, Catalyst, and the Long-Term Viability of Apple Platforms

I don’t think it’s an exaggeration to say that Apple’s announcements of Catalyst and SwiftUI this year saved macOS from becoming obsolete as a platform.

With AppKit’s increasing irrelevance in the era of UIKit, few businesses have been able to justify investment into native macOS apps. As a result, the macOS ecosystem has languished, becoming a shadow of its glory days of the delicious generation.

At WWDC, Apple laid out a clear path forward for developers:

• If you’re working on an existing iOS app, focus on making the most of the new features on iOS 13, like Dark Mode support and Sign In with Apple ID.
• If you have an iPad app, consider adding support for macOS Catalina by way of Catalyst.
• If you’re creating your n+1^th  app, weigh the potential benefit of adopting SwiftUI against the costs and risks associated with developing with new technologies (this calculation will change over time).
• If you’re looking to break into app development, or want to experiment, start a new Xcode project, check the box next to SwiftUI, and have a blast! There’s never been a better time to try everything out.

That’s essentially the decision tree Apple would have us follow.

As others have eloquently opined, SwiftUI marks an important transition for Apple as a company from the NeXT era to the Swift era. By way of historical analogy:

• Swift is the new Objective-C
  
• SwiftUI is the new Cocoa
  
• Catalyst is the new Carbon
  

However, something’s missing from this narrative of how we got from Macintosh OS to Mac OS X.

What about Java(Script)?

Everyone knows Java was deprecated in Mac OS X 10.4.
What this section presupposes is… maybe it didn’t?

The transition from C to Objective-C may seem inevitable today, but at the time, there was a real possibility that Objective-C would be replaced by a more popular language — namely, Java.

The situation in 2019 bears a striking resemblance to what happened in 1999.

With web technologies only becoming more capable and convenient over time, can you really blame them for going with a “hybrid solution” — especially one that promises to target every platform with a single code base?

We must remember that the purpose of software is to solve problems. Consumers only care about which technologies we decide to use insofar as it provides a better solution, more quickly, at a lower price.

Yes, there are plenty of examples of cross-platform or web-based technologies that look and feel janky and out of place on the Mac or an iPhone. But there are plenty of instances where the results are good (or at least “good enough”).

Don’t let perfect be the enemy of good.

Or, put another way:

1GB of RAM for an Electron app isn’t great, but it’s still better than the 0GB of RAM for a native app that never ships.

Thinking outside the App Store

On the heels of Catalyst’s official debut, Twitter announced plans to port its iPad app to the Mac.

Apple’s exciting new technology empowers Twitter to easily bring our entire 1.5 million line code base from iOS to the Mac, allowing ongoing full feature parity with our iPad app, and enhanced with the macOS experience that will make Twitter feel right at home on your Mac. @TwitterSupport

In fact, you don’t need to wait for macOS Catalina — you can experience Twitter as a native desktop app today! The latest version of Chrome lets you install progressive web apps (PWAs), like Twitter, as native desktop apps.

Go ahead and try it for yourself: open https://twitter.com/ in Chrome, click the ⠇ icon on the far right side of your address bar and select “Install Twitter”.

Android has a similar feature that generates and installs a native app from a web app manifest— all without ever leaving the browser. Meanwhile, the Google Play Store has started to become more browser-like itself; with instant apps and games, that can be launched immediately, without installing the full payload.

And lest you think this is just a Google thing, Apple has also (quietly) improved its own support of PWAs over the years. iOS 12.2, in particular, was a huge step forward, addressing some of the most pressing shortcomings on the platform. And the first iOS 13 beta promises to be even better for PWAs (though you’d never know it based on this year’s conference sessions).

We’re not quite there yet, but with forthcoming support for Web App Manifest in WebKit, we’re getting really close.

When the iPhone first debuted in 2007, the intent was for 3rd-party developers to distribute software through web apps. The strong distinction between native and web apps is a product of history, not an immutable truth about software. When you think about the future of “apps”, you have to wonder if this distinction will still make sense in 5 or 10 years. Aside from ubiquitous high-speed wireless internet, there’s nothing particularly futuristic about downloading a 50MB payload from the App Store.

Apple, Politics, and the Global Economy

Apple’s transition from the NeXT era to the Swift era goes beyond technical changes within the company.

The day after delivering the WWDC Keynote, Tim Cook sat down for an interview with CBS News, in which he defended Apple against allegations of monopolistic behavior. A month prior, the U.S. Supreme Court issued a decision in Apple Inc. v. Pepper affirming that consumers were “direct purchasers” of apps from the App Store, and could sue Apple for antitrust practices. All of this at a time when there’s growing political momentum in the U.S. to break up big tech companies like Google, Amazon, Facebook, and Apple.

Meanwhile, slowing iPhone sales in the U.S. and Europe, difficulty entering emerging markets in China and India, and the threat of a prolonged U.S. / China trade war loom large over Apple’s future.

For the past decade, the App Store has shielded many of us from the complexities of doing business with the promise of being able to build an app and carve out a livelihood. To the extent that this was ever true, we may soon have to confront some deeply held assumptions about our industry.

This is all to say that there’s a big world outside the Apple ecosystem.

I don’t doubt that SwiftUI is the future of macOS and iOS development. I’m thrilled that Apple is embracing a declarative UI paradigm on its platforms, and couldn’t be more excited for functional reactive ideas to spread to millions of new developers as a result.

I just worry that fixating on SwiftUI will come at the expense of solving more important problems.

Mind the Enthusiasm Gap

At the time of writing, SwiftUI has been public for what… like a week? And yet, if you haven’t spent every waking hour playing with SwiftUI, you might have the impression that you’re already too late.

Before you drop everything to catch up on session videos or start to feel bad for “falling behind,” remember that we’ve been here before.

The Swift programming language took a long time to become viable for app development. Years. Today, Swift 5 is barely recognizable from what we first saw in 2014.

All of those developers who rushed to learn it when it first came out (myself included) how many of us look back on all of that code churn fondly? How many teams would have been better off holding onto their Objective-C code bases for a few more years instead of deciding to rewrite everything from scratch at the first chance?

By all means, try out Xcode 11 on the latest macOS Catalina beta to appreciate the full extent of its live canvas. It’s insanely great!

But don’t feel beholden to it. Don’t upend your work for the sake of staying ahead of the curve. There are plenty of other things that you can focus on now that will have a more immediate impact on your users and your own career.

Silver Bullets and Universal Truths

SwiftUI solves some of the most visible problems facing Apple platforms, but they aren’t the most important or the most difficult ones — not by a long shot.

Taking care of yourself — sleeping enough, eating right, exercising regularly — will do more to improve your productivity than any language or framework out there. Your ability to communicate and collaborate with others will always be a better predictor of success than your choice of technology stack. Your relationships with others are the most significant factors of success and happiness in life.

Apple’s annual release cycle affords us all an opportunity each June to reflect on how far we’ve come and where we want to go from here — both individually and as a community.

Don’t be afraid to think different.

SwiftUI cast a large shadow over everything announced at WWDC. So now that we’ve gotten this out of our system, we look forward to digging into the hundreds of new APIs and dozens of new frameworks coming later this year.

See you all next week!

Years ago, we remarked that the “at sign” (@) — along with square brackets and ridiculously-long method names — was as characteristic of Objective-C as parentheses are to Lisp or punctuation is to Perl.

Then came Swift, and with it an end to these curious little 🥨-shaped glyphs.
Or so we thought.

At first, the function of @ was limited to Objective-C interoperability: @IBAction, @NSCopying, @UIApplicationMain, and so on. But in time, Swift has continued to incorporate an ever-increasing number of @-prefixed attributes.

We got our first glimpse of Swift 5.1 at WWDC 2019 by way of the SwiftUI announcement. And with each “mind-blowing” slide came a hitherto unknown attribute: @State, @Binding, @EnvironmentObject…

We saw the future of Swift, and it was full of @s.

We’ll dive into SwiftUI once it’s had a bit longer to bake.

But this week, we wanted to take a closer look at a key language feature for SwiftUI — something that will have arguably the biggest impact on the «je ne sais quoi» of Swift in version 5.1 and beyond: property wrappers

About Property DelegatesWrappers

Property wrappers were first pitched to the Swift forums back in March of 2019 — months before the public announcement of SwiftUI.

In his original pitch, Swift Core Team member Douglas Gregor described the feature (then called “property delegates”) as a user-accessible generalization of functionality currently provided by language features like the lazy keyword.

Laziness is a virtue in programming, and this kind of broadly useful functionality is characteristic of the thoughtful design decisions that make Swift such a nice language to work with. When a property is declared as lazy, it defers initialization of its default value until first access. For example, you could implement equivalent functionality yourself using a private property whose access is wrapped by a computed property, but a single lazy keyword makes all of that unnecessary.

structStructure{// Deferred property initialization with lazy keywordlazyvardeferred=...// Equivalent behavior without lazy keywordprivatevar_deferred:Type?vardeferred:Type{get{ifletvalue=_deferred{returnvalue}letinitialValue=..._deferred=initialValuereturninitialValue}set{_deferred=newValue}}}

SE-0258: Property Wrappers is currently in its third review (scheduled to end yesterday, at the time of publication), and it promises to make open up functionality like lazy so that library authors can implement similar functionality themselves.

The proposal does an excellent job outlining its design and implementation. So rather than attempt to improve on this explanation, we thought it’d be interesting to look at some new patterns that property wrappers make possible — and, in the process, get a better handle on how we might use this feature in our projects.

So, for your consideration, here are four potential use cases for the new @propertyWrapper attribute:

• Constraining Values
• Transforming Values on Property Assignment
• Changing Synthesized Equality and Comparison Semantics
• Auditing Property Access

Constraining Values

SE-0258 offers plenty of practical examples, including @Lazy, @Atomic, @ThreadSpecific, and @Box. But the one we were most excited about was that of the @Constrained property wrapper.

Swift’s standard library offer correct, performant floating-point number types, and you can have it in any size you want — so long as it’s 32 or 64(or 80) bits long (to paraphrase Henry Ford).

If you wanted to implement a custom floating-point number type that enforced a valid range of values, this has been possible since Swift 3. However, doing so would require conformance to a labyrinth of protocol requirements:

Pulling this off is no small feat, and often far too much work to justify for most use cases.

Fortunately, property wrappers offer a way to parameterize standard number types with significantly less effort.

Implementing a value clamping property wrapper

Consider the following Clamping structure. As a property wrapper (denoted by the @propertyWrapper attribute), it automatically “clamps” out-of-bound values within the prescribed range.

@propertyWrapperstructClamping<Value:Comparable>{varvalue:Valueletrange:ClosedRange<Value>init(initialValuevalue:Value,_range:ClosedRange<Value>){precondition(range.contains(value))self.value=valueself.range=range}varwrappedValue:Value{get{value}set{value=min(max(range.lowerBound,newValue),range.upperBound)}}}

You could use @Clamping to guarantee that a property modeling acidity in a chemical solution within the conventional range of 0 – 14.

structSolution{@Clamping(0...14)varpH:Double=7.0}letcarbonicAcid=Solution(pH:4.68)// at 1 mM under standard conditions

Attempting to set pH values outside that range results in the closest boundary value (minimum or maximum) to be used instead.

letsuperDuperAcid=Solution(pH:-1)superDuperAcid.pH// 0

Related Ideas

• A @Positive / @NonNegative property wrapper that provides the unsigned guarantees to signed integer types.
• A @NonZero property wrapper that ensures that a number value is either greater than or less than 0.
• @Validated or @Whitelisted / @Blacklisted property wrappers that restrict which values can be assigned.

Transforming Values on Property Assignment

Accepting text input from users is a perennial headache among app developers. There are just so many things to keep track of, from the innocent banalities of string encoding to malicious attempts to inject code through a text field. But among the most subtle and frustrating problems that developers face when accepting user-generated content is dealing with leading and trailing whitespace.

A single leading space can invalidate URLs, confound date parsers, and sow chaos by way of off-by-one errors:

importFoundationURL(string:" https://nshipster.com")// nil (!)ISO8601DateFormatter().date(from:" 2019-06-24")// nil (!)letwords=" Hello, world!".components(separatedBy:.whitespaces)words.count// 3 (!)

When it comes to user input, clients most often plead ignorance and just send everything as-is to the server. ¯\_(ツ)_/¯.

While I’m not advocating for client apps to take on more of this responsibility, the situation presents another compelling use case for Swift property wrappers.

Foundation bridges the trimmingCharacters(in:) method to Swift strings, which provides, among other things, a convenient way to lop off whitespace from both the front or back of a String value. Calling this method each time you want to ensure data sanity is, however, less convenient. And if you’ve ever had to do this yourself to any appreciable extent, you’ve certainly wondered if there might be a better approach.

In your search for a less ad-hoc approach, you may have sought redemption through the willSet property callback… only to be disappointed that you can’t use this to change events already in motion.

structPost{vartitle:String{willSet{title=newValue.trimmingCharacters(in:.whitespacesAndNewlines)/* ⚠️ Attempting to store to property 'title' within its own willSet,
        which is about to be overwritten by the new value              */}}}

From there, you may have realized the potential of didSet as an avenue for greatness… only to realize later that didSet isn’t called for during initial property assignment.

structPost{vartitle:String{// 😓 Not called during initializationdidSet{self.title=title.trimmingCharacters(in:.whitespacesAndNewlines)}}}

Undeterred, you may have tried any number of other approaches… ultimately finding none to yield an acceptable combination of ergonomics and performance characteristics.

If any of this rings true to your personal experience, you can rejoice in the knowledge that your search is over: property wrappers are the solution you’ve long been waiting for.

Implementing a Property Wrapper that Trims Whitespace from String Values

Consider the following Trimmed struct that trims whitespaces and newlines from incoming string values.

importFoundation@propertyWrapperstructTrimmed{private(set)varvalue:String=""varwrappedValue:String{get{value}set{value=newValue.trimmingCharacters(in:.whitespacesAndNewlines)}}init(initialValue:String){self.wrappedValue=initialValue}}

By marking each String property in the Post structure below with the @Trimmed annotation, any string value assigned to title or body— whether during initialization or via property access afterward — automatically has its leading or trailing whitespace removed.

structPost{@Trimmedvartitle:String@Trimmedvarbody:String}letquine=Post(title:"  Swift Property Wrappers  ",body:"...")quine.title// "Swift Property Wrappers" (no leading or trailing spaces!)quine.title="      @propertyWrapper     "quine.title// "@propertyWrapper" (still no leading or trailing spaces!)

Related Ideas

• A @Transformed property wrapper that applies ICU transforms to incoming string values.
• A @Normalized property wrapper that allows a String property to customize its normalization form.
• A @Quantized / @Rounded / @Truncated property that quantizes values to a particular degree (e.g. “round up to nearest ½”), but internally tracks precise intermediate values to prevent cascading rounding errors.

Changing Synthesized Equality and Comparison Semantics

In Swift, two String values are considered equal if they are canonically equivalent. By adopting these equality semantics, Swift strings behave more or less as you’d expect in most circumstances: if two strings comprise the same characters, it doesn’t matter whether any individual character is composed or precomposed — that is, “é” (U+00E9 LATIN SMALL LETTER E WITH ACUTE) is equal to “e” (U+0065 LATIN SMALL LETTER E) + “◌́” (U+0301 COMBINING ACUTE ACCENT).

But what if your particular use case calls for different equality semantics? Say you wanted a case insensitive notion of string equality?

There are plenty of ways you might go about implementing this today using existing language features:

• You could take the lowercased() result anytime you do == comparison, but as with any manual process, this approach is error-prone.
• You could create a custom CaseInsensitive type that wraps a String value, but you’d have to do a lot of additional work to make it as ergonomic and functional as the standard String type.
• You could define a custom comparator function to wrap that comparison — heck, you could even define your own custom operator for it — but nothing comes close to an unqualified == between two operands.

None of these options are especially compelling, but thanks to property wrappers in Swift 5.1, we’ll finally have a solution that gives us what we’re looking for.

Implementing a case-insensitive property wrapper

The CaseInsensitive type below implements a property wrapper around a String / SubString value. The type conforms to Comparable (and by extension, Equatable) by way of the bridged NSString API caseInsensitiveCompare(_:):

importFoundation@propertyWrapperstructCaseInsensitive<Value:StringProtocol>{varwrappedValue:Value}extensionCaseInsensitive:Comparable{privatefunccompare(_other:CaseInsensitive)->ComparisonResult{wrappedValue.caseInsensitiveCompare(other.wrappedValue)}staticfunc==(lhs:CaseInsensitive,rhs:CaseInsensitive)->Bool{lhs.compare(rhs)==.orderedSame}staticfunc<(lhs:CaseInsensitive,rhs:CaseInsensitive)->Bool{lhs.compare(rhs)==.orderedAscending}staticfunc>(lhs:CaseInsensitive,rhs:CaseInsensitive)->Bool{lhs.compare(rhs)==.orderedDescending}}

Construct two string values that differ only by case, and they’ll return false for a standard equality check, but true when wrapped in a CaseInsensitive object.

lethello:String="hello"letHELLO:String="HELLO"hello==HELLO// falseCaseInsensitive(wrappedValue:hello)==CaseInsensitive(wrappedValue:HELLO)// true

So far, this approach is indistinguishable from the custom “wrapper type” approach described above. And this is normally where we’d start the long slog of implementing conformance to ExpressibleByStringLiteral and all of the other protocols to make CaseInsensitive start to feel enough like String to feel good about our approach.

Property wrappers allow us to forego all of this busywork entirely:

structAccount:Equatable{@CaseInsensitivevarname:Stringinit(name:String){$name=CaseInsensitive(wrappedValue:name)}}varjohnny=Account(name:"johnny")letJOHNNY=Account(name:"JOHNNY")letJane=Account(name:"Jane")johnny==JOHNNY// truejohnny==Jane// falsejohnny.name==JOHNNY.name// falsejohnny.name="Johnny"johnny.name// "Johnny"

Here, Account objects are checked for equality by a case-insensitive comparison on their name property value. However, when we go to get or set the name property, it’s a bona fideString value.

That’s neat, but what’s actually going on here?

Since Swift 4, the compiler automatically synthesizes Equatable conformance to types that adopt it in their declaration and whose stored properties are all themselves Equatable. Because of how compiler synthesis is implemented (at least currently), wrapped properties are evaluated through their wrapper rather than their underlying value:

// Synthesized by Swift CompilerextensionAccount:Equatable{staticfunc==(lhs:Account,rhs:Account)->Bool{lhs.$name==rhs.$name}}

Related Ideas

• Defining @CompatibilityEquivalence such that wrapped String properties with the values "①" and "1" are considered equal.
• A @Approximate property wrapper to refine equality semantics for floating-point types (See also SE-0259)
• A @Ranked property wrapper that takes a function that defines strict ordering for, say, enumerated values; this could allow, for example, the playing card rank .ace to be treated either low or high in different contexts.