gcc/doc/gcc/gnu-objective-c-features/constant-string-objects.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 .. _constant-string-objects:
   7
   8 Constant String Objects
   9 ***********************
  10
  11 GNU Objective-C provides constant string objects that are generated
  12 directly by the compiler.  You declare a constant string object by
  13 prefixing a C constant string with the character :samp:`@`:
  14
  15 .. code-block:: objective-c
  16
  17     id myString = @"this is a constant string object";
  18
  19 The constant string objects are by default instances of the
  20 ``NXConstantString`` class which is provided by the GNU Objective-C
  21 runtime.  To get the definition of this class you must include the
  22 :samp:`objc/NXConstStr.h` header file.
  23
  24 User defined libraries may want to implement their own constant string
  25 class.  To be able to support them, the GNU Objective-C compiler provides
  26 a new command line options :option:`-fconstant-string-class=class-name`.
  27 The provided class should adhere to a strict structure, the same
  28 as ``NXConstantString`` 's structure:
  29
  30 .. code-block:: objective-c
  31
  32   @interface MyConstantStringClass
  33   {
  34     Class isa;
  35     char *c_string;
  36     unsigned int len;
  37   }
  38   @end
  39
  40 ``NXConstantString`` inherits from ``Object`` ; user class
  41 libraries may choose to inherit the customized constant string class
  42 from a different class than ``Object``.  There is no requirement in
  43 the methods the constant string class has to implement, but the final
  44 ivar layout of the class must be the compatible with the given
  45 structure.
  46
  47 When the compiler creates the statically allocated constant string
  48 object, the ``c_string`` field will be filled by the compiler with
  49 the string; the ``length`` field will be filled by the compiler with
  50 the string length; the ``isa`` pointer will be filled with
  51 ``NULL`` by the compiler, and it will later be fixed up automatically
  52 at runtime by the GNU Objective-C runtime library to point to the class
  53 which was set by the :option:`-fconstant-string-class` option when the
  54 object file is loaded (if you wonder how it works behind the scenes, the
  55 name of the class to use, and the list of static objects to fixup, are
  56 stored by the compiler in the object file in a place where the GNU
  57 runtime library will find them at runtime).
  58
  59 As a result, when a file is compiled with the
  60 :option:`-fconstant-string-class` option, all the constant string objects
  61 will be instances of the class specified as argument to this option.  It
  62 is possible to have multiple compilation units referring to different
  63 constant string classes, neither the compiler nor the linker impose any
  64 restrictions in doing this.