Up
Authors
- Richard Frith-Macdonald (
rfm@gnu.org
)
-
Copyright: (C) 2004 Free Software Foundation, Inc.
- Declared in:
- Foundation/NSPropertyList.h
Availability: MacOS-X 10.0.0
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 followed 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 introduced. 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 '<' markup representing a '<' character.
<string>hello world & others</string>"
Method summary
+ (
NSData*)
dataFromPropertyList: (id)aPropertyList
format: (
NSPropertyListFormat)aFormat
errorDescription: (
NSString**)anErrorString;
Availability: MacOS-X 10.0.0
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).
+ (BOOL)
propertyList: (id)aPropertyList
isValidForFormat: (
NSPropertyListFormat)aFormat;
Availability: MacOS-X 10.0.0
Returns a flag indicating whether it is possible to serialize aPropertyList in the format aFormat.
+ (id)
propertyListFromData: (
NSData*)data
mutabilityOption: (
NSPropertyListMutabilityOptions)anOption
format: (
NSPropertyListFormat*)aFormat
errorDescription: (
NSString**)anErrorString;
Availability: MacOS-X 10.0.0
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