1====================
2Objective-C Literals
3====================
4
5Introduction
6============
7
8Three new features were introduced into clang at the same time:
9*NSNumber Literals* provide a syntax for creating ``NSNumber`` from
10scalar literal expressions; *Collection Literals* provide a short-hand
11for creating arrays and dictionaries; *Object Subscripting* provides a
12way to use subscripting with Objective-C objects. Users of Apple
13compiler releases can use these features starting with the Apple LLVM
14Compiler 4.0. Users of open-source LLVM.org compiler releases can use
15these features starting with clang v3.1.
16
17These language additions simplify common Objective-C programming
18patterns, make programs more concise, and improve the safety of
19container creation.
20
21This document describes how the features are implemented in clang, and
22how to use them in your own programs.
23
24NSNumber Literals
25=================
26
27The framework class ``NSNumber`` is used to wrap scalar values inside
28objects: signed and unsigned integers (``char``, ``short``, ``int``,
29``long``, ``long long``), floating point numbers (``float``,
30``double``), and boolean values (``BOOL``, C++ ``bool``). Scalar values
31wrapped in objects are also known as *boxed* values.
32
33In Objective-C, any character, numeric or boolean literal prefixed with
34the ``'@'`` character will evaluate to a pointer to an ``NSNumber``
35object initialized with that value. C's type suffixes may be used to
36control the size of numeric literals.
37
38Examples
39--------
40
41The following program illustrates the rules for ``NSNumber`` literals:
42
43.. code-block:: objc
44
45    void main(int argc, const char *argv[]) {
46      // character literals.
47      NSNumber *theLetterZ = @'Z';          // equivalent to [NSNumber numberWithChar:'Z']
48
49      // integral literals.
50      NSNumber *fortyTwo = @42;             // equivalent to [NSNumber numberWithInt:42]
51      NSNumber *fortyTwoUnsigned = @42U;    // equivalent to [NSNumber numberWithUnsignedInt:42U]
52      NSNumber *fortyTwoLong = @42L;        // equivalent to [NSNumber numberWithLong:42L]
53      NSNumber *fortyTwoLongLong = @42LL;   // equivalent to [NSNumber numberWithLongLong:42LL]
54
55      // floating point literals.
56      NSNumber *piFloat = @3.141592654F;    // equivalent to [NSNumber numberWithFloat:3.141592654F]
57      NSNumber *piDouble = @3.1415926535;   // equivalent to [NSNumber numberWithDouble:3.1415926535]
58
59      // BOOL literals.
60      NSNumber *yesNumber = @YES;           // equivalent to [NSNumber numberWithBool:YES]
61      NSNumber *noNumber = @NO;             // equivalent to [NSNumber numberWithBool:NO]
62
63    #ifdef __cplusplus
64      NSNumber *trueNumber = @true;         // equivalent to [NSNumber numberWithBool:(BOOL)true]
65      NSNumber *falseNumber = @false;       // equivalent to [NSNumber numberWithBool:(BOOL)false]
66    #endif
67    }
68
69Discussion
70----------
71
72NSNumber literals only support literal scalar values after the ``'@'``.
73Consequently, ``@INT_MAX`` works, but ``@INT_MIN`` does not, because
74they are defined like this:
75
76.. code-block:: objc
77
78    #define INT_MAX   2147483647  /* max value for an int */
79    #define INT_MIN   (-2147483647-1) /* min value for an int */
80
81The definition of ``INT_MIN`` is not a simple literal, but a
82parenthesized expression. Parenthesized expressions are supported using
83the `boxed expression <#objc_boxed_expressions>`_ syntax, which is
84described in the next section.
85
86Because ``NSNumber`` does not currently support wrapping ``long double``
87values, the use of a ``long double NSNumber`` literal (e.g.
88``@123.23L``) will be rejected by the compiler.
89
90Previously, the ``BOOL`` type was simply a typedef for ``signed char``,
91and ``YES`` and ``NO`` were macros that expand to ``(BOOL)1`` and
92``(BOOL)0`` respectively. To support ``@YES`` and ``@NO`` expressions,
93these macros are now defined using new language keywords in
94``<objc/objc.h>``:
95
96.. code-block:: objc
97
98    #if __has_feature(objc_bool)
99    #define YES             __objc_yes
100    #define NO              __objc_no
101    #else
102    #define YES             ((BOOL)1)
103    #define NO              ((BOOL)0)
104    #endif
105
106The compiler implicitly converts ``__objc_yes`` and ``__objc_no`` to
107``(BOOL)1`` and ``(BOOL)0``. The keywords are used to disambiguate
108``BOOL`` and integer literals.
109
110Objective-C++ also supports ``@true`` and ``@false`` expressions, which
111are equivalent to ``@YES`` and ``@NO``.
112
113Boxed Expressions
114=================
115
116Objective-C provides a new syntax for boxing C expressions:
117
118.. code-block:: objc
119
120    @( <expression> )
121
122Expressions of scalar (numeric, enumerated, BOOL) and C string pointer
123types are supported:
124
125.. code-block:: objc
126
127    // numbers.
128    NSNumber *smallestInt = @(-INT_MAX - 1);  // [NSNumber numberWithInt:(-INT_MAX - 1)]
129    NSNumber *piOverTwo = @(M_PI / 2);        // [NSNumber numberWithDouble:(M_PI / 2)]
130
131    // enumerated types.
132    typedef enum { Red, Green, Blue } Color;
133    NSNumber *favoriteColor = @(Green);       // [NSNumber numberWithInt:((int)Green)]
134
135    // strings.
136    NSString *path = @(getenv("PATH"));       // [NSString stringWithUTF8String:(getenv("PATH"))]
137    NSArray *pathComponents = [path componentsSeparatedByString:@":"];
138
139Boxed Enums
140-----------
141
142Cocoa frameworks frequently define constant values using *enums.*
143Although enum values are integral, they may not be used directly as
144boxed literals (this avoids conflicts with future ``'@'``-prefixed
145Objective-C keywords). Instead, an enum value must be placed inside a
146boxed expression. The following example demonstrates configuring an
147``AVAudioRecorder`` using a dictionary that contains a boxed enumeration
148value:
149
150.. code-block:: objc
151
152    enum {
153      AVAudioQualityMin = 0,
154      AVAudioQualityLow = 0x20,
155      AVAudioQualityMedium = 0x40,
156      AVAudioQualityHigh = 0x60,
157      AVAudioQualityMax = 0x7F
158    };
159
160    - (AVAudioRecorder *)recordToFile:(NSURL *)fileURL {
161      NSDictionary *settings = @{ AVEncoderAudioQualityKey : @(AVAudioQualityMax) };
162      return [[AVAudioRecorder alloc] initWithURL:fileURL settings:settings error:NULL];
163    }
164
165The expression ``@(AVAudioQualityMax)`` converts ``AVAudioQualityMax``
166to an integer type, and boxes the value accordingly. If the enum has a
167:ref:`fixed underlying type <objc-fixed-enum>` as in:
168
169.. code-block:: objc
170
171    typedef enum : unsigned char { Red, Green, Blue } Color;
172    NSNumber *red = @(Red), *green = @(Green), *blue = @(Blue); // => [NSNumber numberWithUnsignedChar:]
173
174then the fixed underlying type will be used to select the correct
175``NSNumber`` creation method.
176
177Boxing a value of enum type will result in a ``NSNumber`` pointer with a
178creation method according to the underlying type of the enum, which can
179be a :ref:`fixed underlying type <objc-fixed-enum>`
180or a compiler-defined integer type capable of representing the values of
181all the members of the enumeration:
182
183.. code-block:: objc
184
185    typedef enum : unsigned char { Red, Green, Blue } Color;
186    Color col = Red;
187    NSNumber *nsCol = @(col); // => [NSNumber numberWithUnsignedChar:]
188
189Boxed C Strings
190---------------
191
192A C string literal prefixed by the ``'@'`` token denotes an ``NSString``
193literal in the same way a numeric literal prefixed by the ``'@'`` token
194denotes an ``NSNumber`` literal. When the type of the parenthesized
195expression is ``(char *)`` or ``(const char *)``, the result of the
196boxed expression is a pointer to an ``NSString`` object containing
197equivalent character data, which is assumed to be '\\0'-terminated and
198UTF-8 encoded. The following example converts C-style command line
199arguments into ``NSString`` objects.
200
201.. code-block:: objc
202
203    // Partition command line arguments into positional and option arguments.
204    NSMutableArray *args = [NSMutableArray new];
205    NSMutableDictionary *options = [NSMutableDictionary new];
206    while (--argc) {
207        const char *arg = *++argv;
208        if (strncmp(arg, "--", 2) == 0) {
209            options[@(arg + 2)] = @(*++argv);   // --key value
210        } else {
211            [args addObject:@(arg)];            // positional argument
212        }
213    }
214
215As with all C pointers, character pointer expressions can involve
216arbitrary pointer arithmetic, therefore programmers must ensure that the
217character data is valid. Passing ``NULL`` as the character pointer will
218raise an exception at runtime. When possible, the compiler will reject
219``NULL`` character pointers used in boxed expressions.
220
221Container Literals
222==================
223
224Objective-C now supports a new expression syntax for creating immutable
225array and dictionary container objects.
226
227Examples
228--------
229
230Immutable array expression:
231
232.. code-block:: objc
233
234    NSArray *array = @[ @"Hello", NSApp, [NSNumber numberWithInt:42] ];
235
236This creates an ``NSArray`` with 3 elements. The comma-separated
237sub-expressions of an array literal can be any Objective-C object
238pointer typed expression.
239
240Immutable dictionary expression:
241
242.. code-block:: objc
243
244    NSDictionary *dictionary = @{
245        @"name" : NSUserName(),
246        @"date" : [NSDate date],
247        @"processInfo" : [NSProcessInfo processInfo]
248    };
249
250This creates an ``NSDictionary`` with 3 key/value pairs. Value
251sub-expressions of a dictionary literal must be Objective-C object
252pointer typed, as in array literals. Key sub-expressions must be of an
253Objective-C object pointer type that implements the
254``<NSCopying>`` protocol.
255
256Discussion
257----------
258
259Neither keys nor values can have the value ``nil`` in containers. If the
260compiler can prove that a key or value is ``nil`` at compile time, then
261a warning will be emitted. Otherwise, a runtime error will occur.
262
263Using array and dictionary literals is safer than the variadic creation
264forms commonly in use today. Array literal expressions expand to calls
265to ``+[NSArray arrayWithObjects:count:]``, which validates that all
266objects are non-``nil``. The variadic form,
267``+[NSArray arrayWithObjects:]`` uses ``nil`` as an argument list
268terminator, which can lead to malformed array objects. Dictionary
269literals are similarly created with
270``+[NSDictionary dictionaryWithObjects:forKeys:count:]`` which validates
271all objects and keys, unlike
272``+[NSDictionary dictionaryWithObjectsAndKeys:]`` which also uses a
273``nil`` parameter as an argument list terminator.
274
275Object Subscripting
276===================
277
278Objective-C object pointer values can now be used with C's subscripting
279operator.
280
281Examples
282--------
283
284The following code demonstrates the use of object subscripting syntax
285with ``NSMutableArray`` and ``NSMutableDictionary`` objects:
286
287.. code-block:: objc
288
289    NSMutableArray *array = ...;
290    NSUInteger idx = ...;
291    id newObject = ...;
292    id oldObject = array[idx];
293    array[idx] = newObject;         // replace oldObject with newObject
294
295    NSMutableDictionary *dictionary = ...;
296    NSString *key = ...;
297    oldObject = dictionary[key];
298    dictionary[key] = newObject;    // replace oldObject with newObject
299
300The next section explains how subscripting expressions map to accessor
301methods.
302
303Subscripting Methods
304--------------------
305
306Objective-C supports two kinds of subscript expressions: *array-style*
307subscript expressions use integer typed subscripts; *dictionary-style*
308subscript expressions use Objective-C object pointer typed subscripts.
309Each type of subscript expression is mapped to a message send using a
310predefined selector. The advantage of this design is flexibility: class
311designers are free to introduce subscripting by declaring methods or by
312adopting protocols. Moreover, because the method names are selected by
313the type of the subscript, an object can be subscripted using both array
314and dictionary styles.
315
316Array-Style Subscripting
317^^^^^^^^^^^^^^^^^^^^^^^^
318
319When the subscript operand has an integral type, the expression is
320rewritten to use one of two different selectors, depending on whether
321the element is being read or written. When an expression reads an
322element using an integral index, as in the following example:
323
324.. code-block:: objc
325
326    NSUInteger idx = ...;
327    id value = object[idx];
328
329it is translated into a call to ``objectAtIndexedSubscript:``
330
331.. code-block:: objc
332
333    id value = [object objectAtIndexedSubscript:idx];
334
335When an expression writes an element using an integral index:
336
337.. code-block:: objc
338
339    object[idx] = newValue;
340
341it is translated to a call to ``setObject:atIndexedSubscript:``
342
343.. code-block:: objc
344
345    [object setObject:newValue atIndexedSubscript:idx];
346
347These message sends are then type-checked and performed just like
348explicit message sends. The method used for objectAtIndexedSubscript:
349must be declared with an argument of integral type and a return value of
350some Objective-C object pointer type. The method used for
351setObject:atIndexedSubscript: must be declared with its first argument
352having some Objective-C pointer type and its second argument having
353integral type.
354
355The meaning of indexes is left up to the declaring class. The compiler
356will coerce the index to the appropriate argument type of the method it
357uses for type-checking. For an instance of ``NSArray``, reading an
358element using an index outside the range ``[0, array.count)`` will raise
359an exception. For an instance of ``NSMutableArray``, assigning to an
360element using an index within this range will replace that element, but
361assigning to an element using an index outside this range will raise an
362exception; no syntax is provided for inserting, appending, or removing
363elements for mutable arrays.
364
365A class need not declare both methods in order to take advantage of this
366language feature. For example, the class ``NSArray`` declares only
367``objectAtIndexedSubscript:``, so that assignments to elements will fail
368to type-check; moreover, its subclass ``NSMutableArray`` declares
369``setObject:atIndexedSubscript:``.
370
371Dictionary-Style Subscripting
372^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
373
374When the subscript operand has an Objective-C object pointer type, the
375expression is rewritten to use one of two different selectors, depending
376on whether the element is being read from or written to. When an
377expression reads an element using an Objective-C object pointer
378subscript operand, as in the following example:
379
380.. code-block:: objc
381
382    id key = ...;
383    id value = object[key];
384
385it is translated into a call to the ``objectForKeyedSubscript:`` method:
386
387.. code-block:: objc
388
389    id value = [object objectForKeyedSubscript:key];
390
391When an expression writes an element using an Objective-C object pointer
392subscript:
393
394.. code-block:: objc
395
396    object[key] = newValue;
397
398it is translated to a call to ``setObject:forKeyedSubscript:``
399
400.. code-block:: objc
401
402    [object setObject:newValue forKeyedSubscript:key];
403
404The behavior of ``setObject:forKeyedSubscript:`` is class-specific; but
405in general it should replace an existing value if one is already
406associated with a key, otherwise it should add a new value for the key.
407No syntax is provided for removing elements from mutable dictionaries.
408
409Discussion
410----------
411
412An Objective-C subscript expression occurs when the base operand of the
413C subscript operator has an Objective-C object pointer type. Since this
414potentially collides with pointer arithmetic on the value, these
415expressions are only supported under the modern Objective-C runtime,
416which categorically forbids such arithmetic.
417
418Currently, only subscripts of integral or Objective-C object pointer
419type are supported. In C++, a class type can be used if it has a single
420conversion function to an integral or Objective-C pointer type, in which
421case that conversion is applied and analysis continues as appropriate.
422Otherwise, the expression is ill-formed.
423
424An Objective-C object subscript expression is always an l-value. If the
425expression appears on the left-hand side of a simple assignment operator
426(=), the element is written as described below. If the expression
427appears on the left-hand side of a compound assignment operator (e.g.
428+=), the program is ill-formed, because the result of reading an element
429is always an Objective-C object pointer and no binary operators are
430legal on such pointers. If the expression appears in any other position,
431the element is read as described below. It is an error to take the
432address of a subscript expression, or (in C++) to bind a reference to
433it.
434
435Programs can use object subscripting with Objective-C object pointers of
436type ``id``. Normal dynamic message send rules apply; the compiler must
437see *some* declaration of the subscripting methods, and will pick the
438declaration seen first.
439
440Caveats
441=======
442
443Objects created using the literal or boxed expression syntax are not
444guaranteed to be uniqued by the runtime, but nor are they guaranteed to
445be newly-allocated. As such, the result of performing direct comparisons
446against the location of an object literal (using ``==``, ``!=``, ``<``,
447``<=``, ``>``, or ``>=``) is not well-defined. This is usually a simple
448mistake in code that intended to call the ``isEqual:`` method (or the
449``compare:`` method).
450
451This caveat applies to compile-time string literals as well.
452Historically, string literals (using the ``@"..."`` syntax) have been
453uniqued across translation units during linking. This is an
454implementation detail of the compiler and should not be relied upon. If
455you are using such code, please use global string constants instead
456(``NSString * const MyConst = @"..."``) or use ``isEqual:``.
457
458Grammar Additions
459=================
460
461To support the new syntax described above, the Objective-C
462``@``-expression grammar has the following new productions:
463
464::
465
466    objc-at-expression : '@' (string-literal | encode-literal | selector-literal | protocol-literal | object-literal)
467                       ;
468
469    object-literal : ('+' | '-')? numeric-constant
470                   | character-constant
471                   | boolean-constant
472                   | array-literal
473                   | dictionary-literal
474                   ;
475
476    boolean-constant : '__objc_yes' | '__objc_no' | 'true' | 'false'  /* boolean keywords. */
477                     ;
478
479    array-literal : '[' assignment-expression-list ']'
480                  ;
481
482    assignment-expression-list : assignment-expression (',' assignment-expression-list)?
483                               | /* empty */
484                               ;
485
486    dictionary-literal : '{' key-value-list '}'
487                       ;
488
489    key-value-list : key-value-pair (',' key-value-list)?
490                   | /* empty */
491                   ;
492
493    key-value-pair : assignment-expression ':' assignment-expression
494                   ;
495
496Note: ``@true`` and ``@false`` are only supported in Objective-C++.
497
498Availability Checks
499===================
500
501Programs test for the new features by using clang's \_\_has\_feature
502checks. Here are examples of their use:
503
504.. code-block:: objc
505
506    #if __has_feature(objc_array_literals)
507        // new way.
508        NSArray *elements = @[ @"H", @"He", @"O", @"C" ];
509    #else
510        // old way (equivalent).
511        id objects[] = { @"H", @"He", @"O", @"C" };
512        NSArray *elements = [NSArray arrayWithObjects:objects count:4];
513    #endif
514
515    #if __has_feature(objc_dictionary_literals)
516        // new way.
517        NSDictionary *masses = @{ @"H" : @1.0078,  @"He" : @4.0026, @"O" : @15.9990, @"C" : @12.0096 };
518    #else
519        // old way (equivalent).
520        id keys[] = { @"H", @"He", @"O", @"C" };
521        id values[] = { [NSNumber numberWithDouble:1.0078], [NSNumber numberWithDouble:4.0026],
522                        [NSNumber numberWithDouble:15.9990], [NSNumber numberWithDouble:12.0096] };
523        NSDictionary *masses = [NSDictionary dictionaryWithObjects:objects forKeys:keys count:4];
524    #endif
525
526    #if __has_feature(objc_subscripting)
527        NSUInteger i, count = elements.count;
528        for (i = 0; i < count; ++i) {
529            NSString *element = elements[i];
530            NSNumber *mass = masses[element];
531            NSLog(@"the mass of %@ is %@", element, mass);
532        }
533    #else
534        NSUInteger i, count = [elements count];
535        for (i = 0; i < count; ++i) {
536            NSString *element = [elements objectAtIndex:i];
537            NSNumber *mass = [masses objectForKey:element];
538            NSLog(@"the mass of %@ is %@", element, mass);
539        }
540    #endif
541
542Code can use also ``__has_feature(objc_bool)`` to check for the
543availability of numeric literals support. This checks for the new
544``__objc_yes / __objc_no`` keywords, which enable the use of
545``@YES / @NO`` literals.
546
547To check whether boxed expressions are supported, use
548``__has_feature(objc_boxed_expressions)`` feature macro.
549