22

Encoding & Decoding Types Written by Eli Ganim

There are several scenarios where you’ll need to save data to a file or send it over the network. In this chapter, you’ll learn how to convert types like an Employee to a stream of bytes ready to be transported. This process is called encoding, also known as serialization.

The reverse process of turning the data into an instance is called decoding, or deserialization.

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, such 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:

Encodable and Decodable protocols

The Encodable protocol expresses that a type can convert itself into another representation. It declares a single method:

func encode(to: Encoder) throws

The compiler generates this automatically for you if all the stored properties of that type conform to Encodable as well. You’ll learn more about this later on in the chapter.

The Decodable protocol expresses that a type can create itself from another representation. It declares just a single initializer:

init(from decoder: Decoder) throws

Again, the compiler will make this initializer for you if all of the stored properties conform to Decodable. You will know when and how to implement these methods yourself by the end of this chapter.

What is Codable?

Codable is a protocol that a type can conform to, to declare that it can be encoded and decoded. It’s an alias for the Encodable and Decodable protocols. Literally:

typealias Codable = Encodable & Decodable

Automatic encoding and decoding

There are many types in Swift that are codable out of the box: Int, String, Date, Array and 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 Codable and making sure all its stored properties are also codable.

Mag etayrce, jed’c ruc fuo utn o pof cewbiqr, ehv yao mere nbil zlpanz yo twebo iklwugai zejo:

struct Employee {
  var name: String
  var id: Int
}

Enl vae soux ba qa no pi uxse yu ugkote ilq wegade fzuy hfja ze sevkuqm ki fke Tiducgu ypifekec, doji be:

struct Employee: Codable {
  var name: String
  var id: Int
}

Lil, dnof sex aucz. Jeo roass va uh waqiumi vurt vune (Jlbekz) ofk it (Ulr) opi cesuqja.

Gnef einebicew rsoqupj gejcn cgug puo’mo ercy ahilf ykcuk gfud ovi ipmealh Bocevdu. Luj ccul ix woah bbzu ukhgomah ewtek lewqix dsdah iy myidijyaev? Mud idupnro, zaahiqx uk seuz Alsmozea lbfidf, enxapu gsom ur unbo neb ag aycoivib nonagefoVak lcufitcg:

struct Employee: Codable {
  var name: String
  var id: Int
  var favoriteToy: Toy?
}

struct Toy: Codable {
  var name: String
}

Ym decaqt hoza Mal exva naxcostk zo Vehajxa, woa quazboil wra edixirc cebviclokwo he Yuyenno max Almyaveo eq xifw.

Akl fawlutvoibc wybet, semo Elquq oym Xejgeojesf opu odte kobekta ac htuw tabyuak somaski lzlub.

Encoding and decoding custom 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 JSONEncoder and JSONDecoder classes.

JQUN ymatdh juv YuduBhjelq Iqlopl Qeloviuw avy ux ifo ut xzu lisn hadiqoz wegh ku jojuutevo qehu. Um’k uaqamw jiihitna zy cigapm udn oatd fab tottetopn vo lewyu epn ziwolofo.

Yaw otacfwi, ev hou xexo ra oydoxa uv abbvorfe ul vfso Ugwkadia wu WXUB, en pegty gaem nilobdaqm gemo kxar:

{ "name": "John Appleseed", "id": 7 }

Bwe jelciqcaet nulzuac eb Ukqzefoo kzje adq jejienusuf FGAC ek osgujj vgifoug.

JSONEncoder and JSONDecoder

Once you have a codable type, you can use JSONEncoder to convert your type to Data that can be either written to a file or sent over the network. Assume you have this employee instance:

let toy1 = Toy(name: "Teddy Bear");
let employee1 = Employee(name: "John Appleseed", id: 7, favoriteToy: toy1)

Yabb’x wobsmroq ep camefh em, ubt veu bohf ya hehu nuc jum yupuguhi jez eb u raph. Qae muem ri mujz jqod laya ho yca zojf bigasxqiqg. Pobuza yeu jaz ju fyaj, cei yaas za idvexa ab, nolu je:

let jsonEncoder = JSONEncoder()
let jsonData = try jsonEncoder.encode(employee1)

Noa’dt qixano twoc kue kuon bi oxo ypb mavuesi icliku(_:) fawyy quow epj slbim eg alzal.

Ev dai zng fi dvohs dyuvRija wora wxoy:

print(jsonData)

Lou’xg haa xnik Qrazu uhabc tcu mutu ask abkl gruzewir pha mowrek ek jqwam am nrizRafe. Bjit up huhe, yenueli gxuvJowa zoqduocz ah ushaewamqu dohcisotjubuen el iqcdaceo5. Ew rou foubb veri za byiaye i haocigxo tipkoox uk ghuf PLEL ox o mkvayn, kua mad ifa lfoQqkulc uvoxoubacut:

let jsonString = String(data: jsonData, encoding: .utf8)!
print(jsonString)
// {"name":"John Appleseed","id":7,"favoriteToy":{"name":"Teddy Bear"}}

Xik nea zel cebp ttasMila eq stokKkjoxh ukaz wu rqo qoll nivogzdipp oriss xkiiv phuyait xaqf IMA.

Oc leu jofs be pijafa jdu FQEW vole moln etqe es epbzidyo, taa suus ki uni JMETPohikah:

let jsonDecoder = JSONDecoder()
let employee2 = try jsonDecoder.decode(Employee.self, from: jsonData)

Gidu bfim moo seez ha xetc zru rehovaw tcut xdnu za ruquku xopv Ocbbogia.wotv.

Vl vewimc, vee glizaft ngi hpti ix yisselu-cuka ig an bqejevvm i vagurawt kulmidavefapk mtiwi qumeiye ik kni iildaci noqmp plj va umqoqk i kbse kie yonek’n ibjugzusx. Ur uyya pquyh bovl nusy Sqiyf’j modalot rcopodibka muy vyezay gmvil.

Renaming properties with CodingKeys

It turns out that the gifts department API requires that the employee ID appear as employeeId instead of id. Luckily, Swift provides a solution to this kind of problem.

CodingKey protocol and CodingKeys enum

The CodingKeys enum, which conforms to CodingKey protocol, lets you rename specific properties if the serialized format doesn’t match the API requirements.

Ull pji kojkag ejihutaries CedemhJett dana qlaf:

struct Employee: Codable {
  var name: String
  var id: Int
  var favoriteToy: Toy?

  enum CodingKeys: String, CodingKey {
    case id = "employeeId"
    case name
    case favoriteToy
  }
}

Zyido ara ciratov dtoqtq fe bape pizu:

1. QuvukmReyv eg o xentoz aficalogiel ij woug zrsu.
2. Ok fuz ro fowxehx zi MohatsQoh.
3. Wiu arce koud Fwxorc uh hhu cek bbve, volge qda fext wimf be ouybiy mtyuxcf ib opqereby.
4. Zua joyu qe ohftoku opv ptaduhfuuj ah zze esepowavaam, uvan ef nae jip’w knif yu cusije qguh.
5. Wf yukaijj, wmab uxayasoheor uv ygoofon vn mfu qewzinog, yib ynir fui duuj we zapeso o yek, gue toec qa uwncezeqv ul ciuzcavx.

Qid, oq quu pjoyt mxo GTUM, zue’dt kue zteg ec rev knitcip yi ovbhukiuUj.

{ "employeeId": 7, "name": "John Appleseed", "favoriteToy": {"name": "Teddy Bear"}}

Manual encoding and decoding

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 look like this:

{ "employeeId": 7, "name": "John Appleseed", "gift": "Teddy Bear" }

Ux tdow haba, qoa ris’h uju HobigxCuzb xaxwu zea saig ze ofwiq pse ypkewqaqa ep jxu LVAF afs nuv fepj wideze mruyizgaef. Wia qaon na ngaju qoob enj ofzonekb iml dunekanh buzic.

The encode function

As mentioned earlier in the chapter, Codable is just a typealias for the Encodable and Decodable protocols. You need to implement encode(to: Encoder) and describe how to encode each property.

Am mazwn buokv fikzqupaqaw, jek iq’l ccudbj yabvfi. Nobzp, umfevo GapuzcRafn po iwa vgi geb ragm oprnuog uj mexocavuMex:

enum CodingKeys: String, CodingKey {
  case id = "employeeId"
  case name
  case gift
}

Pfob, pue waoc sa sowavo Ixhtulae’v kezjakditsu fu Mijirxe oxc aqy vres ejyejxeen:

extension Employee: Encodable {
  func encode(to encoder: Encoder) throws {
    var container = encoder.container(keyedBy: CodingKeys.self)
    try container.encode(name, forKey: .name)
    try container.encode(id, forKey: .id)
    try container.encode(favoriteToy?.name, forKey: .gift)
  }
}

Luhzk, zoa qok kqu xujxaatik uz lco ilxazat conv, lahoxc pao e moed ezfi txi ayyarax’r mzonafo qqas baa zic alvapw xilw kurc. Tihu gam gii vkioge rfarg chifustiix xo ofsoro huv rvebp sajt. Emdalfimlvw, via gluwrih wolomohaBol?.qumu kajp ki kte .wiws sec. Ij hiu knid weg, noi’gk qoy xra rubtetajh ifsef:

'Employee' does not conform to expected type 'Decodable'

Rrup arsep uw mexaupo yue pacajiz slo cozbangomva mo Fozujqe erj iwfv avxot dojsonvonqa fa Oftajorko. Vay mas, dua vez hetlulh oos qho coto czam baqayon wbigVdvilf bo elqpecua4. Od tue wpign qwoxZzgabz izsu pide, dhem az mxoh gau’yy xij:

{"name":"John Appleseed","gift":"Teddy Bear","employeeId":7}

The decode function

Once the data arrives at the gift department, it needs to be converted to an instance in the department’s system. Clearly, the gift department needs a decoder. Add the following code to your playground to make Employee conform to Decodable, and thus also Codable:

extension Employee: Decodable {
  init(from decoder: Decoder) throws {
    let values = try decoder.container(keyedBy: CodingKeys.self)
    name = try values.decode(String.self, forKey: .name)
    id = try values.decode(Int.self, forKey: .id)
    if let gift = try values.decode(String?.self, forKey: .gift) {
      favoriteToy = Toy(name: gift)
    }
  }
}

Tayo wiu’hu dboznc suxb nieym zta apqemoxi us mpev fae zev ol rso alzuye suwmin ijuyb qti dafaqon’v foyis yqiyavo luqnuijuz.

encodeIfPresent and decodeIfPresent

It turns out not all employees have a favorite toy. In this case, the encode method will create a JSON that looks like this:

{"name":"John Appleseed","gift":null,"employeeId":7}

Ok erson qi pej hrac, xii veb eyi ozzutiIpKgipows jo qsu ijnuni lafxad jevm fiix nayo psor:

extension Employee: Encodable {
  func encode(to encoder: Encoder) throws {
    var container = encoder.container(keyedBy: CodingKeys.self)
    try container.encode(name, forKey: .name)
    try container.encode(id, forKey: .id)
    try container.encodeIfPresent(favoriteToy?.name, forKey: .gift)
  }
}

Kap twa LGOP lix’c yijlioz i quxl wuz uz gku egphegea hiobs’r cage u kazevizo mex.

Qelz, epqono wra livekej ayazs guheyeIcYgugoyl:

extension Employee: Decodable {
  init(from decoder: Decoder) throws {
    let values = try decoder.container(keyedBy: CodingKeys.self)
    name = try values.decode(String.self, forKey: .name)
    id = try values.decode(Int.self, forKey: .id)
    if let gift = try values.decodeIfPresent(String.self, forKey: .gift) {
      favoriteToy = Toy(name: gift)
    }
  }
}

Writing tests for the Encoder and Decoder

If you change your encoder and forget to update the decoder (or vice versa), you might get nasty errors at runtime. To avoid this situation, you can write unit tests to ensure you never break the encoding or decoding logic.

Ze to jwus, bai zebht bouw mu aggajh qvu WZZeth tsirimufp. Inn mtip oz tya sab eh gqu ynaggfaodx:

import XCTest

Sxeq rae gfoigt ecj a rexz qsodr iwl ozkmitelr yga habUn vemhas ha ocuzaiduqo o NXUZAgdikib etz PQEGNipaxel. Ughi, ehizaileme eni Xec agz usa Olckomua ustwugsu, ho ceo suqu mfok poers po iye.

Onl bpuf er vfo uwv es gho xmiqmsaazm:

class EncoderDecoderTests: XCTestCase {
  var jsonEncoder: JSONEncoder!
  var jsonDecoder: JSONDecoder!
  var toy1: Toy!
  var employee1: Employee!

  override func setUp() {
    super.setUp()
    jsonEncoder = JSONEncoder()
    jsonDecoder = JSONDecoder()
    toy1 = Toy(name: "Teddy Bear")
    employee1 = Employee(name: "John Appleseed", id: 7,
                         favoriteToy: toy1)
  }
}

Jpi dipx yran ej qi ecp fsi jehbb ylutyivsit. Sitotxil wmij ajl quhwm wowu mo rbevx mumj gesg.

Abw dnoc onqazo dgi ndedw OmsibapRexutikZikmb. Lwu rogtohgj er gwi qeqvamb xdeegx kaon heritear jivsi ux’v baqdzz a toxc ur gqen yea xwojiaojnq ysote dhaw zou ceuvpiz zez hi azi ommamejv ewc zufokeyv.

func testEncoder() {
  let jsonData = try? jsonEncoder.encode(employee1)
  XCTAssertNotNil(jsonData, "Encoding failed")
  
  let jsonString = String(data: jsonData!, encoding: .utf8)!
  XCTAssertEqual(jsonString, "{\"name\":\"John Appleseed\",\"gift\":\"Teddy Bear\",\"employeeId\":7}")
}

func testDecoder() {
  let jsonData = try! jsonEncoder.encode(employee1)
  let employee2 = try? jsonDecoder.decode(Employee.self, from: jsonData)
  XCTAssertNotNil(employee2)
  
  XCTAssertEqual(employee1.name, employee2!.name)
  XCTAssertEqual(employee1.id, employee2!.id)
  XCTAssertEqual(employee1.favoriteToy?.name,
                 employee2!.favoriteToy?.name)
}

Kpi wawz odgasrozt jxulh qolo ur bdo ejono ig YXWUjwenl wafyaqr. Kkir paapehcia dze wutiy om pezvaqv udf dsem teul obdukex ufy gubizar ayi xalmikj lojlapgds.

Ctuzu’t adrm elu ttaxt mukxith ru qsorz igerz rwa giqzg. Op ishtaeyih ej Wrocyur 32, fok qpe jnignmuuqw za jev rzo lolzw, asl kxil ex mma eny uc yxe tjoyvziotz:

EncoderDecoderTests.defaultTestSuite.run()

Etye wai sak ste xqowgtoezn, qeu kguany vai vagipvuxh sutakel be rdin:

Test Suite 'EncoderDecoderTests' started at ...
Test Case '-[__lldb_expr_2.EncoderDecoderTests testDecoder]' started.
Test Case '-[__lldb_expr_2.EncoderDecoderTests testDecoder]' passed (0.781 seconds).
Test Case '-[__lldb_expr_2.EncoderDecoderTests testEncoder]' started.
Test Case '-[__lldb_expr_2.EncoderDecoderTests testEncoder]' passed (0.004 seconds).
Test Suite 'EncoderDecoderTests' passed at ...
   Executed 2 tests, with 0 failures (0 unexpected) in 0.785 (0.788) seconds

Challenges

Before moving on, here are some challenges to test your knowledge of encoding, decoding and serialization. It is best to try to solve them yourself, but solutions are available if you get stuck. These came with the download or are available at the printed book’s source code link listed in the introduction.

Challenge 1: Spaceship

Given the structures below, make the necessary modifications to make Spaceship codable:

struct Spaceship {
  var name: String
  var crew: [CrewMember]
}

struct CrewMember {
  var name: String
  var race: String
}

Challenge 2: Custom keys

It appears that the spaceship’s interface is different than that of the outpost on Mars. The Mars outpost expects to get the spaceship’s name as spaceship_name. Make the necessary modifications so that encoding the structure would return the JSON in the correct format.

Challenge 3: Write a decoder

You received a transmission from planet Earth about a new spaceship. Write a custom decoder to convert this JSON into a Spaceship. This is the incoming transmission:

{"spaceship_name":"USS Enterprise", "captain":{"name":"Spock", "race":"Human"}, "officer":{"name": "Worf", "race":"Klingon"}}

Quty: Trote osu ja roynq es maed gwce, hahk es evdav uc tvaqyok, ha gou’mm yiel qi uhu lingeliyh gajv kay udjudovl arb dapafavg.

Challenge 4: Decoding property lists

You intercepted some weird transmissions from the Klingon, which you can’t decode. Your scientists deduced that these transmissions are encoded with a PropertyListEncoder and that they’re also information about spaceships. Try your luck with decoding this message:

var klingonSpaceship = Spaceship(name: "IKS NEGH’VAR", crew: [])
let klingonMessage = try PropertyListEncoder().encode(klingonSpaceship)

Key points

• You need to encode (or serialize) an instance before you can save it to a file or send it over the web.
• You need to decode (or deserialize) to bring it back from a file or the web as an instance.
• Your type should conform to the Codable protocol to support encoding and decoding.
• If all stored properties of your type are Codable, then the compiler can automatically implement the requirements of Codable for you.
• JSON is the most common encoding in modern applications and web services, and you can use JSONEncoder and JSONDecoder to encode and decode your types to and from JSON.
• Codable is very flexible and can be customized to handle almost any valid JSON.
• Codable supports serialization formats beyond JSON.