8 Three new features were introduced into clang at the same time:
9 *NSNumber Literals* provide a syntax for creating ``NSNumber`` from
10 scalar literal expressions; *Collection Literals* provide a short-hand
11 for creating arrays and dictionaries; *Object Subscripting* provides a
12 way to use subscripting with Objective-C objects. Users of Apple
13 compiler releases can use these features starting with the Apple LLVM
14 Compiler 4.0. Users of open-source LLVM.org compiler releases can use
15 these features starting with clang v3.1.
17 These language additions simplify common Objective-C programming
18 patterns, make programs more concise, and improve the safety of
21 This document describes how the features are implemented in clang, and
22 how to use them in your own programs.
27 The framework class ``NSNumber`` is used to wrap scalar values inside
28 objects: 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
31 wrapped in objects are also known as *boxed* values.
33 In Objective-C, any character, numeric or boolean literal prefixed with
34 the ``'@'`` character will evaluate to a pointer to an ``NSNumber``
35 object initialized with that value. C's type suffixes may be used to
36 control the size of numeric literals.
41 The following program illustrates the rules for ``NSNumber`` literals:
45 void main(int argc, const char *argv[]) {
46 // character literals.
47 NSNumber *theLetterZ = @'Z'; // equivalent to [NSNumber numberWithChar:'Z']
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]
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]
60 NSNumber *yesNumber = @YES; // equivalent to [NSNumber numberWithBool:YES]
61 NSNumber *noNumber = @NO; // equivalent to [NSNumber numberWithBool:NO]
64 NSNumber *trueNumber = @true; // equivalent to [NSNumber numberWithBool:(BOOL)true]
65 NSNumber *falseNumber = @false; // equivalent to [NSNumber numberWithBool:(BOOL)false]
72 NSNumber literals only support literal scalar values after the ``'@'``.
73 Consequently, ``@INT_MAX`` works, but ``@INT_MIN`` does not, because
74 they are defined like this:
78 #define INT_MAX 2147483647 /* max value for an int */
79 #define INT_MIN (-2147483647-1) /* min value for an int */
81 The definition of ``INT_MIN`` is not a simple literal, but a
82 parenthesized expression. Parenthesized expressions are supported using
83 the `boxed expression <#objc_boxed_expressions>`_ syntax, which is
84 described in the next section.
86 Because ``NSNumber`` does not currently support wrapping ``long double``
87 values, the use of a ``long double NSNumber`` literal (e.g.
88 ``@123.23L``) will be rejected by the compiler.
90 Previously, the ``BOOL`` type was simply a typedef for ``signed char``,
91 and ``YES`` and ``NO`` were macros that expand to ``(BOOL)1`` and
92 ``(BOOL)0`` respectively. To support ``@YES`` and ``@NO`` expressions,
93 these macros are now defined using new language keywords in
98 #if __has_feature(objc_bool)
99 #define YES __objc_yes
102 #define YES ((BOOL)1)
106 The 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.
110 Objective-C++ also supports ``@true`` and ``@false`` expressions, which
111 are equivalent to ``@YES`` and ``@NO``.
116 Objective-C provides a new syntax for boxing C expressions:
122 Expressions of scalar (numeric, enumerated, BOOL) and C string pointer
128 NSNumber *smallestInt = @(-INT_MAX - 1); // [NSNumber numberWithInt:(-INT_MAX - 1)]
129 NSNumber *piOverTwo = @(M_PI / 2); // [NSNumber numberWithDouble:(M_PI / 2)]
132 typedef enum { Red, Green, Blue } Color;
133 NSNumber *favoriteColor = @(Green); // [NSNumber numberWithInt:((int)Green)]
136 NSString *path = @(getenv("PATH")); // [NSString stringWithUTF8String:(getenv("PATH"))]
137 NSArray *pathComponents = [path componentsSeparatedByString:@":"];
142 Cocoa frameworks frequently define constant values using *enums.*
143 Although enum values are integral, they may not be used directly as
144 boxed literals (this avoids conflicts with future ``'@'``-prefixed
145 Objective-C keywords). Instead, an enum value must be placed inside a
146 boxed expression. The following example demonstrates configuring an
147 ``AVAudioRecorder`` using a dictionary that contains a boxed enumeration
153 AVAudioQualityMin = 0,
154 AVAudioQualityLow = 0x20,
155 AVAudioQualityMedium = 0x40,
156 AVAudioQualityHigh = 0x60,
157 AVAudioQualityMax = 0x7F
160 - (AVAudioRecorder *)recordToFile:(NSURL *)fileURL {
161 NSDictionary *settings = @{ AVEncoderAudioQualityKey : @(AVAudioQualityMax) };
162 return [[AVAudioRecorder alloc] initWithURL:fileURL settings:settings error:NULL];
165 The expression ``@(AVAudioQualityMax)`` converts ``AVAudioQualityMax``
166 to an integer type, and boxes the value accordingly. If the enum has a
167 :ref:`fixed underlying type <objc-fixed-enum>` as in:
171 typedef enum : unsigned char { Red, Green, Blue } Color;
172 NSNumber *red = @(Red), *green = @(Green), *blue = @(Blue); // => [NSNumber numberWithUnsignedChar:]
174 then the fixed underlying type will be used to select the correct
175 ``NSNumber`` creation method.
177 Boxing a value of enum type will result in a ``NSNumber`` pointer with a
178 creation method according to the underlying type of the enum, which can
179 be a :ref:`fixed underlying type <objc-fixed-enum>`
180 or a compiler-defined integer type capable of representing the values of
181 all the members of the enumeration:
185 typedef enum : unsigned char { Red, Green, Blue } Color;
187 NSNumber *nsCol = @(col); // => [NSNumber numberWithUnsignedChar:]
192 A C string literal prefixed by the ``'@'`` token denotes an ``NSString``
193 literal in the same way a numeric literal prefixed by the ``'@'`` token
194 denotes an ``NSNumber`` literal. When the type of the parenthesized
195 expression is ``(char *)`` or ``(const char *)``, the result of the
196 boxed expression is a pointer to an ``NSString`` object containing
197 equivalent character data, which is assumed to be '\\0'-terminated and
198 UTF-8 encoded. The following example converts C-style command line
199 arguments into ``NSString`` objects.
203 // Partition command line arguments into positional and option arguments.
204 NSMutableArray *args = [NSMutableArray new];
205 NSMutableDictionary *options = [NSMutableDictionary new];
207 const char *arg = *++argv;
208 if (strncmp(arg, "--", 2) == 0) {
209 options[@(arg + 2)] = @(*++argv); // --key value
211 [args addObject:@(arg)]; // positional argument
215 As with all C pointers, character pointer expressions can involve
216 arbitrary pointer arithmetic, therefore programmers must ensure that the
217 character data is valid. Passing ``NULL`` as the character pointer will
218 raise an exception at runtime. When possible, the compiler will reject
219 ``NULL`` character pointers used in boxed expressions.
224 Objective-C now supports a new expression syntax for creating immutable
225 array and dictionary container objects.
230 Immutable array expression:
234 NSArray *array = @[ @"Hello", NSApp, [NSNumber numberWithInt:42] ];
236 This creates an ``NSArray`` with 3 elements. The comma-separated
237 sub-expressions of an array literal can be any Objective-C object
238 pointer typed expression.
240 Immutable dictionary expression:
244 NSDictionary *dictionary = @{
245 @"name" : NSUserName(),
246 @"date" : [NSDate date],
247 @"processInfo" : [NSProcessInfo processInfo]
250 This creates an ``NSDictionary`` with 3 key/value pairs. Value
251 sub-expressions of a dictionary literal must be Objective-C object
252 pointer typed, as in array literals. Key sub-expressions must be of an
253 Objective-C object pointer type that implements the
254 ``<NSCopying>`` protocol.
259 Neither keys nor values can have the value ``nil`` in containers. If the
260 compiler can prove that a key or value is ``nil`` at compile time, then
261 a warning will be emitted. Otherwise, a runtime error will occur.
263 Using array and dictionary literals is safer than the variadic creation
264 forms commonly in use today. Array literal expressions expand to calls
265 to ``+[NSArray arrayWithObjects:count:]``, which validates that all
266 objects are non-``nil``. The variadic form,
267 ``+[NSArray arrayWithObjects:]`` uses ``nil`` as an argument list
268 terminator, which can lead to malformed array objects. Dictionary
269 literals are similarly created with
270 ``+[NSDictionary dictionaryWithObjects:forKeys:count:]`` which validates
271 all objects and keys, unlike
272 ``+[NSDictionary dictionaryWithObjectsAndKeys:]`` which also uses a
273 ``nil`` parameter as an argument list terminator.
278 Objective-C object pointer values can now be used with C's subscripting
284 The following code demonstrates the use of object subscripting syntax
285 with ``NSMutableArray`` and ``NSMutableDictionary`` objects:
289 NSMutableArray *array = ...;
290 NSUInteger idx = ...;
292 id oldObject = array[idx];
293 array[idx] = newObject; // replace oldObject with newObject
295 NSMutableDictionary *dictionary = ...;
297 oldObject = dictionary[key];
298 dictionary[key] = newObject; // replace oldObject with newObject
300 The next section explains how subscripting expressions map to accessor
306 Objective-C supports two kinds of subscript expressions: *array-style*
307 subscript expressions use integer typed subscripts; *dictionary-style*
308 subscript expressions use Objective-C object pointer typed subscripts.
309 Each type of subscript expression is mapped to a message send using a
310 predefined selector. The advantage of this design is flexibility: class
311 designers are free to introduce subscripting by declaring methods or by
312 adopting protocols. Moreover, because the method names are selected by
313 the type of the subscript, an object can be subscripted using both array
314 and dictionary styles.
316 Array-Style Subscripting
317 ^^^^^^^^^^^^^^^^^^^^^^^^
319 When the subscript operand has an integral type, the expression is
320 rewritten to use one of two different selectors, depending on whether
321 the element is being read or written. When an expression reads an
322 element using an integral index, as in the following example:
326 NSUInteger idx = ...;
327 id value = object[idx];
329 it is translated into a call to ``objectAtIndexedSubscript:``
333 id value = [object objectAtIndexedSubscript:idx];
335 When an expression writes an element using an integral index:
339 object[idx] = newValue;
341 it is translated to a call to ``setObject:atIndexedSubscript:``
345 [object setObject:newValue atIndexedSubscript:idx];
347 These message sends are then type-checked and performed just like
348 explicit message sends. The method used for objectAtIndexedSubscript:
349 must be declared with an argument of integral type and a return value of
350 some Objective-C object pointer type. The method used for
351 setObject:atIndexedSubscript: must be declared with its first argument
352 having some Objective-C pointer type and its second argument having
355 The meaning of indexes is left up to the declaring class. The compiler
356 will coerce the index to the appropriate argument type of the method it
357 uses for type-checking. For an instance of ``NSArray``, reading an
358 element using an index outside the range ``[0, array.count)`` will raise
359 an exception. For an instance of ``NSMutableArray``, assigning to an
360 element using an index within this range will replace that element, but
361 assigning to an element using an index outside this range will raise an
362 exception; no syntax is provided for inserting, appending, or removing
363 elements for mutable arrays.
365 A class need not declare both methods in order to take advantage of this
366 language feature. For example, the class ``NSArray`` declares only
367 ``objectAtIndexedSubscript:``, so that assignments to elements will fail
368 to type-check; moreover, its subclass ``NSMutableArray`` declares
369 ``setObject:atIndexedSubscript:``.
371 Dictionary-Style Subscripting
372 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
374 When the subscript operand has an Objective-C object pointer type, the
375 expression is rewritten to use one of two different selectors, depending
376 on whether the element is being read from or written to. When an
377 expression reads an element using an Objective-C object pointer
378 subscript operand, as in the following example:
383 id value = object[key];
385 it is translated into a call to the ``objectForKeyedSubscript:`` method:
389 id value = [object objectForKeyedSubscript:key];
391 When an expression writes an element using an Objective-C object pointer
396 object[key] = newValue;
398 it is translated to a call to ``setObject:forKeyedSubscript:``
402 [object setObject:newValue forKeyedSubscript:key];
404 The behavior of ``setObject:forKeyedSubscript:`` is class-specific; but
405 in general it should replace an existing value if one is already
406 associated with a key, otherwise it should add a new value for the key.
407 No syntax is provided for removing elements from mutable dictionaries.
412 An Objective-C subscript expression occurs when the base operand of the
413 C subscript operator has an Objective-C object pointer type. Since this
414 potentially collides with pointer arithmetic on the value, these
415 expressions are only supported under the modern Objective-C runtime,
416 which categorically forbids such arithmetic.
418 Currently, only subscripts of integral or Objective-C object pointer
419 type are supported. In C++, a class type can be used if it has a single
420 conversion function to an integral or Objective-C pointer type, in which
421 case that conversion is applied and analysis continues as appropriate.
422 Otherwise, the expression is ill-formed.
424 An Objective-C object subscript expression is always an l-value. If the
425 expression appears on the left-hand side of a simple assignment operator
426 (=), the element is written as described below. If the expression
427 appears 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
429 is always an Objective-C object pointer and no binary operators are
430 legal on such pointers. If the expression appears in any other position,
431 the element is read as described below. It is an error to take the
432 address of a subscript expression, or (in C++) to bind a reference to
435 Programs can use object subscripting with Objective-C object pointers of
436 type ``id``. Normal dynamic message send rules apply; the compiler must
437 see *some* declaration of the subscripting methods, and will pick the
438 declaration seen first.
443 Objects created using the literal or boxed expression syntax are not
444 guaranteed to be uniqued by the runtime, but nor are they guaranteed to
445 be newly-allocated. As such, the result of performing direct comparisons
446 against the location of an object literal (using ``==``, ``!=``, ``<``,
447 ``<=``, ``>``, or ``>=``) is not well-defined. This is usually a simple
448 mistake in code that intended to call the ``isEqual:`` method (or the
449 ``compare:`` method).
451 This caveat applies to compile-time string literals as well.
452 Historically, string literals (using the ``@"..."`` syntax) have been
453 uniqued across translation units during linking. This is an
454 implementation detail of the compiler and should not be relied upon. If
455 you are using such code, please use global string constants instead
456 (``NSString * const MyConst = @"..."``) or use ``isEqual:``.
461 To support the new syntax described above, the Objective-C
462 ``@``-expression grammar has the following new productions:
466 objc-at-expression : '@' (string-literal | encode-literal | selector-literal | protocol-literal | object-literal)
469 object-literal : ('+' | '-')? numeric-constant
476 boolean-constant : '__objc_yes' | '__objc_no' | 'true' | 'false' /* boolean keywords. */
479 array-literal : '[' assignment-expression-list ']'
482 assignment-expression-list : assignment-expression (',' assignment-expression-list)?
486 dictionary-literal : '{' key-value-list '}'
489 key-value-list : key-value-pair (',' key-value-list)?
493 key-value-pair : assignment-expression ':' assignment-expression
496 Note: ``@true`` and ``@false`` are only supported in Objective-C++.
501 Programs test for the new features by using clang's \_\_has\_feature
502 checks. Here are examples of their use:
506 #if __has_feature(objc_array_literals)
508 NSArray *elements = @[ @"H", @"He", @"O", @"C" ];
510 // old way (equivalent).
511 id objects[] = { @"H", @"He", @"O", @"C" };
512 NSArray *elements = [NSArray arrayWithObjects:objects count:4];
515 #if __has_feature(objc_dictionary_literals)
517 NSDictionary *masses = @{ @"H" : @1.0078, @"He" : @4.0026, @"O" : @15.9990, @"C" : @12.0096 };
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];
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);
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);
542 Code can use also ``__has_feature(objc_bool)`` to check for the
543 availability of numeric literals support. This checks for the new
544 ``__objc_yes / __objc_no`` keywords, which enable the use of
545 ``@YES / @NO`` literals.
547 To check whether boxed expressions are supported, use
548 ``__has_feature(objc_boxed_expressions)`` feature macro.