MacOS-X compatibility fixes and improved documentation about class cluster

initialisers.


git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/libs/base/trunk@20012 72102866-910b-0410-8b05-ffd578937521

ChangeLog

@@ -1,3 +1,14 @@
+2004-09-07 Richard Frith-Macdonald <rfm@gnu.org>
+
+	* Source/NSArray.m:
+	* Source/NSDictionary.m:
+	* Source/NSSet.m:
+	* Source/NSString.m:
+	Changes to designated initiailiser stuff for MacOS-X compatibility.
+	Call -init to maintain the chain from subclasses to superclasses,
+	but document the 'designated initialisers' as being the richer methods
+	which may be used in GNUstep to make all the other initialisers work.
+
 2004-09-04  Adam Fedor  <fedor@gnu.org>
 
 	* Version 1.10.0

Headers/Foundation/NSArray.h

@@ -52,6 +52,7 @@
 - (unsigned) indexOfObject: (id)anObject inRange: (NSRange)aRange;
 - (unsigned) indexOfObjectIdenticalTo: (id)anObject;
 - (unsigned) indexOfObjectIdenticalTo: (id)anObject inRange: (NSRange)aRange;
+- (id) init;
 - (id) initWithArray: (NSArray*)array;
 #ifndef	STRICT_OPENSTEP
 - (id) initWithArray: (NSArray*)array copyItems: (BOOL)shouldCopy;

Headers/Foundation/NSDictionary.h

@@ -52,6 +52,7 @@
 - (NSString*) descriptionWithLocale: (NSDictionary*)locale
 			     indent: (unsigned int)level;
 
+- (id) init;
 - (id) initWithContentsOfFile: (NSString*)path;
 #ifndef	STRICT_OPENSTEP
 - (id) initWithContentsOfURL: (NSURL*)aURL;

Headers/Foundation/NSSet.h

@@ -51,6 +51,7 @@
 - (NSString*) description;
 - (NSString*) descriptionWithLocale: (NSDictionary*)locale;
 
+- (id) init;
 - (id) initWithArray: (NSArray*)other;
 - (id) initWithObjects: (id)firstObject, ...;
 - (id) initWithObjects: (id*)objects

Headers/Foundation/NSString.h

@@ -184,6 +184,7 @@ enum {
 + (id) stringWithContentsOfFile:(NSString *)path;
 
 // Initializing Newly Allocated Strings
+- (id) init;
 #ifndef	STRICT_OPENSTEP
 - (id) initWithBytes: (const void*)bytes
 	      length: (unsigned int)length

Source/NSArray.m

@@ -517,9 +517,34 @@ static SEL	rlSel;
   return NSNotFound;
 }
 
+/**
+ * <p>In MacOS-X class clusters do not have designated initialisers,
+ * and there is a general rule that -init is treated as the designated
+ * initialiser of the class cluster, but that other intitialisers
+ * may not work s expected an would need to be individually overridden
+ * in any subclass.
+ * </p>
+ * <p>GNUstep tries to make it easier to subclass a class cluster,
+ * by making class clusters follow the same convention as normal
+ * classes, so the designated initialiser is the <em>richest</em>
+ * initialiser.  This means that all other initialisers call the
+ * documented designated initialiser (which calls -init only for
+ * MacOS-X compatibility), and anyone writing a subclass only needs
+ * to override that one initialiser in order to have all the other
+ * ones work.
+ * </p>
+ * <p>For MacOS-X compatibility, you may also need to override various
+ * other initialisers.  Exactly which ones, you will need to determine
+ * by trial on a MacOS-X system ... and may vary between releases of
+ * MacOS-X.  So to be safe, on MacOS-X you probably need to re-implement
+ * <em>all</em> the class cluster initialisers you might use in conjunction
+ * with your subclass.
+ * </p>
+ */
 - (id) init
 {
-  return [self initWithObjects: (id*)0 count: 0];
+  self = [super init];
+  return self;
 }
 
 /**
@@ -742,15 +767,17 @@ static SEL	rlSel;
   return self;
 }
 
-/** <init />
- * Initialize the array with count objects.<br />
+/** <init /> <override-subclass />
+ * This should initialize the array with count (may be zero) objects.<br />
  * Retains each object placed in the array.<br />
- * Like all initializers, may change the value of self before returning it.
+ * Calls -init (which does nothing but maintain MacOS-X compatibility),
+ * and needs to be re-implemented in subclasses in order to have all
+ * other initialisers work.
  */
 - (id) initWithObjects: (id*)objects count: (unsigned)count
 {
-  [self subclassResponsibility: _cmd];
-  return nil;
+  self = [self init];
+  return self;
 }
 
 /**
@@ -1281,14 +1308,17 @@ compare(id elem1, id elem2, void* context)
   return NSMutableArrayClass;
 }
 
-/** <init />
+/** <init /> <override-subclass />
  * Initialise the array with the specified capacity ... this
- * should ensure that the array can have numItems added efficiently.
+ * should ensure that the array can have numItems added efficiently.<br />
+ * Calls -init (which does nothing but maintain MacOS-X compatibility),
+ * and needs to be re-implemented in subclasses in order to have all
+ * other initialisers work.
  */
 - (id) initWithCapacity: (unsigned)numItems
 {
-  [self subclassResponsibility: _cmd];
-  return nil;
+  self = [self init];
+  return self;
 }
 
 /** <override-subclass />
@@ -1386,7 +1416,9 @@ compare(id elem1, id elem2, void* context)
     initWithCapacity: numItems]);
 }
 
-/** <init /> Override our superclass's designated initializer to go our's */
+/**
+ * Override our superclass's designated initializer to go our's
+ */
 - (id) initWithObjects: (id*)objects count: (unsigned)count
 {
   self = [self initWithCapacity: count];

Source/NSDictionary.m

@@ -119,18 +119,50 @@ static SEL	appSel;
 }
 
 /**
+ * <p>In MacOS-X class clusters do not have designated initialisers,
+ * and there is a general rule that -init is treated as the designated
+ * initialiser of the class cluster, but that other intitialisers
+ * may not work s expected an would need to be individually overridden
+ * in any subclass.
+ * </p>
+ * <p>GNUstep tries to make it easier to subclass a class cluster,
+ * by making class clusters follow the same convention as normal
+ * classes, so the designated initialiser is the <em>richest</em>
+ * initialiser.  This means that all other initialisers call the
+ * documented designated initialiser (which calls -init only for
+ * MacOS-X compatibility), and anyone writing a subclass only needs
+ * to override that one initialiser in order to have all the other
+ * ones work.
+ * </p>
+ * <p>For MacOS-X compatibility, you may also need to override various
+ * other initialisers.  Exactly which ones, you will need to determine
+ * by trial on a MacOS-X system ... and may vary between releases of
+ * MacOS-X.  So to be safe, on MacOS-X you probably need to re-implement
+ * <em>all</em> the class cluster initialisers you might use in conjunction
+ * with your subclass.
+ * </p>
+ */
+- (id) init
+{
+  self = [super init];
+  return self;
+}
+
+/** <init /> <override-subclass />
  * Initializes contents to the given objects and keys.
  * The two arrays must have the same size.
  * The n th element of the objects array is associated with the n th
- * element of the keys array.
- * <init />
+ * element of the keys array.<br />
+ * Calls -init (which does nothing but maintain MacOS-X compatibility),
+ * and needs to be re-implemented in subclasses in order to have all
+ * other initialisers work.
  */
 - (id) initWithObjects: (id*)objects
 	       forKeys: (id*)keys
 		 count: (unsigned)count
 {
-  [self subclassResponsibility: _cmd];
-  return 0;
+  self = [self init];
+  return self;
 }
 
 /**
@@ -446,12 +478,6 @@ static SEL	appSel;
     initWithObjects: &object forKeys: &key count: 1]);
 }
 
-/* Override superclass's designated initializer */
-- (id) init
-{
-  return [self initWithObjects: NULL forKeys: NULL count: 0];
-}
-
 /**
  * Initializes with the keys and objects of otherDictionary.
  * (The keys and objects are not copied.)
@@ -1101,17 +1127,19 @@ compareIt(id o1, id o2, void* context)
   return NSMutableDictionaryClass;
 }
 
-/**
- *  Initializes an empty dictionary with memory preallocated for given number
- *  of entries.  Although memory space will be grown as needed when entries
- *  are added, this can avoid the reallocate-and-copy process if the size of
- *  the ultimate contents is known in advance.
- *  <init/>
+/** <init /> <override-subclass />
+ * Initializes an empty dictionary with memory preallocated for given number
+ * of entries.  Although memory space will be grown as needed when entries
+ * are added, this can avoid the reallocate-and-copy process if the size of
+ * the ultimate contents is known in advance.<br />
+ * Calls -init (which does nothing but maintain MacOS-X compatibility),
+ * and needs to be re-implemented in subclasses in order to have all
+ * other initialisers work.
  */
 - (id) initWithCapacity: (unsigned)numItems
 {
-  [self subclassResponsibility: _cmd];
-  return 0;
+  self = [self init];
+  return self;
 }
 
 /**

Source/NSSet.m

@@ -272,14 +272,46 @@ static Class NSMutableSet_concrete_class;
 }
 
 /**
- *  Initialize to contain (unique elements of) objects.
- * <init />
+ * <p>In MacOS-X class clusters do not have designated initialisers,
+ * and there is a general rule that -init is treated as the designated
+ * initialiser of the class cluster, but that other intitialisers
+ * may not work s expected an would need to be individually overridden
+ * in any subclass.
+ * </p>
+ * <p>GNUstep tries to make it easier to subclass a class cluster,
+ * by making class clusters follow the same convention as normal
+ * classes, so the designated initialiser is the <em>richest</em>
+ * initialiser.  This means that all other initialisers call the
+ * documented designated initialiser (which calls -init only for
+ * MacOS-X compatibility), and anyone writing a subclass only needs
+ * to override that one initialiser in order to have all the other
+ * ones work.
+ * </p>
+ * <p>For MacOS-X compatibility, you may also need to override various
+ * other initialisers.  Exactly which ones, you will need to determine
+ * by trial on a MacOS-X system ... and may vary between releases of
+ * MacOS-X.  So to be safe, on MacOS-X you probably need to re-implement
+ * <em>all</em> the class cluster initialisers you might use in conjunction
+ * with your subclass.
+ * </p>
+ */
+- (id) init
+{
+  self = [super init];
+  return self;
+}
+
+/** <init /> <override-subclass />
+ * Initialize to contain (unique elements of) objects.<br />
+ * Calls -init (which does nothing but maintain MacOS-X compatibility),
+ * and needs to be re-implemented in subclasses in order to have all
+ * other initialisers work.
  */
 - (id) initWithObjects: (id*)objects
 		 count: (unsigned)count
 {
-  [self subclassResponsibility: _cmd];
-  return 0;
+  self = [self init];
+  return self;
 }
 
 /**
@@ -323,12 +355,6 @@ static Class NSMutableSet_concrete_class;
   return self;
 }
 
-/* Override superclass's designated initializer */
-- (id) init
-{
-  return [self initWithObjects: NULL count: 0];
-}
-
 /**
  * Initialises a newly allocated set by adding all the objects
  * in the supplied array to the set.
@@ -613,16 +639,20 @@ static Class NSMutableSet_concrete_class;
   return NSMutableSet_concrete_class;
 }
 
-/** <init />
+/** <init /> <override-subclass />
  * Initialises a newly allocated set to contain no objects but
  * to have space available to hold the specified number of items.<br />
  * Additions of items to a set initialised
  * with an appropriate capacity will be more efficient than addition
- * of items otherwise.
+ * of items otherwise.<br />
+ * Calls -init (which does nothing but maintain MacOS-X compatibility),
+ * and needs to be re-implemented in subclasses in order to have all
+ * other initialisers work.
  */
 - (id) initWithCapacity: (unsigned)numItems
 {
-  return [self subclassResponsibility: _cmd];
+  self = [self init];
+  return self;
 }
 
 /**

Source/NSString.m

@@ -520,7 +520,36 @@ handle_printf_atsign (FILE *stream,
   return ret;
 }
 
-// Initializing Newly Allocated Strings
+
+/**
+ * <p>In MacOS-X class clusters do not have designated initialisers,
+ * and there is a general rule that -init is treated as the designated
+ * initialiser of the class cluster, but that other intitialisers
+ * may not work s expected an would need to be individually overridden
+ * in any subclass.
+ * </p>
+ * <p>GNUstep tries to make it easier to subclass a class cluster,
+ * by making class clusters follow the same convention as normal
+ * classes, so the designated initialiser is the <em>richest</em>
+ * initialiser.  This means that all other initialisers call the
+ * documented designated initialiser (which calls -init only for
+ * MacOS-X compatibility), and anyone writing a subclass only needs
+ * to override that one initialiser in order to have all the other
+ * ones work.
+ * </p>
+ * <p>For MacOS-X compatibility, you may also need to override various
+ * other initialisers.  Exactly which ones, you will need to determine
+ * by trial on a MacOS-X system ... and may vary between releases of
+ * MacOS-X.  So to be safe, on MacOS-X you probably need to re-implement
+ * <em>all</em> the class cluster initialisers you might use in conjunction
+ * with your subclass.
+ * </p>
+ */
+- (id) init
+{
+  self = [super init];
+  return self;
+}
 
 /**
  * Initialises the receiver with a copy of the supplied length of bytes,
@@ -861,7 +890,7 @@ handle_printf_atsign (FILE *stream,
   return self;
 }
 
-/** <init />
+/** <init /> <override-subclass />
  * <p>Initialize with given unicode chars up to length, regardless of presence
  *  of null bytes.  Does not copy the string.  If flag, frees its storage when
  *  this instance is deallocated.</p>
@@ -873,7 +902,7 @@ handle_printf_atsign (FILE *stream,
 			 length: (unsigned int)length
 		   freeWhenDone: (BOOL)flag
 {
-  [self subclassResponsibility: _cmd];
+  self = [self init];
   return self;
 }
 
@@ -1492,19 +1521,6 @@ handle_printf_atsign (FILE *stream,
   return self;
 }
 
-/**
- *  Initializes as an empty string.
- */
-- (id) init
-{
-  self = [self initWithCharactersNoCopy: (unichar*)0
-				 length: 0
-			   freeWhenDone: 0];
-  return self;
-}
-
-// Getting a String's Length
-
 /**
  * Returns the number of Unicode characters in this string, including the
  * individual characters of composed character sequences,
@@ -4724,13 +4740,15 @@ handle_printf_atsign (FILE *stream,
   return self;
 }
 
-// Designated initialiser
-/** <init/>
- * Constructs an empty string with initial buffer size of capacity.
+/** <init/> <override-subclass />
+ * Constructs an empty string with initial buffer size of capacity.<br />
+ * Calls -init (which does nothing but maintain MacOS-X compatibility),
+ * and needs to be re-implemented in subclasses in order to have all
+ * other initialisers work.
  */
 - (id) initWithCapacity: (unsigned int)capacity
 {
-  [self subclassResponsibility: _cmd];
+  self = [self init];
   return self;
 }