Complete NSValueTransformer implementation and document it.

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

ChangeLog

@@ -1,3 +1,11 @@
+2006-12-26  Richard Frith-Macdonald <rfm@gnu.org>
+
+	* Headers/Foundation/NSValueTransformer.h:
+	* Source/NSValueTransformer.h:
+	Complete implementation.
+	Make thread-safe.
+	Document.
+
 2006-12-25 Dr. H. Nikolaus Schaller
 
 	* Headers/Foundation/NSValueTransformer.h:

Headers/Foundation/NSValueTransformer.h

@@ -3,6 +3,7 @@
 
    Written Dr. H. Nikolaus Schaller
    Created on Mon Mar 21 2005.
+   Updatesd and documented by Richard Frith-Macdonald
    
    This file is part of the GNUstep Base Library.
 
@@ -34,41 +35,81 @@
 extern "C" {
 #endif
 
-GS_EXPORT NSString* const NSNegateBooleanTransformerName;
-GS_EXPORT NSString* const NSIsNilTransformerName;
-GS_EXPORT NSString* const NSIsNotNilTransformerName; 
-GS_EXPORT NSString* const NSUnarchiveFromDataTransformerName;
-
+@class NSArray;
 @class NSString;
 
+/** This transformer converts a YES to a NO and a NO to a YES.
+ */
+GS_EXPORT NSString* const NSNegateBooleanTransformerName;
+
+/** This transformer converts a nil value to a YES.<br />
+ * Not reversible.
+ */
+GS_EXPORT NSString* const NSIsNilTransformerName;
+
+/** This transformer converts a non-nil value to a YES.<br />
+ * Not reversible.
+ */
+GS_EXPORT NSString* const NSIsNotNilTransformerName; 
+
+/** This transformer converts an [NSData] instance to the object
+ * archived in it, or archives an object inot an [NSData].
+ */
+GS_EXPORT NSString* const NSUnarchiveFromDataTransformerName;
+
+/** Instances of the NSValueTransformer class are used to convert
+ * values from one representation to another.  The base class is
+ * abstract and its methods must be overridden by subclasses to do
+ * the actual work.
+ */
 @interface NSValueTransformer : NSObject
 
+/** <override-subclass />
+ * Returns a flag indicating whether the transformer permits reverse
+ * transformations.
+ */
 + (BOOL) allowsReverseTransformation;
+
+/**
+ * Registers transformer to handle transformations with the specified
+ * name.
+ */
 + (void) setValueTransformer: (NSValueTransformer *)transformer
 		     forName: (NSString *)name;
+
+/** <override-subclass />
+ * Returns the class of the value produced by this transformer.
+ */
 + (Class) transformedValueClass;
+
+/**
+ * Returns the transformer registered for the specified name, or nil
+ * if no transformer is registered for name.
+ */
 + (NSValueTransformer *) valueTransformerForName: (NSString *)name;
+
+/**
+ * Returns an array listing the names of all registered value transformers.
+ */
 + (NSArray *) valueTransformerNames;
 
+/**
+ * Performs a reverse transformation on the specified value and returns the
+ * resulting object.<br />
+ * The default implementation raises an exception if
+ * +allowsReverseTransformation returns NO, otherwise it calls
+ * -transformedValue: and returns the result.
+ */
 - (id) reverseTransformedValue: (id)value;
+
+/** <override-subclass/>
+ * Subclasses should override this method to perform the actual transformation
+ * (and reverse transformation if applicable) and return the result.
+ */
 - (id) transformedValue: (id)value;
 
 @end
 
-// builtin transformers
-
-@interface NSNegateBooleanTransformer : NSValueTransformer
-@end
-
-@interface NSIsNilTransformer : NSValueTransformer
-@end
-
-@interface NSIsNotNilTransformer : NSValueTransformer
-@end
-
-@interface NSUnarchiveFromDataTransformer : NSValueTransformer
-@end
-
 #if	defined(__cplusplus)
 }
 #endif

Source/NSValueTransformer.m

@@ -3,6 +3,7 @@
 
    Written Dr. H. Nikolaus Schaller
    Created on Mon Mar 21 2005.
+   Updated (thread safety) by Richard Frith-Macdonald
    
    This file is part of the GNUstep Base Library.
 
@@ -23,6 +24,20 @@
    */ 
 
 #import "Foundation/Foundation.h"
+#import "GNUstepBase/GSLock.h"
+
+@interface NSNegateBooleanTransformer : NSValueTransformer
+@end
+
+@interface NSIsNilTransformer : NSValueTransformer
+@end
+
+@interface NSIsNotNilTransformer : NSValueTransformer
+@end
+
+@interface NSUnarchiveFromDataTransformer : NSValueTransformer
+@end
+
 
 @implementation NSValueTransformer
 
@@ -37,33 +52,68 @@ NSString * const NSUnarchiveFromDataTransformerName
 
 // non-abstract methods
 
-static NSMutableDictionary *names;
+static NSMutableDictionary *registry = nil;
+static GSLazyLock *lock = nil;
+
++ (void) initialize
+{
+  if (lock == nil)
+    {
+      NSValueTransformer	*t;
+
+      lock = [GSLazyLock new];
+      registry = [[NSMutableDictionary alloc] init];
+
+      t = [NSNegateBooleanTransformer new];
+      [self setValueTransformer: t
+		        forName: NSNegateBooleanTransformerName];
+      RELEASE(t);
+
+      t = [NSIsNilTransformer new];
+      [self setValueTransformer: t
+		        forName: NSIsNilTransformerName];
+      RELEASE(t);
+
+      t = [NSIsNotNilTransformer new];
+      [self setValueTransformer: t
+		        forName: NSIsNotNilTransformerName];
+      RELEASE(t);
+
+      t = [NSUnarchiveFromDataTransformer new];
+      [self setValueTransformer: t
+		        forName: NSUnarchiveFromDataTransformerName];
+      RELEASE(t);
+    }
+}
 
 + (void) setValueTransformer: (NSValueTransformer *)transformer
 		     forName: (NSString *)name
 {
-  if (names == nil)
-    {
-      [self valueTransformerNames];	// allocate if needed
-    }
-  [names setObject: transformer forKey: name];
+  [lock lock];
+  [registry setObject: transformer forKey: name];
+  [lock unlock];
 }
 
 + (NSValueTransformer *) valueTransformerForName: (NSString *)name
 {
-  return [names objectForKey: name];
+  NSValueTransformer	*transformer;
+
+  [lock lock];
+  transformer = [registry objectForKey: name];
+  RETAIN(transformer);
+  [lock unlock];
+  return AUTORELEASE(transformer);
 }
 
 + (NSArray *) valueTransformerNames;
 {
-  if (names == nil)
-    {
-      names = [[NSMutableDictionary alloc] init];
-    }
-  return [names allKeys];
-}
+  NSArray	*names;
 
-// abstract methods (must be implemented in subclasses)
+  [lock lock];
+  names = [registry allKeys];
+  [lock unlock];
+  return names;
+}
 
 + (BOOL) allowsReverseTransformation
 {
@@ -78,7 +128,13 @@ static NSMutableDictionary *names;
 
 - (id) reverseTransformedValue: (id)value
 {
-  return [self subclassResponsibility: _cmd];
+  if ([[self class] allowsReverseTransformation] == NO)
+    {
+      [NSException raise: NSGenericException
+      		  format: @"[%@] is not reversible",
+	NSStringFromClass([self class])];
+    }
+  return [self transformedValue: value];
 }
 
 - (id) transformedValue: (id)value
@@ -96,17 +152,20 @@ static NSMutableDictionary *names;
 {
   return YES;
 }
+
 + (Class) transformedValueClass
 {
   return [NSNumber class];
 }
+
 - (id) reverseTransformedValue: (id) value
 {
-  return [NSNumber numberWithBool: ![value boolValue]];
+  return [NSNumber numberWithBool: [value boolValue] ? NO : YES];
 }
+
 - (id) transformedValue: (id)value
 {
-  return [NSNumber numberWithBool: ![value boolValue]];
+  return [NSNumber numberWithBool: [value boolValue] ? NO : YES];
 }
 
 @end
@@ -117,17 +176,15 @@ static NSMutableDictionary *names;
 {
   return NO;
 }
+
 + (Class) transformedValueClass
 {
   return [NSNumber class];
 }
-- (id) reverseTransformedValue: (id)value
-{
-  return [self notImplemented: _cmd];
-}
+
 - (id) transformedValue: (id)value
 {
-  return [NSNumber numberWithBool: (value == nil)];
+  return [NSNumber numberWithBool: (value == nil) ? YES : NO];
 }
 
 @end
@@ -138,17 +195,15 @@ static NSMutableDictionary *names;
 {
   return NO;
 }
+
 + (Class) transformedValueClass
 {
   return [NSNumber class];
 }
-- (id) reverseTransformedValue: (id)value
-{
-  return [self notImplemented: _cmd];
-}
+
 - (id) transformedValue: (id)value
 {
-  return [NSNumber numberWithBool: (value != nil)];
+  return [NSNumber numberWithBool: (value != nil) ? YES : NO];
 }
 
 @end
@@ -159,17 +214,22 @@ static NSMutableDictionary *names;
 {
   return YES;
 }
+
 + (Class) transformedValueClass
 {
   return [NSData class];
 }
+
 - (id) reverseTransformedValue: (id)value
 {
-  return [self notImplemented: _cmd];
+// FIXME ... should we use a keyed archive?
+  return [NSKeyedArchiver archivedDataWithRootObject: value];
 }
+
 - (id) transformedValue: (id)value
 {
-  return [self notImplemented: _cmd];
+// FIXME ... should we use a keyed archive?
+  return [NSKeyedUnarchiver unarchiveObjectWithData: value];
 }
 
 @end