ObjectiveCLiterals.rst source code [clang_source_code/docs/ObjectiveCLiterals.rst]

1	====================
2	Objective-C Literals
3	====================
4
5	Introduction
6	============
7
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.
16
17	These language additions simplify common Objective-C programming
18	patterns, make programs more concise, and improve the safety of
19	container creation.
20
21	This document describes how the features are implemented in clang, and
22	how to use them in your own programs.
23
24	NSNumber Literals
25	=================
26
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.
32
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.
37
38	Examples
39	--------
40
41	The 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
69	Discussion
70	----------
71
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:
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
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.
85
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.
89
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
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
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.
109
110	Objective-C++ also supports ``@true`` and ``@false`` expressions, which
111	are equivalent to ``@YES`` and ``@NO``.
112
113	Boxed Expressions
114	=================
115
116	Objective-C provides a new syntax for boxing C expressions:
117
118	.. code-block:: objc
119
120	@( <expression> )
121
122	Expressions of scalar (numeric, enumerated, BOOL), C string pointer
123	and some C structures (via NSValue) 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
139	// structs.
140	NSValue *center = @(view.center); // Point p = view.center;
141	// [NSValue valueWithBytes:&p objCType:@encode(Point)];
142	NSValue *frame = @(view.frame); // Rect r = view.frame;
143	// [NSValue valueWithBytes:&r objCType:@encode(Rect)];
144
145	Boxed Enums
146	-----------
147
148	Cocoa frameworks frequently define constant values using enums.
149	Although enum values are integral, they may not be used directly as
150	boxed literals (this avoids conflicts with future ``'@'``-prefixed
151	Objective-C keywords). Instead, an enum value must be placed inside a
152	boxed expression. The following example demonstrates configuring an
153	``AVAudioRecorder`` using a dictionary that contains a boxed enumeration
154	value:
155
156	.. code-block:: objc
157
158	enum {
159	AVAudioQualityMin = 0,
160	AVAudioQualityLow = 0x20,
161	AVAudioQualityMedium = 0x40,
162	AVAudioQualityHigh = 0x60,
163	AVAudioQualityMax = 0x7F
164	};
165
166	- (AVAudioRecorder )recordToFile:(NSURL )fileURL {
167	NSDictionary *settings = @{ AVEncoderAudioQualityKey : @(AVAudioQualityMax) };
168	return [[AVAudioRecorder alloc] initWithURL:fileURL settings:settings error:NULL];
169	}
170
171	The expression ``@(AVAudioQualityMax)`` converts ``AVAudioQualityMax``
172	to an integer type, and boxes the value accordingly. If the enum has a
173	:ref:`fixed underlying type <objc-fixed-enum>` as in:
174
175	.. code-block:: objc
176
177	typedef enum : unsigned char { Red, Green, Blue } Color;
178	NSNumber red = @(Red), green = @(Green), *blue = @(Blue); // => [NSNumber numberWithUnsignedChar:]
179
180	then the fixed underlying type will be used to select the correct
181	``NSNumber`` creation method.
182
183	Boxing a value of enum type will result in a ``NSNumber`` pointer with a
184	creation method according to the underlying type of the enum, which can
185	be a :ref:`fixed underlying type <objc-fixed-enum>`
186	or a compiler-defined integer type capable of representing the values of
187	all the members of the enumeration:
188
189	.. code-block:: objc
190
191	typedef enum : unsigned char { Red, Green, Blue } Color;
192	Color col = Red;
193	NSNumber *nsCol = @(col); // => [NSNumber numberWithUnsignedChar:]
194
195	Boxed C Strings
196	---------------
197
198	A C string literal prefixed by the ``'@'`` token denotes an ``NSString``
199	literal in the same way a numeric literal prefixed by the ``'@'`` token
200	denotes an ``NSNumber`` literal. When the type of the parenthesized
201	expression is ``(char )`` or ``(const char )``, the result of the
202	boxed expression is a pointer to an ``NSString`` object containing
203	equivalent character data, which is assumed to be '\\0'-terminated and
204	UTF-8 encoded. The following example converts C-style command line
205	arguments into ``NSString`` objects.
206
207	.. code-block:: objc
208
209	// Partition command line arguments into positional and option arguments.
210	NSMutableArray *args = [NSMutableArray new];
211	NSMutableDictionary *options = [NSMutableDictionary new];
212	while (--argc) {
213	const char arg = ++argv;
214	if (strncmp(arg, "--", 2) == 0) {
215	options[@(arg + 2)] = @(*++argv); // --key value
216	} else {
217	[args addObject:@(arg)]; // positional argument
218	}
219	}
220
221	As with all C pointers, character pointer expressions can involve
222	arbitrary pointer arithmetic, therefore programmers must ensure that the
223	character data is valid. Passing ``NULL`` as the character pointer will
224	raise an exception at runtime. When possible, the compiler will reject
225	``NULL`` character pointers used in boxed expressions.
226
227	Boxed C Structures
228	------------------
229
230	Boxed expressions support construction of NSValue objects.
231	It said that C structures can be used, the only requirement is:
232	structure should be marked with ``objc_boxable`` attribute.
233	To support older version of frameworks and/or third-party libraries
234	you may need to add the attribute via ``typedef``.
235
236	.. code-block:: objc
237
238	struct __attribute__((objc_boxable)) Point {
239	// ...
240	};
241
242	typedef struct __attribute__((objc_boxable)) _Size {
243	// ...
244	} Size;
245
246	typedef struct _Rect {
247	// ...
248	} Rect;
249
250	struct Point p;
251	NSValue *point = @(p); // ok
252	Size s;
253	NSValue *size = @(s); // ok
254
255	Rect r;
256	NSValue *bad_rect = @(r); // error
257
258	typedef struct __attribute__((objc_boxable)) _Rect Rect;
259
260	NSValue *good_rect = @(r); // ok
261
262
263	Container Literals
264	==================
265
266	Objective-C now supports a new expression syntax for creating immutable
267	array and dictionary container objects.
268
269	Examples
270	--------
271
272	Immutable array expression:
273
274	.. code-block:: objc
275
276	NSArray *array = @[ @"Hello", NSApp, [NSNumber numberWithInt:42] ];
277
278	This creates an ``NSArray`` with 3 elements. The comma-separated
279	sub-expressions of an array literal can be any Objective-C object
280	pointer typed expression.
281
282	Immutable dictionary expression:
283
284	.. code-block:: objc
285
286	NSDictionary *dictionary = @{
287	@"name" : NSUserName(),
288	@"date" : [NSDate date],
289	@"processInfo" : [NSProcessInfo processInfo]
290	};
291
292	This creates an ``NSDictionary`` with 3 key/value pairs. Value
293	sub-expressions of a dictionary literal must be Objective-C object
294	pointer typed, as in array literals. Key sub-expressions must be of an
295	Objective-C object pointer type that implements the
296	``<NSCopying>`` protocol.
297
298	Discussion
299	----------
300
301	Neither keys nor values can have the value ``nil`` in containers. If the
302	compiler can prove that a key or value is ``nil`` at compile time, then
303	a warning will be emitted. Otherwise, a runtime error will occur.
304
305	Using array and dictionary literals is safer than the variadic creation
306	forms commonly in use today. Array literal expressions expand to calls
307	to ``+[NSArray arrayWithObjects:count:]``, which validates that all
308	objects are non-``nil``. The variadic form,
309	``+[NSArray arrayWithObjects:]`` uses ``nil`` as an argument list
310	terminator, which can lead to malformed array objects. Dictionary
311	literals are similarly created with
312	``+[NSDictionary dictionaryWithObjects:forKeys:count:]`` which validates
313	all objects and keys, unlike
314	``+[NSDictionary dictionaryWithObjectsAndKeys:]`` which also uses a
315	``nil`` parameter as an argument list terminator.
316
317	Object Subscripting
318	===================
319
320	Objective-C object pointer values can now be used with C's subscripting
321	operator.
322
323	Examples
324	--------
325
326	The following code demonstrates the use of object subscripting syntax
327	with ``NSMutableArray`` and ``NSMutableDictionary`` objects:
328
329	.. code-block:: objc
330
331	NSMutableArray *array = ...;
332	NSUInteger idx = ...;
333	id newObject = ...;
334	id oldObject = array[idx];
335	array[idx] = newObject; // replace oldObject with newObject
336
337	NSMutableDictionary *dictionary = ...;
338	NSString *key = ...;
339	oldObject = dictionary[key];
340	dictionary[key] = newObject; // replace oldObject with newObject
341
342	The next section explains how subscripting expressions map to accessor
343	methods.
344
345	Subscripting Methods
346	--------------------
347
348	Objective-C supports two kinds of subscript expressions: array-style
349	subscript expressions use integer typed subscripts; dictionary-style
350	subscript expressions use Objective-C object pointer typed subscripts.
351	Each type of subscript expression is mapped to a message send using a
352	predefined selector. The advantage of this design is flexibility: class
353	designers are free to introduce subscripting by declaring methods or by
354	adopting protocols. Moreover, because the method names are selected by
355	the type of the subscript, an object can be subscripted using both array
356	and dictionary styles.
357
358	Array-Style Subscripting
359	^^^^^^^^^^^^^^^^^^^^^^^^
360
361	When the subscript operand has an integral type, the expression is
362	rewritten to use one of two different selectors, depending on whether
363	the element is being read or written. When an expression reads an
364	element using an integral index, as in the following example:
365
366	.. code-block:: objc
367
368	NSUInteger idx = ...;
369	id value = object[idx];
370
371	it is translated into a call to ``objectAtIndexedSubscript:``
372
373	.. code-block:: objc
374
375	id value = [object objectAtIndexedSubscript:idx];
376
377	When an expression writes an element using an integral index:
378
379	.. code-block:: objc
380
381	object[idx] = newValue;
382
383	it is translated to a call to ``setObject:atIndexedSubscript:``
384
385	.. code-block:: objc
386
387	[object setObject:newValue atIndexedSubscript:idx];
388
389	These message sends are then type-checked and performed just like
390	explicit message sends. The method used for objectAtIndexedSubscript:
391	must be declared with an argument of integral type and a return value of
392	some Objective-C object pointer type. The method used for
393	setObject:atIndexedSubscript: must be declared with its first argument
394	having some Objective-C pointer type and its second argument having
395	integral type.
396
397	The meaning of indexes is left up to the declaring class. The compiler
398	will coerce the index to the appropriate argument type of the method it
399	uses for type-checking. For an instance of ``NSArray``, reading an
400	element using an index outside the range ``[0, array.count)`` will raise
401	an exception. For an instance of ``NSMutableArray``, assigning to an
402	element using an index within this range will replace that element, but
403	assigning to an element using an index outside this range will raise an
404	exception; no syntax is provided for inserting, appending, or removing
405	elements for mutable arrays.
406
407	A class need not declare both methods in order to take advantage of this
408	language feature. For example, the class ``NSArray`` declares only
409	``objectAtIndexedSubscript:``, so that assignments to elements will fail
410	to type-check; moreover, its subclass ``NSMutableArray`` declares
411	``setObject:atIndexedSubscript:``.
412
413	Dictionary-Style Subscripting
414	^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
415
416	When the subscript operand has an Objective-C object pointer type, the
417	expression is rewritten to use one of two different selectors, depending
418	on whether the element is being read from or written to. When an
419	expression reads an element using an Objective-C object pointer
420	subscript operand, as in the following example:
421
422	.. code-block:: objc
423
424	id key = ...;
425	id value = object[key];
426
427	it is translated into a call to the ``objectForKeyedSubscript:`` method:
428
429	.. code-block:: objc
430
431	id value = [object objectForKeyedSubscript:key];
432
433	When an expression writes an element using an Objective-C object pointer
434	subscript:
435
436	.. code-block:: objc
437
438	object[key] = newValue;
439
440	it is translated to a call to ``setObject:forKeyedSubscript:``
441
442	.. code-block:: objc
443
444	[object setObject:newValue forKeyedSubscript:key];
445
446	The behavior of ``setObject:forKeyedSubscript:`` is class-specific; but
447	in general it should replace an existing value if one is already
448	associated with a key, otherwise it should add a new value for the key.
449	No syntax is provided for removing elements from mutable dictionaries.
450
451	Discussion
452	----------
453
454	An Objective-C subscript expression occurs when the base operand of the
455	C subscript operator has an Objective-C object pointer type. Since this
456	potentially collides with pointer arithmetic on the value, these
457	expressions are only supported under the modern Objective-C runtime,
458	which categorically forbids such arithmetic.
459
460	Currently, only subscripts of integral or Objective-C object pointer
461	type are supported. In C++, a class type can be used if it has a single
462	conversion function to an integral or Objective-C pointer type, in which
463	case that conversion is applied and analysis continues as appropriate.
464	Otherwise, the expression is ill-formed.
465
466	An Objective-C object subscript expression is always an l-value. If the
467	expression appears on the left-hand side of a simple assignment operator
468	(=), the element is written as described below. If the expression
469	appears on the left-hand side of a compound assignment operator (e.g.
470	+=), the program is ill-formed, because the result of reading an element
471	is always an Objective-C object pointer and no binary operators are
472	legal on such pointers. If the expression appears in any other position,
473	the element is read as described below. It is an error to take the
474	address of a subscript expression, or (in C++) to bind a reference to
475	it.
476
477	Programs can use object subscripting with Objective-C object pointers of
478	type ``id``. Normal dynamic message send rules apply; the compiler must
479	see some declaration of the subscripting methods, and will pick the
480	declaration seen first.
481
482	Caveats
483	=======
484
485	Objects created using the literal or boxed expression syntax are not
486	guaranteed to be uniqued by the runtime, but nor are they guaranteed to
487	be newly-allocated. As such, the result of performing direct comparisons
488	against the location of an object literal (using ``==``, ``!=``, ``<``,
489	``<=``, ``>``, or ``>=``) is not well-defined. This is usually a simple
490	mistake in code that intended to call the ``isEqual:`` method (or the
491	``compare:`` method).
492
493	This caveat applies to compile-time string literals as well.
494	Historically, string literals (using the ``@"..."`` syntax) have been
495	uniqued across translation units during linking. This is an
496	implementation detail of the compiler and should not be relied upon. If
497	you are using such code, please use global string constants instead
498	(``NSString * const MyConst = @"..."``) or use ``isEqual:``.
499
500	Grammar Additions
501	=================
502
503	To support the new syntax described above, the Objective-C
504	``@``-expression grammar has the following new productions:
505
506	::
507
508	objc-at-expression : '@' (string-literal \| encode-literal \| selector-literal \| protocol-literal \| object-literal)
509	;
510
511	object-literal : ('+' \| '-')? numeric-constant
512	\| character-constant
513	\| boolean-constant
514	\| array-literal
515	\| dictionary-literal
516	;
517
518	boolean-constant : '__objc_yes' \| '__objc_no' \| 'true' \| 'false' /* boolean keywords. */
519	;
520
521	array-literal : '[' assignment-expression-list ']'
522	;
523
524	assignment-expression-list : assignment-expression (',' assignment-expression-list)?
525	\| /* empty */
526	;
527
528	dictionary-literal : '{' key-value-list '}'
529	;
530
531	key-value-list : key-value-pair (',' key-value-list)?
532	\| /* empty */
533	;
534
535	key-value-pair : assignment-expression ':' assignment-expression
536	;
537
538	Note: ``@true`` and ``@false`` are only supported in Objective-C++.
539
540	Availability Checks
541	===================
542
543	Programs test for the new features by using clang's \_\_has\_feature
544	checks. Here are examples of their use:
545
546	.. code-block:: objc
547
548	#if __has_feature(objc_array_literals)
549	// new way.
550	NSArray *elements = @[ @"H", @"He", @"O", @"C" ];
551	#else
552	// old way (equivalent).
553	id objects[] = { @"H", @"He", @"O", @"C" };
554	NSArray *elements = [NSArray arrayWithObjects:objects count:4];
555	#endif
556
557	#if __has_feature(objc_dictionary_literals)
558	// new way.
559	NSDictionary *masses = @{ @"H" : @1.0078, @"He" : @4.0026, @"O" : @15.9990, @"C" : @12.0096 };
560	#else
561	// old way (equivalent).
562	id keys[] = { @"H", @"He", @"O", @"C" };
563	id values[] = { [NSNumber numberWithDouble:1.0078], [NSNumber numberWithDouble:4.0026],
564	[NSNumber numberWithDouble:15.9990], [NSNumber numberWithDouble:12.0096] };
565	NSDictionary *masses = [NSDictionary dictionaryWithObjects:objects forKeys:keys count:4];
566	#endif
567
568	#if __has_feature(objc_subscripting)
569	NSUInteger i, count = elements.count;
570	for (i = 0; i < count; ++i) {
571	NSString *element = elements[i];
572	NSNumber *mass = masses[element];
573	NSLog(@"the mass of %@ is %@", element, mass);
574	}
575	#else
576	NSUInteger i, count = [elements count];
577	for (i = 0; i < count; ++i) {
578	NSString *element = [elements objectAtIndex:i];
579	NSNumber *mass = [masses objectForKey:element];
580	NSLog(@"the mass of %@ is %@", element, mass);
581	}
582	#endif
583
584	#if __has_attribute(objc_boxable)
585	typedef struct __attribute__((objc_boxable)) _Rect Rect;
586	#endif
587
588	#if __has_feature(objc_boxed_nsvalue_expressions)
589	CABasicAnimation animation = [CABasicAnimation animationWithKeyPath:@"position"];
590	animation.fromValue = @(layer.position);
591	animation.toValue = @(newPosition);
592	[layer addAnimation:animation forKey:@"move"];
593	#else
594	CABasicAnimation animation = [CABasicAnimation animationWithKeyPath:@"position"];
595	animation.fromValue = [NSValue valueWithCGPoint:layer.position];
596	animation.toValue = [NSValue valueWithCGPoint:newPosition];
597	[layer addAnimation:animation forKey:@"move"];
598	#endif
599
600	Code can use also ``__has_feature(objc_bool)`` to check for the
601	availability of numeric literals support. This checks for the new
602	``__objc_yes / __objc_no`` keywords, which enable the use of
603	``@YES / @NO`` literals.
604
605	To check whether boxed expressions are supported, use
606	``__has_feature(objc_boxed_expressions)`` feature macro.
607

Clang Project