Mac Developer Library

Developer

Foundation Framework Reference NSValueTransformer Class Reference

Options
Deployment Target:

On This Page
Language:

NSValueTransformer

NSValueTransformer is an abstract class that is used by the Cocoa Bindings technology to transform values from one representation to another.

An application creates a subclass of NSValueTransformer, overriding the necessary methods to provide the required custom transformation.

Example

A relatively trivial value transformer takes an object of type id and returns a string based on the object’€™s class type. This transformer is not reversible as it’s probably unreasonable to transform a class name into an object. The value transformer class you write to accomplish this simple task could look like:

  • @interface ClassNameTransformer: NSValueTransformer {}
  • @end
  • @implementation ClassNameTransformer
  • + (Class)transformedValueClass { return [NSString class]; }
  • + (BOOL)allowsReverseTransformation { return NO; }
  • - (id)transformedValue:(id)value {
  • return (value == nil) ? nil : NSStringFromClass([value class]);
  • }
  • @end

Inheritance


Conforms To


Import Statement


Swift

import Foundation

Objective-C

@import Foundation;

Availability


Available in OS X v10.3 and later.
  • Registers the provided value transformer with a given identifier.

    Declaration

    Swift

    class func setValueTransformer(_ transformer: NSValueTransformer, forName name: String)

    Objective-C

    + (void)setValueTransformer:(NSValueTransformer *)transformer forName:(NSString *)name

    Parameters

    transformer

    The transformer to register.

    name

    The name for transformer.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.3 and later.

  • Returns the value transformer identified by a given identifier.

    Declaration

    Swift

    init?(forName name: String) -> NSValueTransformer

    Objective-C

    + (NSValueTransformer *)valueTransformerForName:(NSString *)name

    Parameters

    name

    The transformer identifier.

    Return Value

    The value transformer identified by name in the shared registry, or nil if not found.

    Discussion

    If valueTransformerForName: does not find a registered transformer instance for name, it will attempt to find a class with the specified name. If a corresponding class is found an instance will be created and initialized using its init: method and then automatically registered with name.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.3 and later.

  • Returns an array of all the registered value transformers.

    Declaration

    Swift

    class func valueTransformerNames() -> [AnyObject]

    Objective-C

    + (NSArray *)valueTransformerNames

    Return Value

    An array of all the registered value transformers.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.3 and later.

  • Returns a Boolean value that indicates whether the receiver can reverse a transformation.

    Declaration

    Swift

    class func allowsReverseTransformation() -> Bool

    Objective-C

    + (BOOL)allowsReverseTransformation

    Return Value

    YEStrue if the receiver supports reverse value transformations, otherwise NOfalse.

    The default is YEStrue.

    Discussion

    Subclasses should override this method to return NOfalse if they do not support reverse value transformations.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.3 and later.

  • Returns the class of the value returned by the receiver for a forward transformation.

    Declaration

    Swift

    class func transformedValueClass() -> AnyClass

    Objective-C

    + (Class)transformedValueClass

    Return Value

    The class of the value returned by the receiver for a forward transformation.

    Discussion

    A subclass should override this method to return the appropriate class.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.3 and later.

  • Returns the result of transforming a given value.

    Declaration

    Swift

    func transformedValue(_ value: AnyObject?) -> AnyObject?

    Objective-C

    - (id)transformedValue:(id)value

    Parameters

    value

    The value to transform.

    Return Value

    The result of transforming value.

    The default implementation simply returns value.

    Discussion

    A subclass should override this method to transform and return an object based on value.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.3 and later.

  • Returns the result of the reverse transformation of a given value.

    Declaration

    Swift

    func reverseTransformedValue(_ value: AnyObject?) -> AnyObject?

    Objective-C

    - (id)reverseTransformedValue:(id)value

    Parameters

    value

    The value to reverse transform.

    Return Value

    The reverse transformation of value.

    Discussion

    The default implementation raises an exception if allowsReverseTransformation returns NOfalse; otherwise it will invoke transformedValue: with value.

    A subclass should override this method if they require a reverse transformation that is not the same as simply reapplying the original transform (as would be the case with negation, for example). For example, if a value transformer converts a value in Fahrenheit to Celsius, this method would converts a value from Celsius to Fahrenheit.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.3 and later.

  • The following named value transformers are defined by NSValueTransformer:

    Declaration

    Swift

    let NSNegateBooleanTransformerName: NSString! let NSIsNilTransformerName: NSString! let NSIsNotNilTransformerName: NSString! let NSUnarchiveFromDataTransformerName: NSString! let NSKeyedUnarchiveFromDataTransformerName: NSString!

    Objective-C

    NSString * const NSNegateBooleanTransformerName; NSString * const NSIsNilTransformerName ; NSString * const NSIsNotNilTransformerName ; NSString * const NSUnarchiveFromDataTransformerName ; NSString * const NSKeyedUnarchiveFromDataTransformerName ;

    Constants

    • NSNegateBooleanTransformerName

      NSNegateBooleanTransformerName

      This value transformer negates a boolean value, transforming YEStrue to NOfalse and NOfalse to YEStrue.

      This transformer is reversible.

      Available in OS X v10.3 and later.

    • NSIsNilTransformerName

      NSIsNilTransformerName

      This value transformer returns YEStrue if the value is nil.

      This transformer is not reversible.

      Available in OS X v10.3 and later.

    • NSIsNotNilTransformerName

      NSIsNotNilTransformerName

      This value transformer returns YEStrue if the value is non-nil.

      This transformer is not reversible.

      Available in OS X v10.3 and later.

    • NSUnarchiveFromDataTransformerName

      NSUnarchiveFromDataTransformerName

      This value transformer returns an object created by attempting to unarchive the data in the NSData object passed as the value.

      The reverse transformation returns an NSData instance created by archiving the value. The archived object must implement the NSCoding protocol using sequential archiving in order to be unarchived and archived with this transformer.

      Available in OS X v10.3 and later.

    • NSKeyedUnarchiveFromDataTransformerName

      NSKeyedUnarchiveFromDataTransformerName

      This value transformer returns an object created by attempting to unarchive the data in the NSData object passed as the value. The archived object must be created using keyed archiving in order to be unarchived and archived with this transformer.

      The reverse transformation returns an NSData instance created by archiving the value using keyed archiving. The archived object must implement the NSCoding protocol using keyed archiving in order to be unarchived and archived with this transformer.

      Available in OS X v10.5 and later.