-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathEnumerations.html
More file actions
615 lines (500 loc) · 38.8 KB
/
Copy pathEnumerations.html
File metadata and controls
615 lines (500 loc) · 38.8 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
<!DOCTYPE html>
<html lang="en"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>The Swift Programming Language: Enumerations</title>
<link rel="stylesheet" type="text/css" href="resource/style-1.1.15.css">
<meta charset="utf-8"> <script>window["_GOOG_TRANS_EXT_VER"] = "1";</script></head>
<body id="conceptual_flow_with_tasks" class="jazz">
<div id="_omniture_top">
</div>
<a name="TP40014097" title="The Swift Programming Language"></a>
<section id="valence">
<div class="content-wrapper">
<p id="hierarchial_navigation">
<span id="book_title">The Swift Programming Language</span>
</p>
<img id="shortstack" src="./resource/shortstack_2x.png">
</div>
</section>
<div class="content-wrapper">
<nav class="book-parts hideInXcode" role="navigation">
<ul class="nav-parts">
<li data-id="TP40014097-CH1-XID_27" class="part-name">Welcome to Swift
<ul class="nav-chapters">
<li class="nav-chapter nav-visited-chapter">
<a href="About Swift.html#TP40014097-CH3-XID_0" data-id="TP40014097-CH3-XID_0" class="">About Swift</a>
</li>
<li class="nav-chapter">
<a href="A Swift Tour.html#TP40014097-CH2-XID_1" data-id="TP40014097-CH2-XID_1" class="">A Swift Tour</a>
</li>
</ul>
</li><li data-id="TP40014097-CH4-XID_299" class="part-name nav-part-active open-part">Language Guide
<ul class="nav-chapters" style="height: 607px;">
<li class="nav-chapter">
<a href="The Basics.html#TP40014097-CH5-XID_399" data-id="TP40014097-CH5-XID_399" class="">The Basics</a>
</li>
<li class="nav-chapter">
<a href="Basic Operators.html#TP40014097-CH6-XID_70" data-id="TP40014097-CH6-XID_70" class="">Basic Operators</a>
</li>
<li class="nav-chapter">
<a href="Strings and Characters.html#TP40014097-CH7-XID_368" data-id="TP40014097-CH7-XID_368" class="">Strings and Characters</a>
</li>
<li class="nav-chapter">
<a href="Collection Types.html#TP40014097-CH8-XID_133" data-id="TP40014097-CH8-XID_133" class="">Collection Types</a>
</li>
<li class="nav-chapter">
<a href="Control Flow.html#TP40014097-CH9-XID_153" data-id="TP40014097-CH9-XID_153" class="">Control Flow</a>
</li>
<li class="nav-chapter">
<a href="Functions.html#TP40014097-CH10-XID_204" data-id="TP40014097-CH10-XID_204" class="">Functions</a>
</li>
<li class="nav-chapter">
<a href="Closures.html#TP40014097-CH11-XID_117" data-id="TP40014097-CH11-XID_117" class="">Closures</a>
</li>
<li class="nav-chapter nav-current-chapter">
<a href="Enumerations.html" data-id="TP40014097-CH12-XID_185" class="nav-chapter-active">Enumerations</a>
</li>
<li class="nav-chapter">
<a href="Classes and Structures.html#TP40014097-CH13-XID_94" data-id="TP40014097-CH13-XID_94">Classes and Structures</a>
</li>
<li class="nav-chapter">
<a href="Properties.html#TP40014097-CH14-XID_323" data-id="TP40014097-CH14-XID_323">Properties</a>
</li>
<li class="nav-chapter">
<a href="Methods.html#TP40014097-CH15-XID_300" data-id="TP40014097-CH15-XID_300">Methods</a>
</li>
<li class="nav-chapter">
<a href="Subscripts.html#TP40014097-CH16-XID_393" data-id="TP40014097-CH16-XID_393">Subscripts</a>
</li>
<li class="nav-chapter">
<a href="Inheritance.html#TP40014097-CH17-XID_251" data-id="TP40014097-CH17-XID_251">Inheritance</a>
</li>
<li class="nav-chapter">
<a href="Initialization.html#TP40014097-CH18-XID_266" data-id="TP40014097-CH18-XID_266">Initialization</a>
</li>
<li class="nav-chapter">
<a href="Deinitialization.html#TP40014097-CH19-XID_182" data-id="TP40014097-CH19-XID_182">Deinitialization</a>
</li>
<li class="nav-chapter">
<a href="Automatic Reference Counting.html#TP40014097-CH20-XID_50" data-id="TP40014097-CH20-XID_50">Automatic Reference Counting</a>
</li>
<li class="nav-chapter">
<a href="Optional Chaining.html#TP40014097-CH21-XID_312" data-id="TP40014097-CH21-XID_312">Optional Chaining</a>
</li>
<li class="nav-chapter">
<a href="Type Casting.html#TP40014097-CH22-XID_443" data-id="TP40014097-CH22-XID_443">Type Casting</a>
</li>
<li class="nav-chapter">
<a href="Nested Types.html#TP40014097-CH23-XID_309" data-id="TP40014097-CH23-XID_309">Nested Types</a>
</li>
<li class="nav-chapter">
<a href="Extensions.html#TP40014097-CH24-XID_191" data-id="TP40014097-CH24-XID_191">Extensions</a>
</li>
<li class="nav-chapter">
<a href="Protocols.html#TP40014097-CH25-XID_345" data-id="TP40014097-CH25-XID_345">Protocols</a>
</li>
<li class="nav-chapter">
<a href="Generics.html#TP40014097-CH26-XID_234" data-id="TP40014097-CH26-XID_234">Generics</a>
</li>
<li class="nav-chapter">
<a href="Advanced Operators.html#TP40014097-CH27-XID_28" data-id="TP40014097-CH27-XID_28">Advanced Operators</a>
</li>
</ul>
</li><li data-id="TP40014097-CH28-XID_912" class="part-name">Language Reference
<ul class="nav-chapters">
<li class="nav-chapter">
<a href="About the Language Reference.html#TP40014097-CH29-XID_453" data-id="TP40014097-CH29-XID_453" class="">About the Language Reference</a>
</li>
<li class="nav-chapter">
<a href="Lexical Structure.html#TP40014097-CH30-XID_794" data-id="TP40014097-CH30-XID_794">Lexical Structure</a>
</li>
<li class="nav-chapter">
<a href="Types.html#TP40014097-CH31-XID_988" data-id="TP40014097-CH31-XID_988">Types</a>
</li>
<li class="nav-chapter">
<a href="Expressions.html#TP40014097-CH32-XID_655" data-id="TP40014097-CH32-XID_655">Expressions</a>
</li>
<li class="nav-chapter">
<a href="Statements.html#TP40014097-CH33-XID_913" data-id="TP40014097-CH33-XID_913">Statements</a>
</li>
<li class="nav-chapter">
<a href="Declarations.html#TP40014097-CH34-XID_475" data-id="TP40014097-CH34-XID_475">Declarations</a>
</li>
<li class="nav-chapter">
<a href="Attributes.html#TP40014097-CH35-XID_460" data-id="TP40014097-CH35-XID_460">Attributes</a>
</li>
<li class="nav-chapter">
<a href="Patterns.html#TP40014097-CH36-XID_878" data-id="TP40014097-CH36-XID_878">Patterns</a>
</li>
<li class="nav-chapter">
<a href="Generic Parameters and Arguments.html#TP40014097-CH37-XID_774" data-id="TP40014097-CH37-XID_774">Generic Parameters and Arguments</a>
</li>
<li class="nav-chapter">
<a href="Summary of the Grammar.html#TP40014097-CH38-XID_1030" data-id="TP40014097-CH38-XID_1030">Summary of the Grammar</a>
</li>
</ul>
</li>
</ul>
</nav>
<article class="chapter">
<a name="TP40014097-CH12"></a><a name="TP40014097-CH12-XID_185"></a>
<div class="pixel-line"></div>
<h2 class="chapter-name chapter-name-short">Enumerations</h2>
<section id="mini_toc" class="hideInXcode" role="navigation">
<div id="mini_toc_button">
<p>On This Page</p>
</div>
<ul class="list-bullet">
<li class="item">
<p class="para">
<a href="#TP40014097-CH12-XID_186">
Enumeration Syntax
</a>
</p>
</li>
<li class="item">
<p class="para">
<a href="#TP40014097-CH12-XID_188">
Matching Enumeration Values with a Switch Statement
</a>
</p>
</li>
<li class="item">
<p class="para">
<a href="#TP40014097-CH12-XID_189">
Associated Values
</a>
</p>
</li>
<li class="item">
<p class="para">
<a href="#TP40014097-CH12-XID_190">
Raw Values
</a>
</p>
</li>
</ul>
</section>
<section class="section">
<p class="para">
An <em>enumeration</em> defines a common type for a group of related values and enables you to work with those values in a type-safe way within your code.
</p>
<p class="para">
If you are familiar with C, you will know that C enumerations assign related names to a set of integer values. Enumerations in Swift are much more flexible, and do not have to provide a value for each member of the enumeration. If a value (known as a “raw” value) <em>is</em> provided for each enumeration member, the value can be a string, a character, or a value of any integer or floating-point type.
</p>
<p class="para">
Alternatively, enumeration members can specify associated values of <em>any</em> type to be stored along with each different member value, much as unions or variants do in other languages. You can define a common set of related members as part of one enumeration, each of which has a different set of values of appropriate types associated with it.
</p>
<p class="para">
Enumerations in Swift are first-class types in their own right. They adopt many features traditionally supported only by classes, such as computed properties to provide additional information about the enumeration’s current value, and instance methods to provide functionality related to the values the enumeration represents. Enumerations can also define initializers to provide an initial member value; can be extended to expand their functionality beyond their original implementation; and can conform to protocols to provide standard functionality.
</p>
<p class="para">
For more on these capabilities, see <span class="x-name"><a href="Properties.html#TP40014097-CH14-XID_323" data-id="TP40014097-CH14-XID_323">Properties</a></span>, <span class="x-name"><a href="Methods.html#TP40014097-CH15-XID_300" data-id="TP40014097-CH15-XID_300">Methods</a></span>, <span class="x-name"><a href="Initialization.html#TP40014097-CH18-XID_266" data-id="TP40014097-CH18-XID_266">Initialization</a></span>, <span class="x-name"><a href="Extensions.html#TP40014097-CH24-XID_191" data-id="TP40014097-CH24-XID_191">Extensions</a></span>, and <span class="x-name"><a href="Protocols.html#TP40014097-CH25-XID_345" data-id="TP40014097-CH25-XID_345">Protocols</a></span>.
</p>
</section>
<section class="section">
<a name="TP40014097-CH12-XID_186"></a>
<h3 class="section-name" tabindex="0">Enumeration Syntax</h3>
<p class="para">
You introduce enumerations with the <code class="code-voice">enum</code> keyword and place their entire definition within a pair of braces:
</p><section class="code-listing">
<span class="caption"></span>
<div class="code-sample">
<ul class="code-lines">
<li><code class="code-voice"><span class="kt">enum</span> <span class="vc">SomeEnumeration</span> {</code></li>
<li><code class="code-voice"> <span class="c">// enumeration definition goes here</span></code></li>
<li><code class="code-voice">}</code></li>
</ul>
</div>
</section><p class="para">
Here’s an example for the four main points of a compass:
</p><section class="code-listing">
<span class="caption"></span>
<div class="code-sample">
<ul class="code-lines">
<li><code class="code-voice"><span class="kt">enum</span> <span class="vc">CompassPoint</span> {</code></li>
<li><code class="code-voice"> <span class="kt">case</span> <span class="vc">North</span></code></li>
<li><code class="code-voice"> <span class="kt">case</span> <span class="vc">South</span></code></li>
<li><code class="code-voice"> <span class="kt">case</span> <span class="vc">East</span></code></li>
<li><code class="code-voice"> <span class="kt">case</span> <span class="vc">West</span></code></li>
<li><code class="code-voice">}</code></li>
</ul>
</div>
</section><p class="para">
The values defined in an enumeration (such as <code class="code-voice">North</code>, <code class="code-voice">South</code>, <code class="code-voice">East</code>, and <code class="code-voice">West</code>) are the <em>member values</em> (or <em>members</em>) of that enumeration. The <code class="code-voice">case</code> keyword indicates that a new line of member values is about to be defined.
</p><div class="note">
<a name="TP40014097-CH12-XID_187"></a>
<aside class="aside">
<p class="aside-title">Note
</p>
<p class="para">Unlike C and Objective-C, Swift enumeration members are not assigned a default integer value when they are created. In the <code class="code-voice">CompassPoints</code> example above, <code class="code-voice">North</code>, <code class="code-voice">South</code>, <code class="code-voice">East</code> and <code class="code-voice">West</code> do not implicitly equal <code class="code-voice">0</code>, <code class="code-voice">1</code>, <code class="code-voice">2</code> and <code class="code-voice">3</code>. Instead, the different enumeration members are fully-fledged values in their own right, with an explicitly-defined type of <code class="code-voice">CompassPoint</code>.
</p>
</aside>
</div><p class="para">
Multiple member values can appear on a single line, separated by commas:
</p><section class="code-listing">
<span class="caption"></span>
<div class="code-sample">
<ul class="code-lines">
<li><code class="code-voice"><span class="kt">enum</span> <span class="vc">Planet</span> {</code></li>
<li><code class="code-voice"> <span class="kt">case</span> <span class="vc">Mercury</span>, <span class="vc">Venus</span>, <span class="vc">Earth</span>, <span class="vc">Mars</span>, <span class="vc">Jupiter</span>, <span class="vc">Saturn</span>, <span class="vc">Uranus</span>, <span class="vc">Neptune</span></code></li>
<li><code class="code-voice">}</code></li>
</ul>
</div>
</section><p class="para">
Each enumeration definition defines a brand new type. Like other types in Swift, their names (such as <code class="code-voice">CompassPoint</code> and <code class="code-voice">Planet</code>) should start with a capital letter. Give enumeration types singular rather than plural names, so that they read as self-evident:
</p><section class="code-listing">
<span class="caption"></span>
<div class="code-sample">
<ul class="code-lines">
<li><code class="code-voice"><span class="kt">var</span> <span class="vc">directionToHead</span> = <span class="vc">CompassPoint</span>.<span class="vc">West</span></code></li>
</ul>
</div>
</section><p class="para">
The type of <code class="code-voice">directionToHead</code> is inferred when it is initialized with one of the possible values of <code class="code-voice">CompassPoint</code>. Once <code class="code-voice">directionToHead</code> is declared as a <code class="code-voice">CompassPoint</code>, you can set it to a different <code class="code-voice">CompassPoint</code> value using a shorter dot syntax:
</p><section class="code-listing">
<span class="caption"></span>
<div class="code-sample">
<ul class="code-lines">
<li><code class="code-voice"><span class="vc">directionToHead</span> = .<span class="vc">East</span></code></li>
</ul>
</div>
</section><p class="para">
The type of <code class="code-voice">directionToHead</code> is already known, and so you can drop the type when setting its value. This makes for highly readable code when working with explicitly-typed enumeration values.
</p>
</section>
<section class="section">
<a name="TP40014097-CH12-XID_188"></a>
<h3 class="section-name" tabindex="0">Matching Enumeration Values with a Switch Statement</h3>
<p class="para">
You can match individual enumeration values with a <code class="code-voice">switch</code> statement:
</p><section class="code-listing">
<span class="caption"></span>
<div class="code-sample">
<ul class="code-lines">
<li><code class="code-voice"><span class="vc">directionToHead</span> = .<span class="vc">South</span></code></li>
<li><code class="code-voice"><span class="kt">switch</span> <span class="vc">directionToHead</span> {</code></li>
<li><code class="code-voice"><span class="kt">case</span> .<span class="vc">North</span>:</code></li>
<li><code class="code-voice"> <span class="vc">println</span>(<span class="s">"Lots of planets have a north"</span>)</code></li>
<li><code class="code-voice"><span class="kt">case</span> .<span class="vc">South</span>:</code></li>
<li><code class="code-voice"> <span class="vc">println</span>(<span class="s">"Watch out for penguins"</span>)</code></li>
<li><code class="code-voice"><span class="kt">case</span> .<span class="vc">East</span>:</code></li>
<li><code class="code-voice"> <span class="vc">println</span>(<span class="s">"Where the sun rises"</span>)</code></li>
<li><code class="code-voice"><span class="kt">case</span> .<span class="vc">West</span>:</code></li>
<li><code class="code-voice"> <span class="vc">println</span>(<span class="s">"Where the skies are blue"</span>)</code></li>
<li><code class="code-voice">}</code></li>
<li><code class="code-voice"><span class="c">// prints "Watch out for penguins"</span></code></li>
</ul>
</div>
</section><p class="para">
You can read this code as:
</p><p class="para">
“Consider the value of <code class="code-voice">directionToHead</code>. In the case where it equals <code class="code-voice">.North</code>, print <code class="code-voice">"Lots of planets have a north"</code>. In the case where it equals <code class="code-voice">.South</code>, print <code class="code-voice">"Watch out for penguins"</code>.”
</p><p class="para">
…and so on.
</p><p class="para">
As described in <span class="x-name"><a href="Control Flow.html#TP40014097-CH9-XID_153" data-id="TP40014097-CH9-XID_153">Control Flow</a></span>, a <code class="code-voice">switch</code> statement must be exhaustive when considering an enumeration’s members. If the <code class="code-voice">case</code> for <code class="code-voice">.West</code> is omitted, this code does not compile, because it does not consider the complete list of <code class="code-voice">CompassPoint</code> members. Requiring exhaustiveness ensures that enumeration members are not accidentally omitted.
</p><p class="para">
When it is not appropriate to provide a <code class="code-voice">case</code> for every enumeration member, you can provide a <code class="code-voice">default</code> case to cover any members that are not addressed explicitly:
</p><section class="code-listing">
<span class="caption"></span>
<div class="code-sample">
<ul class="code-lines">
<li><code class="code-voice"><span class="kt">let</span> <span class="vc">somePlanet</span> = <span class="vc">Planet</span>.<span class="vc">Earth</span></code></li>
<li><code class="code-voice"><span class="kt">switch</span> <span class="vc">somePlanet</span> {</code></li>
<li><code class="code-voice"><span class="kt">case</span> .<span class="vc">Earth</span>:</code></li>
<li><code class="code-voice"> <span class="vc">println</span>(<span class="s">"Mostly harmless"</span>)</code></li>
<li><code class="code-voice"><span class="kt">default</span>:</code></li>
<li><code class="code-voice"> <span class="vc">println</span>(<span class="s">"Not a safe place for humans"</span>)</code></li>
<li><code class="code-voice">}</code></li>
<li><code class="code-voice"><span class="c">// prints "Mostly harmless"</span></code></li>
</ul>
</div>
</section>
</section>
<section class="section">
<a name="TP40014097-CH12-XID_189"></a>
<h3 class="section-name" tabindex="0">Associated Values</h3>
<p class="para">
The examples in the previous section show how the members of an enumeration are a defined (and typed) value in their own right. You can set a constant or variable to <code class="code-voice">Planet.Earth</code>, and check for this value later. However, it is sometimes useful to be able to store <em>associated values</em> of other types alongside these member values. This enables you to store additional custom information along with the member value, and permits this information to vary each time you use that member in your code.
</p><p class="para">
You can define Swift enumerations to store associated values of any given type, and the value types can be different for each member of the enumeration if needed. Enumerations similar to these are known as <em>discriminated unions</em>, <em>tagged unions</em>, or <em>variants</em> in other programming languages.
</p><p class="para">
For example, suppose an inventory tracking system needs to track products by two different types of barcode. Some products are labeled with 1D barcodes in UPC-A format, which uses the numbers <code class="code-voice">0</code> to <code class="code-voice">9</code>. Each barcode has a “number system” digit, followed by ten “identifier” digits. These are followed by a “check” digit to verify that the code has been scanned correctly:
</p><figure class="figure">
<span class="caption"></span>
<img src="./resource/barcode_UPC_2x.png" alt="image: ../Art/barcode_UPC_2x.png" width="252" height="120">
</figure><p class="para">
Other products are labeled with 2D barcodes in QR code format, which can use any ISO 8859-1 character and can encode a string up to 2,953 characters long:
</p><figure class="figure">
<span class="caption"></span>
<img src="./resource/barcode_QR_2x.png" alt="image: ../Art/barcode_QR_2x.png" width="169" height="169">
</figure><p class="para">
It would be convenient for an inventory tracking system to be able to store UPC-A barcodes as a tuple of three integers, and QR code barcodes as a string of any length.
</p><p class="para">
In Swift, an enumeration to define product barcodes of either type might look like this:
</p><section class="code-listing">
<span class="caption"></span>
<div class="code-sample">
<ul class="code-lines">
<li><code class="code-voice"><span class="kt">enum</span> <span class="vc">Barcode</span> {</code></li>
<li><code class="code-voice"> <span class="kt">case</span> <span class="vc">UPCA</span>(<span class="vc">Int</span>, <span class="vc">Int</span>, <span class="vc">Int</span>)</code></li>
<li><code class="code-voice"> <span class="kt">case</span> <span class="vc">QRCode</span>(<span class="vc">String</span>)</code></li>
<li><code class="code-voice">}</code></li>
</ul>
</div>
</section><p class="para">
This can be read as:
</p><p class="para">
“Define an enumeration type called <code class="code-voice">Barcode</code>, which can take either a value of <code class="code-voice">UPCA</code> with an associated value of type (<code class="code-voice">Int</code>, <code class="code-voice">Int</code>, <code class="code-voice">Int</code>), or a value of <code class="code-voice">QRCode</code> with an associated value of type <code class="code-voice">String</code>.”
</p><p class="para">
This definition does not provide any actual <code class="code-voice">Int</code> or <code class="code-voice">String</code> values—it just defines the <em>type</em> of associated values that <code class="code-voice">Barcode</code> constants and variables can store when they are equal to <code class="code-voice">Barcode.UPCA</code> or <code class="code-voice">Barcode.QRCode</code>.
</p><p class="para">
New barcodes can then be created using either type:
</p><section class="code-listing">
<span class="caption"></span>
<div class="code-sample">
<ul class="code-lines">
<li><code class="code-voice"><span class="kt">var</span> <span class="vc">productBarcode</span> = <span class="vc">Barcode</span>.<span class="vc">UPCA</span>(<span class="m">8</span>, <span class="m">85909_51226</span>, <span class="m">3</span>)</code></li>
</ul>
</div>
</section><p class="para">
This example creates a new variable called <code class="code-voice">productBarcode</code> and assigns it a value of <code class="code-voice">Barcode.UPCA</code> with an associated tuple value of <code class="code-voice">(8, 8590951226, 3)</code>. The provided “identifier” value has an underscore within its integer literal—<code class="code-voice">85909_51226</code>—to make it easier to read as a barcode.
</p><p class="para">
The same product can be assigned a different type of barcode:
</p><section class="code-listing">
<span class="caption"></span>
<div class="code-sample">
<ul class="code-lines">
<li><code class="code-voice"><span class="vc">productBarcode</span> = .<span class="vc">QRCode</span>(<span class="s">"ABCDEFGHIJKLMNOP"</span>)</code></li>
</ul>
</div>
</section><p class="para">
At this point, the original <code class="code-voice">Barcode.UPCA</code> and its integer values are replaced by the new <code class="code-voice">Barcode.QRCode</code> and its string value. Constants and variables of type <code class="code-voice">Barcode</code> can store either a <code class="code-voice">.UPCA</code> or a <code class="code-voice">.QRCode</code> (together with their associated values), but they can only store one of them at any given time.
</p><p class="para">
The different barcode types can be checked using a switch statement, as before. This time, however, the associated values can be extracted as part of the switch statement. You extract each associated value as a constant (with the <code class="code-voice">let</code> prefix) or a variable (with the <code class="code-voice">var</code> prefix) for use within the <code class="code-voice">switch</code> case’s body:
</p><section class="code-listing">
<span class="caption"></span>
<div class="code-sample">
<ul class="code-lines">
<li><code class="code-voice"><span class="kt">switch</span> <span class="vc">productBarcode</span> {</code></li>
<li><code class="code-voice"><span class="kt">case</span> .<span class="vc">UPCA</span>(<span class="kt">let</span> <span class="vc">numberSystem</span>, <span class="kt">let</span> <span class="vc">identifier</span>, <span class="kt">let</span> <span class="vc">check</span>):</code></li>
<li><code class="code-voice"> <span class="vc">println</span>(<span class="s">"UPC-A with value of </span>\(<span class="vc">numberSystem</span>)<span class="s">, </span>\(<span class="vc">identifier</span>)<span class="s">, </span>\(<span class="vc">check</span>)<span class="s">."</span>)</code></li>
<li><code class="code-voice"><span class="kt">case</span> .<span class="vc">QRCode</span>(<span class="kt">let</span> <span class="vc">productCode</span>):</code></li>
<li><code class="code-voice"> <span class="vc">println</span>(<span class="s">"QR code with value of </span>\(<span class="vc">productCode</span>)<span class="s">."</span>)</code></li>
<li><code class="code-voice">}</code></li>
<li><code class="code-voice"><span class="c">// prints "QR code with value of ABCDEFGHIJKLMNOP."</span></code></li>
</ul>
</div>
</section><p class="para">
If all of the associated values for a enumeration member are extracted as constants, or if all are extracted as variables, you can place a single <code class="code-voice">var</code> or <code class="code-voice">let</code> annotation before the member name, for brevity:
</p><section class="code-listing">
<span class="caption"></span>
<div class="code-sample">
<ul class="code-lines">
<li><code class="code-voice"><span class="kt">switch</span> <span class="vc">productBarcode</span> {</code></li>
<li><code class="code-voice"><span class="kt">case</span> <span class="kt">let</span> .<span class="vc">UPCA</span>(<span class="vc">numberSystem</span>, <span class="vc">identifier</span>, <span class="vc">check</span>):</code></li>
<li><code class="code-voice"> <span class="vc">println</span>(<span class="s">"UPC-A with value of </span>\(<span class="vc">numberSystem</span>)<span class="s">, </span>\(<span class="vc">identifier</span>)<span class="s">, </span>\(<span class="vc">check</span>)<span class="s">."</span>)</code></li>
<li><code class="code-voice"><span class="kt">case</span> <span class="kt">let</span> .<span class="vc">QRCode</span>(<span class="vc">productCode</span>):</code></li>
<li><code class="code-voice"> <span class="vc">println</span>(<span class="s">"QR code with value of </span>\(<span class="vc">productCode</span>)<span class="s">."</span>)</code></li>
<li><code class="code-voice">}</code></li>
<li><code class="code-voice"><span class="c">// prints "QR code with value of ABCDEFGHIJKLMNOP."</span></code></li>
</ul>
</div>
</section>
</section>
<section class="section">
<a name="TP40014097-CH12-XID_190"></a>
<h3 class="section-name" tabindex="0">Raw Values</h3>
<p class="para">
The barcode example in <span class="x-name"><a href="Enumerations.html#TP40014097-CH12-XID_189" data-id="TP40014097-CH12-XID_189">Associated Values</a></span> shows how members of an enumeration can declare that they store associated values of different types. As an alternative to associated values, enumeration members can come prepopulated with default values (called <em>raw values</em>), which are all of the same type.
</p><p class="para">
Here’s an example that stores raw ASCII values alongside named enumeration members:
</p><section class="code-listing">
<span class="caption"></span>
<div class="code-sample">
<ul class="code-lines">
<li><code class="code-voice"><span class="kt">enum</span> <span class="vc">ASCIIControlCharacter</span>: <span class="n"></span> {</code></li>
<li><code class="code-voice"> <span class="kt">case</span> <span class="vc">Tab</span> = <span class="s">"\t"</span></code></li>
<li><code class="code-voice"> <span class="kt">case</span> <span class="vc">LineFeed</span> = <span class="s">"\n"</span></code></li>
<li><code class="code-voice"> <span class="kt">case</span> <span class="vc">CarriageReturn</span> = <span class="s">"\r"</span></code></li>
<li><code class="code-voice">}</code></li>
</ul>
</div>
</section><p class="para">
Here, the raw values for an enumeration called <code class="code-voice">ASCIIControlCharacter</code> are defined to be of type <code class="code-voice">Character</code>, and are set to some of the more common ASCII control characters. <code class="code-voice">Character</code> values are described in <span class="x-name"><a href="Strings and Characters.html#TP40014097-CH7-XID_368" data-id="TP40014097-CH7-XID_368">Strings and Characters</a></span>.
</p><p class="para">
Note that raw values are <em>not</em> the same as associated values. Raw values are set to prepopulated values when you first define the enumeration in your code, like the three ASCII codes above. The raw value for a particular enumeration member is always the same. Associated values are set when you create a new constant or variable based on one of the enumeration’s members, and can be different each time you do so.
</p><p class="para">
Raw values can be strings, characters, or any of the integer or floating-point number types. Each raw value must be unique within its enumeration declaration. When integers are used for raw values, they auto-increment if no value is specified for some of the enumeration members.
</p><p class="para">
The enumeration below is a refinement of the earlier <code class="code-voice">Planet</code> enumeration, with raw integer values to represent each planet’s order from the sun:
</p><section class="code-listing">
<span class="caption"></span>
<div class="code-sample">
<ul class="code-lines">
<li><code class="code-voice"><span class="kt">enum</span> <span class="vc">Planet</span>: <span class="n"></span> {</code></li>
<li><code class="code-voice"> <span class="kt">case</span> <span class="vc">Mercury</span> = <span class="m">1</span>, <span class="vc">Venus</span>, <span class="vc">Earth</span>, <span class="vc">Mars</span>, <span class="vc">Jupiter</span>, <span class="vc">Saturn</span>, <span class="vc">Uranus</span>, <span class="vc">Neptune</span></code></li>
<li><code class="code-voice">}</code></li>
</ul>
</div>
</section><p class="para">
Auto-incrementation means that <code class="code-voice">Planet.Venus</code> has a raw value of <code class="code-voice">2</code>, and so on.
</p><p class="para">
Access the raw value of an enumeration member with its <code class="code-voice">toRaw</code> method:
</p><section class="code-listing">
<span class="caption"></span>
<div class="code-sample">
<ul class="code-lines">
<li><code class="code-voice"><span class="kt">let</span> <span class="vc">earthsOrder</span> = <span class="vc">Planet</span>.<span class="vc">Earth</span>.<span class="vc">toRaw</span>()</code></li>
<li><code class="code-voice"><span class="c">// earthsOrder is 3</span></code></li>
</ul>
</div>
</section><p class="para">
Use an enumeration’s <code class="code-voice">fromRaw</code> method to try to find an enumeration member with a particular raw value. This example identifies Uranus from its raw value of <code class="code-voice">7</code>:
</p><section class="code-listing">
<span class="caption"></span>
<div class="code-sample">
<ul class="code-lines">
<li><code class="code-voice"><span class="kt">let</span> <span class="vc">possiblePlanet</span> = <span class="vc">Planet</span>.<span class="vc">fromRaw</span>(<span class="m">7</span>)</code></li>
<li><code class="code-voice"><span class="c">// possiblePlanet is of type Planet? and equals Planet.Uranus</span></code></li>
</ul>
</div>
</section><p class="para">
Not all possible <code class="code-voice">Int</code> values will find a matching planet, however. Because of this, the <code class="code-voice">fromRaw</code> method returns an <em>optional</em> enumeration member. In the example above, <code class="code-voice">possiblePlanet</code> is of type <code class="code-voice">Planet?</code>, or “optional <code class="code-voice">Planet</code>.”
</p><p class="para">
If you try to find a Planet with a position of <code class="code-voice">9</code>, the optional <code class="code-voice">Planet</code> value returned by <code class="code-voice">fromRaw</code> will be <code class="code-voice">nil</code>:
</p><section class="code-listing">
<span class="caption"></span>
<div class="code-sample">
<ul class="code-lines">
<li><code class="code-voice"><span class="kt">let</span> <span class="vc">positionToFind</span> = <span class="m">9</span></code></li>
<li><code class="code-voice"><span class="kt">if</span> <span class="kt">let</span> <span class="vc">somePlanet</span> = <span class="vc">Planet</span>.<span class="vc">fromRaw</span>(<span class="vc">positionToFind</span>) {</code></li>
<li><code class="code-voice"> <span class="kt">switch</span> <span class="vc">somePlanet</span> {</code></li>
<li><code class="code-voice"> <span class="kt">case</span> .<span class="vc">Earth</span>:</code></li>
<li><code class="code-voice"> <span class="vc">println</span>(<span class="s">"Mostly harmless"</span>)</code></li>
<li><code class="code-voice"> <span class="kt">default</span>:</code></li>
<li><code class="code-voice"> <span class="vc">println</span>(<span class="s">"Not a safe place for humans"</span>)</code></li>
<li><code class="code-voice"> }</code></li>
<li><code class="code-voice">} <span class="kt">else</span> {</code></li>
<li><code class="code-voice"> <span class="vc">println</span>(<span class="s">"There isn't a planet at position </span>\(<span class="vc">positionToFind</span>)<span class="s">"</span>)</code></li>
<li><code class="code-voice">}</code></li>
<li><code class="code-voice"><span class="c">// prints "There isn't a planet at position 9"</span></code></li>
</ul>
</div>
</section><p class="para">
This example uses optional binding to try to access a planet with a raw value of <code class="code-voice">9</code>. The statement <code class="code-voice">if let somePlanet = Planet.fromRaw(9)</code> retrieves an optional <code class="code-voice">Planet</code>, and sets <code class="code-voice">somePlanet</code> to the contents of that optional <code class="code-voice">Planet</code> if it can be retrieved. In this case, it is not possible to retrieve a planet with a position of <code class="code-voice">9</code>, and so the <code class="code-voice">else</code> branch is executed instead.
</p>
</section>
<section id="next_previous" class="">
<p class="previous-link"><a href="Closures.html#TP40014097-CH11-XID_117" data-id="TP40014097-CH11-XID_117">Closures</a></p>
<p class="next-link"><a href="Classes and Structures.html#TP40014097-CH13-XID_94" data-id="TP40014097-CH13-XID_94">Classes and Structures</a></p>
<p class="copyright">Copyright © 2014 Apple Inc. All rights reserved. <a class="link" href="http://www.apple.com/legal/terms/site.html" target="_blank" rel="external">Terms of Use</a> | <a class="link" href="http://www.apple.com/privacy/" target="_blank" rel="external">Privacy Policy</a> | Updated: 2014-06-02
</p>
</section>
</article>
</div>
<div id="big_button"></div>
<footer id="footer">
<div class="content-wrapper">
</div>
<script src="./resource/devpubs-1.1.15.js" type="text/javascript" charset="utf-8"></script> </footer> <div id="blackout"> <div id="preload"></div> </div> </body></html>