From 90a810065ddff8477d1a1e3fb171abdfa524ffda Mon Sep 17 00:00:00 2001 From: Richard Frith-Macdonald Date: Tue, 7 Sep 2004 05:43:20 +0000 Subject: [PATCH] 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 | 11 ++++++ Headers/Foundation/NSArray.h | 1 + Headers/Foundation/NSDictionary.h | 1 + Headers/Foundation/NSSet.h | 1 + Headers/Foundation/NSString.h | 1 + Source/NSArray.m | 54 ++++++++++++++++++++------ Source/NSDictionary.m | 64 ++++++++++++++++++++++--------- Source/NSSet.m | 56 ++++++++++++++++++++------- Source/NSString.m | 58 ++++++++++++++++++---------- 9 files changed, 185 insertions(+), 62 deletions(-) diff --git a/ChangeLog b/ChangeLog index a12e721d0..44f2153a5 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,14 @@ +2004-09-07 Richard Frith-Macdonald + + * 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 * Version 1.10.0 diff --git a/Headers/Foundation/NSArray.h b/Headers/Foundation/NSArray.h index f0e95c2bc..e4d6b2409 100644 --- a/Headers/Foundation/NSArray.h +++ b/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; diff --git a/Headers/Foundation/NSDictionary.h b/Headers/Foundation/NSDictionary.h index fc7a35a46..8da531278 100644 --- a/Headers/Foundation/NSDictionary.h +++ b/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; diff --git a/Headers/Foundation/NSSet.h b/Headers/Foundation/NSSet.h index 82862dc9e..27afc2f26 100644 --- a/Headers/Foundation/NSSet.h +++ b/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 diff --git a/Headers/Foundation/NSString.h b/Headers/Foundation/NSString.h index 31e88c43e..9076cae97 100644 --- a/Headers/Foundation/NSString.h +++ b/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 diff --git a/Source/NSArray.m b/Source/NSArray.m index 1b709bfb0..3f387f4e3 100644 --- a/Source/NSArray.m +++ b/Source/NSArray.m @@ -517,9 +517,34 @@ static SEL rlSel; return NSNotFound; } +/** + *

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. + *

+ *

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 richest + * 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. + *

+ *

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 + * all the class cluster initialisers you might use in conjunction + * with your subclass. + *

+ */ - (id) init { - return [self initWithObjects: (id*)0 count: 0]; + self = [super init]; + return self; } /** @@ -742,15 +767,17 @@ static SEL rlSel; return self; } -/** - * Initialize the array with count objects.
+/** + * This should initialize the array with count (may be zero) objects.
* Retains each object placed in the array.
- * 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; } -/** +/** * 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.
+ * 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; } /** @@ -1386,7 +1416,9 @@ compare(id elem1, id elem2, void* context) initWithCapacity: numItems]); } -/** 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]; diff --git a/Source/NSDictionary.m b/Source/NSDictionary.m index 51e0b160a..135b651f5 100644 --- a/Source/NSDictionary.m +++ b/Source/NSDictionary.m @@ -119,18 +119,50 @@ static SEL appSel; } /** + *

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. + *

+ *

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 richest + * 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. + *

+ *

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 + * all the class cluster initialisers you might use in conjunction + * with your subclass. + *

+ */ +- (id) init +{ + self = [super init]; + return self; +} + +/** * 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. - * + * element of the keys array.
+ * 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. - * +/** + * 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.
+ * 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; } /** diff --git a/Source/NSSet.m b/Source/NSSet.m index 4afd774a9..e655ffca8 100644 --- a/Source/NSSet.m +++ b/Source/NSSet.m @@ -272,14 +272,46 @@ static Class NSMutableSet_concrete_class; } /** - * Initialize to contain (unique elements of) objects. - * + *

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. + *

+ *

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 richest + * 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. + *

+ *

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 + * all the class cluster initialisers you might use in conjunction + * with your subclass. + *

+ */ +- (id) init +{ + self = [super init]; + return self; +} + +/** + * Initialize to contain (unique elements of) objects.
+ * 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; } -/** +/** * Initialises a newly allocated set to contain no objects but * to have space available to hold the specified number of items.
* Additions of items to a set initialised * with an appropriate capacity will be more efficient than addition - * of items otherwise. + * of items otherwise.
+ * 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; } /** diff --git a/Source/NSString.m b/Source/NSString.m index d448b5e17..641f341d1 100644 --- a/Source/NSString.m +++ b/Source/NSString.m @@ -520,7 +520,36 @@ handle_printf_atsign (FILE *stream, return ret; } -// Initializing Newly Allocated Strings + +/** + *

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. + *

+ *

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 richest + * 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. + *

+ *

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 + * all the class cluster initialisers you might use in conjunction + * with your subclass. + *

+ */ +- (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; } -/** +/** *

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.

@@ -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 -/** - * Constructs an empty string with initial buffer size of capacity. +/** + * Constructs an empty string with initial buffer size of capacity.
+ * 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; }