Up

NSPropertyListSerialization class documentation

Authors

Richard Frith-Macdonald (rfm@gnu.org)

Copyright: (C) 2004 Free Software Foundation, Inc.

Software documentation for the NSPropertyListSerialization class

NSPropertyListSerialization : NSObject

Declared in:
Foundation/NSPropertyList.h
Standards:

The NSPropertyListSerialization class provides facilities for serialising and deserializing property list data in a number of formats. A property list is roughly an NSArray or NSDictionary object, with these or NSNumber , NSData , NSString , or NSDate objects as members. (See below.)

You do not work with instances of this class, instead you use a small number of class methods to serialize and deserialize property lists.


A property list may only be one of the following classes -

NSArray
An array which is either empty or contains only property list objects.
An array is delimited by round brackets and its contents are comma separated (there is no comma after the last array element). 
       ( "one", "two", "three" )
In XML format, an array is an element whose name is array and whose content is the array content. 
       <array><string>one</string><string>two</string><string>three</string></array>
NSData
An array is represented as a series of pairs of hexadecimal characters (each pair representing a byte of data) enclosed in angle brackets. Spaces are ignored). 
       < 54637374 696D67 >
In XML format, a data object is an element whose name is data and whose content is a stream of base64 encoded bytes.
NSDate
Date objects were not traditionally allowed in property lists but were added when the XML format was introduced. GNUstep provides an extension to the traditional property list format to support date objects, but older code will not read property lists containing this extension.
This format consists of an asterisk follwed by the letter 'D' then a date/time in YYYY-MM-DD HH:MM:SS +/-ZZZZ format, all enclosed within angle brackets. 
       <*D2002-03-22 11:30:00 +0100>
In XML format, a date object is an element whose name is date and whose content is a date in the above format. 
       <date>2002-03-22 11:30:00 +0100</date>
NSDictionary
A dictionary which is either empty or contains only string keys and property list objects.
A dictionary is delimited by curly brackets and its contents are semicolon terminated (there is a semicolon after each value). Each item in the dictionary is a key/value pair with an equals sign after the key and before the value. 
       {
         "key1" = "value1";
       }
In XML format, a dictionary is an element whose name is dictionary and whose content consists of pairs of strings and other property list objects. 
       <dictionary>
         <string>key1</string>
         <string>value1</string>
       </dictionary>
NSNumber
Number objects were not traditionally allowed in property lists but were added when the XML format was intoroduced. GNUstep provides an extension to the traditional property list format to support number objects, but older code will not read property lists containing this extension.
Numbers are stored in a variety of formats depending on their values.
  • boolean... either <*BY> for YES or <*BN> for NO.
    In XML format this is either <true /> or <false />
  • integer... <*INNN> where NNN is an integer.
    In XML format this is <integer>NNN<integer>
  • real... <*RNNN> where NNN is a real number.
    In XML format this is <real>NNN<real>
NSString
A string is either stored literally (if it contains no spaces or special characters), or is stored as a quoted string with special characters escaped where necessary.
Escape conventions are similar to those normally used in ObjectiveC programming, using a backslash followed by -
  • \ a backslash character
  • " a quote character
  • b a backspace character
  • n a newline character
  • r a carriage return character
  • t a tab character
  • OOO (three octal digits) an arbitrary ascii character
  • UXXXX (where X is a hexadecimal digit) a an arbitrary unicode character 
       "hello world & others"
In XML format, the string is simply stored in UTF8 format as the content of a string element, and the only character escapes required are those used by XML such as the '&lt;' markup representing a '<' character. 
       <string>hello world &amp; others</string>"

Method summary

dataFromPropertyList: format: errorDescription: 

+ (NSData*) dataFromPropertyList: (id)aPropertyList format: (NSPropertyListFormat)aFormat errorDescription: (NSString**)anErrorString;

Creates and returns a data object containing a serialized representation of plist. The argument aFormat is used to determine the way in which the data is serialised, and the anErrorString argument is a pointer in which an error message is returned on failure ( nil is returned on success).

propertyList: isValidForFormat: 

+ (BOOL) propertyList: (id)aPropertyList isValidForFormat: (NSPropertyListFormat)aFormat;

Returns a flag indicating whether it is possible to serialize aPropertyList in the format aFormat.

propertyListFromData: mutabilityOption: format: errorDescription: 

+ (id) propertyListFromData: (NSData*)data mutabilityOption: (NSPropertyListMutabilityOptions)anOption format: (NSPropertyListFormat*)aFormat errorDescription: (NSString**)anErrorString;

Deserialises dataItem and returns the resulting property list (or nil if the data does not contain a property list serialised in a supported format).
The argument anOption is used to control whether the objects making up the deserialized property list are mutable or not.
The argument aFormat is either null or a pointer to a location in which the format of the serialized property list will be returned.
Either nil or an error message will be returned in anErrorString.


Up