Documented the new -fconstant-string-class option.

From-SVN: r35537

libobjc/objc-features.texi

@@ -5,7 +5,14 @@
 @setchapternewpage odd
 @c %**end of header
      
-@node Top, Executing code before main, , (dir), (dir)
+@menu
+* Executing code before main::  
+* Type encoding::               
+* Garbage Collection::          
+* Constant string objects::     
+@end menu
+
+@node Top, Executing code before main, (dir), (dir)
 @comment  node-name,  next,  previous,  up
 
 @chapter GNU Objective-C runtime features
@@ -16,14 +23,8 @@ resources on the Internet that present the language.  Questions and
 comments about this document to Ovidiu Predescu
 @code{<ovidiu@@cup.hp.com>}.
 
-@menu
-* Executing code before main::
-* Type encoding::
-* Garbage Collection::
-@end menu
-
 
-@node Executing code before main, What you can and what you cannot do in +load, Top, Top
+@node Executing code before main, Type encoding, Top, Top
 @section @code{+load}: Executing code before main
 
 
@@ -101,14 +102,14 @@ You should be aware of its limitations when you decide to use it
 instead of @code{+initialize}.
 
 @menu
-* What you can and what you cannot do in +load::
+* What you can and what you cannot do in +load::  
 @end menu
 
 
-@node What you can and what you cannot do in +load, Type encoding, Executing code before main, Executing code before main
+@node What you can and what you cannot do in +load,  , Executing code before main, Executing code before main
 @subsection What you can and what you cannot do in @code{+load}
 
-The +load implementation in the GNU runtime guarantees you the following
+The @code{+load} implementation in the GNU runtime guarantees you the following
 things:
 
 @itemize @bullet
@@ -169,7 +170,7 @@ above apply to classes defined in bundle.
 
 
 
-@node Type encoding, Garbage Collection, What you can and what you cannot do in +load, Top
+@node Type encoding, Garbage Collection, Executing code before main, Top
 @section Type encoding
 
 The Objective-C compiler generates type encodings for all the
@@ -309,15 +310,13 @@ however, the type specifiers are only encoded when they appear in method
 argument types.
 
 
-@node Garbage Collection, , Type encoding, Top
-
-@page
+@node Garbage Collection, Constant string objects, Type encoding, Top
 @section Garbage Collection
 
 Support for a new memory management policy has been added by using a
 powerful conservative garbage collector, known as the
 Boehm-Demers-Weiser conservative garbage collector. It is available from
-@w{@uref{http://reality.sgi.com/boehm_mti/gc.html}}.
+@w{@uref{http://www.hpl.hp.com/personal/Hans_Boehm/gc/}}.
 
 To enable the support for it you have to configure the compiler using an
 additional argument, @w{@kbd{--enable-objc-gc}}. You need to have
@@ -387,6 +386,50 @@ represented by the @code{'!'} character. The
 specifier to the string type description of the instance variable named
 as argument.
 
+@c =========================================================================
+@node Constant string objects,  , Garbage Collection, Top
+@comment  node-name,  next,  previous,  up
+@section Constant string objects
+
+GNU Objective-C provides constant string objects that are generated
+directly by the compiler. You declare a constant string object by
+prefixing a C constant string with the character @code{@@}:
+
+@example
+  id myString = @@"this is a constant string object";
+@end example
+
+The constant string objects are usually instances of the
+@code{NXConstantString} class which is provided by the GNU Objective-C
+runtime. To get the definition of this class you must include the
+@file{objc/NXConstStr.h} header file.
+
+User defined libraries may want to implement their own constant string
+class. To be able to support them, the GNU Objective-C compiler provides
+a new command line options @code{-fconstant-string-class=<class
+name>}. The provided class should adhere to a strict structure, the same
+as @code{NXConstantString}'s structure:
+
+@example
+
+@@interface NXConstantString : Object
+@{
+  char *c_string;
+  unsigned int len;
+@}
+@@end
+
+@end example
+
+User class libraries may choose to inherit the customized constant
+string class from a different class than @code{Object}. There is no
+requirement in the methods the constant string class has to implement.
+
+When a file is compiled with the @code{-fconstant-string-class} option,
+all the constant string objects will be instances of the class specified
+as argument to this option. It is possible to have multiple compilation
+units referring to different constant string classes, neither the
+compiler nor the linker impose any restrictions in doing this.
 
 @bye