This is an abridged chapter from our best-selling book Swift Apprentice, which has been completely updated for Swift 4 and includes several new chapters. This tutorial is presented as part of ouriOS 11 Launch Party — enjoy!
There are several scenarios where you’ll need to save data to a file or to send it over the network. In this tutorial, you’ll learn how to achieve these tasks by converting your instances to another representation, like a string or a stream of bytes. This process is known asencoding, also known asserialization.
The reverse process of turning the data into an instance is calleddecoding, ordeserialization.
Imagine you have an instance you want to write to a file. The instance itself cannot be written as-is to the file, so you need to encode it into another representation, like as a stream of bytes:
Once the data is encoded and saved to a file, you can turn it back into an instance whenever you want by using a decoder:
Encodableprotocol is used by types that can be encoded to another representation. It declares a single method:
…which the compiler generates for you if all the stored properties of that type conform to
Encodableas well. You’ll learn more about this later on in the tutorial.
TheDecodableprotocol is used by types that can be decoded. It declares just a single initializer:
You will know when and how to implement these methods by the end of this tutorial.
Codableis a protocol that a type can conform to, to declare that it can be encoded and decoded. It’s basically an alias for the
There are many types in Swift which are codable out of the box:
Arrayand many other types from the Standard Library and the Foundation framework. If you want your type to be codable, the simplest way to do it is by conforming to
Codableand making sure all its stored properties are also codable.
For example, let’s say you own a toy factory and you have this struct to store employee data:
All you need to do to be able to encode and decode this type is to conform to the
Codableprotocol, like so:
Wow, that was easy! You were able to do it because both
Int) are codable.
This works well when you’re only using types that are already
Codable. But what if your type includes other custom types as properties? For example, looking at your
Employeestruct, assume that it also has a
By making sure
Toyalso conforms to
Codable, you maintain the overall conformance to
All collections types, like
Dictionaryare also codable if they contain codable types.
There are several representations you can encode to or decode from, such as XML or a Property List. In this section, you’ll learn how to encode to and decode from JSON, by using Swift’s
For example, if you were to encode an instance of type
Employeeto JSON, it might look something like this:
You can easily understand how the
Employeeinstance looked like before it was serialized into JSON.
Once you have a codable type, you can use
JSONEncoderto convert your type to
Datawhich can be either written to a file or sent over the network. Assume you have this employee instance:
John’s birthday is coming up and you want to give him his favorite toy as a gift. You need to send over this data to the Gifts department. Before you can do that, you need to encode it like this:
You’ll notice that you need to use
encode(_:)might fail and throw an error.
If you try to print
You’ll see that Xcode omits the data and only provides the number of bytes in
jsonData. This is fine, because
jsonDatacontains an unreadable representation of
employee1. If you would like to create a readable version of this JSON as a string, you can use
Now you can send
jsonStringover to the gifts department using their special gift API.
If you want to decode the JSON data back into an instance, you need to use
Note that you need to tell the decoder what type to decode the JSON to, because the compiler can’t figure this out on its own.
It turns out that the gifts department API requires that the employee ID appear as
id. Luckily, Swift provides a solution to this kind of problem.
CodingKeysenum, which conforms to
CodingKeyprotocol, lets you rename specific properties in case the serialized format doesn’t match the requirements of the API.
Add the nested enumeration
There are several things to note here:
is a nested enumeration in your type.
- It has to conform to
- You also need
as the raw type, since the keys are always strings.
- You have to include all properties in the enumeration, even if you don’t plan to rename them.
- By default, this enumeration is created by the compiler, but when you need to rename a key you need to implement it yourself.
Now if you print the JSON, you’ll see that the stored property
idkey has changed to
You try to send the data over to the gifts department, and again the data gets rejected. This time they claim that the information of the gift you want to send to the employee should not be inside a nested type, but rather as a property called
gift. So the JSON should actually look like this:
In this case you can’t use
CodingKeys, since you need to alter the structure of the JSON and not just rename properties. You need to write your own encoding and decoding logic.
As mentioned earlier in the tutorial,
Codableis actually just a typealias for the
Decodableprotocols. You need to implement
encode(to: Encoder)and describe how to encode each property.
It might sound complicated, but it’s pretty simple. First, update
CodingKeysto use the key
Then, you need to remove
Employee’s conformance to
Codableand then add this extension:
First you get back the
containerof the encoder. This is a view into the storage of the encoder that you can access with keys. Note how you choose which properties to encode for which keys. Importantly, you flatten
favoriteToy.namedown to the
If you stop now, you should get an error that says:
This is because you removed the conformance to
Codableand only added conformance to
Encodable. For now you can comment out the code that decodes
If you print
jsonStringonce more, this is what you’ll get:
Once the data arrives at the gifts department, they need to be able to convert this JSON back to an instance in their system. For this they’ll need a decoder.
Add the following code to your playground to make
Decodable(and thus also
Here you’re pretty much doing the opposite of what you did in the
encodemethod using the decoder’s keyed storage container.
- You need to encode (or serialize) an instance before you can save it to a file or send it over the web.
- Your type should conform to the
Codableprotocol to make it codable. If all properties are codable, then the type is automatically codable as well.
- JSON is the most common encoding in modern applications and web services, and you can use
JSONDecoderto encode and decode your types to and from JSON.
You can downloadthe final package from this tutorial here.
If you enjoyed what you learned in this tutorial, why not check outthe complete Swift Apprentice book, available on our store?
Here’s a taste of what’s in the book:
- Section I: Swift Basics
: The first section of the book starts at the very beginning of the computing environment: first, how computers work, and then, how Swift’s playgrounds feature works. With those logistics out of the way, you’ll take a tour of the fundamentals of the Swift language and learn the basics of managing data, structuring your code, performing simple operations and calculations, working with types.
- Section II: Collection Types
: Stored data is a core component of any app, whether it’s a list of friends in your social networking app or a set of unlockable characters in your hit game. In this section, you’ll learn how to store collections of data in Swift.
- Section III: Building Your Own Types
: Swift comes with basic building blocks, but its real power is in the custom things you can build to model parts of your app. Swift has no idea about playable characters and monsters and power-ups, for example — these are things you need to build yourself! You’ll learn how to do that in this section.
- Section IV: Advanced Topics
: The final section of the book covers more advanced topics in Swift. You’ll learn about specific things, such as how to handle problems that come up as your code runs, as well as about more general things such as memory management, which will help you understand some of Swift’s behind-the-scenes mechanisms.
By the end of this book, you’ll have some great hands-on experience with all of the best features of the Swift 4 programming language.
And to help sweeten the deal, the digital edition of the book is on sale for$49.99! But don’t wait — this sale price isonly available for a limited time.
Speaking of sweet deals, be sure to check out the great prizes we’re giving away this year with theiOS 11 Launch Party, including over_$9,000_in giveaways!
To enter, simply retweet this post using the #ios11launchparty hashtag by using the button below:
We hope you enjoy this update to one of our most-loved books. Stay tuned for more book releases and updates coming soon!