gcc/doc/gcc/extensions-to-the-c-language-family/compound-literals.rst

   1 ..
   2   Copyright 1988-2022 Free Software Foundation, Inc.
   3   This is part of the GCC manual.
   4   For copying conditions, see the copyright.rst file.
   5
   6 .. index:: constructor expressions, initializations in expressions, structures, constructor expression, expressions, constructor, compound literals
   7
   8 .. _compound-literals:
   9
  10 Compound Literals
  11 *****************
  12
  13 .. The GNU C name for what C99 calls compound literals was "constructor expressions".
  14
  15 A compound literal looks like a cast of a brace-enclosed aggregate
  16 initializer list.  Its value is an object of the type specified in
  17 the cast, containing the elements specified in the initializer.
  18 Unlike the result of a cast, a compound literal is an lvalue.  ISO
  19 C99 and later support compound literals.  As an extension, GCC
  20 supports compound literals also in C90 mode and in C++, although
  21 as explained below, the C++ semantics are somewhat different.
  22
  23 Usually, the specified type of a compound literal is a structure.  Assume
  24 that ``struct foo`` and ``structure`` are declared as shown:
  25
  26 .. code-block:: c++
  27
  28   struct foo {int a; char b[2];} structure;
  29
  30 Here is an example of constructing a ``struct foo`` with a compound literal:
  31
  32 .. code-block:: c++
  33
  34   structure = ((struct foo) {x + y, 'a', 0});
  35
  36 This is equivalent to writing the following:
  37
  38 .. code-block:: c++
  39
  40   {
  41     struct foo temp = {x + y, 'a', 0};
  42     structure = temp;
  43   }
  44
  45 You can also construct an array, though this is dangerous in C++, as
  46 explained below.  If all the elements of the compound literal are
  47 (made up of) simple constant expressions suitable for use in
  48 initializers of objects of static storage duration, then the compound
  49 literal can be coerced to a pointer to its first element and used in
  50 such an initializer, as shown here:
  51
  52 .. code-block:: c++
  53
  54   char **foo = (char *[]) { "x", "y", "z" };
  55
  56 Compound literals for scalar types and union types are also allowed.  In
  57 the following example the variable ``i`` is initialized to the value
  58 ``2``, the result of incrementing the unnamed object created by
  59 the compound literal.
  60
  61 .. code-block:: c++
  62
  63   int i = ++(int) { 1 };
  64
  65 As a GNU extension, GCC allows initialization of objects with static storage
  66 duration by compound literals (which is not possible in ISO C99 because
  67 the initializer is not a constant).
  68 It is handled as if the object were initialized only with the brace-enclosed
  69 list if the types of the compound literal and the object match.
  70 The elements of the compound literal must be constant.
  71 If the object being initialized has array type of unknown size, the size is
  72 determined by the size of the compound literal.
  73
  74 .. code-block:: c++
  75
  76   static struct foo x = (struct foo) {1, 'a', 'b'};
  77   static int y[] = (int []) {1, 2, 3};
  78   static int z[] = (int [3]) {1};
  79
  80 The above lines are equivalent to the following:
  81
  82 .. code-block:: c++
  83
  84   static struct foo x = {1, 'a', 'b'};
  85   static int y[] = {1, 2, 3};
  86   static int z[] = {1, 0, 0};
  87
  88 In C, a compound literal designates an unnamed object with static or
  89 automatic storage duration.  In C++, a compound literal designates a
  90 temporary object that only lives until the end of its full-expression.
  91 As a result, well-defined C code that takes the address of a subobject
  92 of a compound literal can be undefined in C++, so G++ rejects
  93 the conversion of a temporary array to a pointer.  For instance, if
  94 the array compound literal example above appeared inside a function,
  95 any subsequent use of ``foo`` in C++ would have undefined behavior
  96 because the lifetime of the array ends after the declaration of ``foo``.
  97
  98 As an optimization, G++ sometimes gives array compound literals longer
  99 lifetimes: when the array either appears outside a function or has
 100 a ``const`` -qualified type.  If ``foo`` and its initializer had
 101 elements of type ``char *const`` rather than ``char *``, or if
 102 ``foo`` were a global variable, the array would have static storage
 103 duration.  But it is probably safest just to avoid the use of array
 104 compound literals in C++ code.