Add excahnge method

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

ChangeLog

@@ -5,7 +5,8 @@
 	* Source/NSUserDefaults.m: Use distributed lock to ensure that there
 	is no possible window when the defaults file is invalid ... not all
 	systems guarantee that the rename() system call is atomic.
-	* Source/NSArray.m: New MacOS-X method ([-initWithArray:copyItems:])
+	* Source/NSArray.m: New MacOS-X methods ([-initWithArray:copyItems:])
+	([-exchangeObjectAtIndex:withObjectAtIndex:])
  
 2002-08-25  Richard Frith-Macdonald <rfm@gnu.org>
 

Headers/gnustep/base/NSArray.h

@@ -105,6 +105,10 @@
 
 - (void) addObject: (id)anObject;				// Primitive
 - (void) addObjectsFromArray: (NSArray*)otherArray;
+#ifndef	STRICT_OPENSTEP
+- (void) exchangeObjectAtIndex: (unsigned int)i1
+	     withObjectAtIndex: (unsigned int)i2;
+#endif
 - (id) initWithCapacity: (unsigned)numItems;			// Primitive
 - (void) insertObject: (id)anObject atIndex: (unsigned)index;	// Primitive
 - (void) removeObjectAtIndex: (unsigned)index;			// Primitive

Source/GSArray.m

@@ -331,6 +331,56 @@ static SEL	eqSel;
     }
 }
 
+- (void) addObject: (id)anObject
+{
+  if (anObject == nil)
+    {
+      [NSException raise: NSInvalidArgumentException
+		  format: @"Tried to add nil to array"];
+    }
+  if (_count >= _capacity)
+    {
+      id	*ptr;
+      size_t	size = (_capacity + _grow_factor)*sizeof(id);
+
+      ptr = NSZoneRealloc([self zone], _contents_array, size);
+      if (ptr == 0)
+	{
+	  [NSException raise: NSMallocException
+		      format: @"Unable to grow"];
+	}
+      _contents_array = ptr;
+      _capacity += _grow_factor;
+      _grow_factor = _capacity/2;
+    }
+  _contents_array[_count] = RETAIN(anObject);
+  _count++;	/* Do this AFTER we have retained the object.	*/
+}
+
+- (void) exchangeObjectAtIndex: (unsigned int)i1 
+             withObjectAtIndex: (unsigned int)i2
+{
+  if (i1 >= _count)
+    {
+      [NSException raise: NSRangeException format:
+	@"in %@:, index %d is out of range",
+	NSStringFromSelector(_cmd), i1];
+    }
+  if (i2 >= _count)
+    {
+      [NSException raise: NSRangeException format:
+	@"in %@:, index %d is out of range",
+	NSStringFromSelector(_cmd), i1];
+    }
+  if (i1 != i2)
+    {
+      id	tmp = _contents_array[i1];
+
+      _contents_array[i1] = _contents_array[i2];
+      _contents_array[i2] = tmp;
+    }
+}
+
 - (id) initWithCapacity: (unsigned)cap
 {
   if (cap == 0)
@@ -429,32 +479,6 @@ static SEL	eqSel;
   _contents_array[index] = RETAIN(anObject);
 }
 
-- (void) addObject: (id)anObject
-{
-  if (anObject == nil)
-    {
-      [NSException raise: NSInvalidArgumentException
-		  format: @"Tried to add nil to array"];
-    }
-  if (_count >= _capacity)
-    {
-      id	*ptr;
-      size_t	size = (_capacity + _grow_factor)*sizeof(id);
-
-      ptr = NSZoneRealloc([self zone], _contents_array, size);
-      if (ptr == 0)
-	{
-	  [NSException raise: NSMallocException
-		      format: @"Unable to grow"];
-	}
-      _contents_array = ptr;
-      _capacity += _grow_factor;
-      _grow_factor = _capacity/2;
-    }
-  _contents_array[_count] = RETAIN(anObject);
-  _count++;	/* Do this AFTER we have retained the object.	*/
-}
-
 - (void) removeLastObject
 {
   if (_count == 0)

Source/NSArray.m

@@ -1172,23 +1172,53 @@ static NSString	*indentStrings[] = {
   return newArray;
 }
 
-/* This is the desgnated initializer for NSMutableArray */
+/** <init />
+ * Initialise the array with the specified capacity ... this
+ * should ensure that the array can have numItems added efficiently.
+ */
 - (id) initWithCapacity: (unsigned)numItems
 {
   [self subclassResponsibility: _cmd];
   return nil;
 }
 
-- (void) addObject: anObject
+/** <override-subclass />
+ * Adds an object at the end of the array.
+ */
+- (void) addObject: (id)anObject
 {
   [self subclassResponsibility: _cmd];
 }
 
-- (void) replaceObjectAtIndex: (unsigned)index withObject: anObject
+/**
+ * Swaps the positions of two objects in the array.  Raises an exception
+ * if either array index is out of bounds.
+ */
+- (void) exchangeObjectAtIndex: (unsigned int)i1 
+             withObjectAtIndex: (unsigned int)i2
+{
+  id	tmp = [self objectAtIndex: i1];
+
+  RETAIN(tmp);
+  [self replaceObjectAtIndex: i1 withObject: [self objectAtIndex: i2]];
+  [self replaceObjectAtIndex: i2 withObject: tmp];
+  RELEASE(tmp);
+}
+
+/** <override-subclass />
+ * Places an object into the receiver at the specified location.<br />
+ * Raises an exception if given an array index which is too large.<br />
+ * The object is retained by the array.
+ */
+- (void) replaceObjectAtIndex: (unsigned)index withObject: (id)anObject
 {
   [self subclassResponsibility: _cmd];
 }
 
+/**
+ * Replaces objects in the receiver with those from anArray.<br />
+ * Raises an exception if given a range extending beyond the array.<br />
+ */
 - (void) replaceObjectsInRange: (NSRange)aRange
 	  withObjectsFromArray: (NSArray*)anArray
 {
@@ -1203,6 +1233,10 @@ static NSString	*indentStrings[] = {
     [self insertObject: o atIndex: aRange.location];
 }
 
+/**
+ * Replaces objects in the receiver with some of those from anArray.<br />
+ * Raises an exception if given a range extending beyond the array.<br />
+ */
 - (void) replaceObjectsInRange: (NSRange)aRange
 	  withObjectsFromArray: (NSArray*)anArray
 			 range: (NSRange)anotherRange
@@ -1211,11 +1245,20 @@ static NSString	*indentStrings[] = {
 	 withObjectsFromArray: [anArray subarrayWithRange: anotherRange]];
 }
 
+/** <override-subclass />
+ * Inserts an object into the receiver at the specified location.<br />
+ * Raises an exception if given an array index which is too large.<br />
+ * The object is retained by the array.
+ */
 - (void) insertObject: anObject atIndex: (unsigned)index
 {
   [self subclassResponsibility: _cmd];
 }
 
+/** <override-subclass />
+ * Removes an object from the receiver at the specified location.<br />
+ * Raises an exception if given an array index which is too large.<br />
+ */
 - (void) removeObjectAtIndex: (unsigned)index
 {
   [self subclassResponsibility: _cmd];
@@ -1227,7 +1270,7 @@ static NSString	*indentStrings[] = {
     initWithCapacity: numItems]);
 }
 
-/* Override our superclass's designated initializer to go our's */
+/** <init /> Override our superclass's designated initializer to go our's */
 - (id) initWithObjects: (id*)objects count: (unsigned)count
 {
   self = [self initWithCapacity: count];