iOS Developer Library

Developer

Foundation Framework Reference NSJSONSerialization Class Reference

Options
Deployment Target:

On This Page
Language:

NSJSONSerialization

You use the NSJSONSerialization class to convert JSON to Foundation objects and convert Foundation objects to JSON. More...

Inheritance


Conforms To


Import Statement


import Foundation @import Foundation;

Availability


Available in iOS 5.0 and later.
  • Returns a Foundation object from given JSON data.

    Declaration

    Swift

    class func JSONObjectWithData(_ data: NSData, options opt: NSJSONReadingOptions, error error: NSErrorPointer) -> AnyObject?

    Objective-C

    + (id)JSONObjectWithData:(NSData *)data options:(NSJSONReadingOptions)opt error:(NSError **)error

    Parameters

    data

    A data object containing JSON data.

    opt

    Options for reading the JSON data and creating the Foundation objects.

    For possible values, see NSJSONReadingOptions.

    error

    If an error occurs, upon return contains an NSError object that describes the problem.

    Return Value

    A Foundation object from the JSON data in data, or nil if an error occurs.

    Discussion

    The data must be in one of the 5 supported encodings listed in the JSON specification: UTF-8, UTF-16LE, UTF-16BE, UTF-32LE, UTF-32BE. The data may or may not have a BOM. The most efficient encoding to use for parsing is UTF-8, so if you have a choice in encoding the data passed to this method, use UTF-8.

    Import Statement

    import Foundation

    Availability

    Available in iOS 5.0 and later.

  • Returns a Foundation object from JSON data in a given stream.

    Declaration

    Swift

    class func JSONObjectWithStream(_ stream: NSInputStream, options opt: NSJSONReadingOptions, error error: NSErrorPointer) -> AnyObject?

    Objective-C

    + (id)JSONObjectWithStream:(NSInputStream *)stream options:(NSJSONReadingOptions)opt error:(NSError **)error

    Parameters

    stream

    A stream from which to read JSON data.

    The stream should be opened and configured.

    opt

    Options for reading the JSON data and creating the Foundation objects.

    For possible values, see NSJSONReadingOptions.

    error

    If an error occurs, upon return contains an NSError object that describes the problem.

    Return Value

    A Foundation object from the JSON data in stream.

    Discussion

    The data in the stream must be in one of the 5 supported encodings listed in the JSON specification: UTF-8, UTF-16LE, UTF-16BE, UTF-32LE, UTF-32BE. The data may or may not have a BOM. The most efficient encoding to use for parsing is UTF-8, so if you have a choice in encoding the data passed to this method, use UTF-8.

    Availability

    Available in iOS 5.0 and later.

    Import Statement

    import Foundation

  • Returns JSON data from a Foundation object.

    Declaration

    Swift

    class func dataWithJSONObject(_ obj: AnyObject, options opt: NSJSONWritingOptions, error error: NSErrorPointer) -> NSData?

    Objective-C

    + (NSData *)dataWithJSONObject:(id)obj options:(NSJSONWritingOptions)opt error:(NSError **)error

    Parameters

    obj

    The object from which to generate JSON data. Must not be nil.

    opt

    Options for creating the JSON data.

    See NSJSONWritingOptions for possible values. Pass 0 to specify no options.

    error

    If an internal error occurs, upon return contains an NSError object that describes the problem.

    Return Value

    JSON data for obj, or nil if an internal error occurs. The resulting data is a encoded in UTF-8.

    Discussion

    If obj will not produce valid JSON, an exception is thrown. This exception is thrown prior to parsing and represents a programming error, not an internal error. You should check whether the input will produce valid JSON before calling this method by using isValidJSONObject:.

    Setting the NSJSONWritingPrettyPrinted option will generate JSON with whitespace designed to make the output more readable. If that option is not set, the most compact possible JSON will be generated.

    Import Statement

    import Foundation

    Availability

    Available in iOS 5.0 and later.

  • Writes a given JSON object to a stream.

    Declaration

    Swift

    class func writeJSONObject(_ obj: AnyObject, toStream stream: NSOutputStream, options opt: NSJSONWritingOptions, error error: NSErrorPointer) -> Int

    Objective-C

    + (NSInteger)writeJSONObject:(id)obj toStream:(NSOutputStream *)stream options:(NSJSONWritingOptions)opt error:(NSError **)error

    Parameters

    obj

    The object to write to stream.

    stream

    The stream to which to write.

    The stream should be opened and configured.

    opt

    Options for writing the JSON data.

    See NSJSONWritingOptions for possible values. Pass 0 to specify no options.

    error

    If an error occurs, upon return contains an NSError object that describes the problem.

    Return Value

    The number of bytes written to the stream, or 0 if an error occurs.

    Discussion

    Import Statement

    import Foundation

    Availability

    Available in iOS 5.0 and later.

  • Returns a Boolean value that indicates whether a given object can be converted to JSON data.

    Declaration

    Swift

    class func isValidJSONObject(_ obj: AnyObject) -> Bool

    Objective-C

    + (BOOL)isValidJSONObject:(id)obj

    Parameters

    obj

    The object to test.

    Return Value

    YEStrue if obj can be converted to JSON data, otherwise NOfalse.

    Discussion

    Import Statement

    import Foundation

    Availability

    Available in iOS 5.0 and later.

  • Options used when creating Foundation objects from JSON data—see JSONObjectWithData:options:error: and JSONObjectWithStream:options:error:.

    Declaration

    Swift

    struct NSJSONReadingOptions : RawOptionSetType { init(_ rawValue: UInt) init(rawValue rawValue: UInt) static var MutableContainers: NSJSONReadingOptions { get } static var MutableLeaves: NSJSONReadingOptions { get } static var AllowFragments: NSJSONReadingOptions { get } }

    Objective-C

    enum { NSJSONReadingMutableContainers = (1UL << 0), NSJSONReadingMutableLeaves = (1UL << 1), NSJSONReadingAllowFragments = (1UL << 2) }; typedef NSUInteger NSJSONReadingOptions;

    Constants

    • MutableContainers

      NSJSONReadingMutableContainers

      Specifies that arrays and dictionaries are created as mutable objects.

      Available in iOS 5.0 and later.

    • MutableLeaves

      NSJSONReadingMutableLeaves

      Specifies that leaf strings in the JSON object graph are created as instances of NSMutableString.

      Available in iOS 5.0 and later.

    • AllowFragments

      NSJSONReadingAllowFragments

      Specifies that the parser should allow top-level objects that are not an instance of NSArray or NSDictionary.

      Available in iOS 5.0 and later.

    Import Statement

    import Foundation

    Availability

    Available in iOS 5.0 and later.

  • Options for writing JSON data.

    Declaration

    Swift

    struct NSJSONWritingOptions : RawOptionSetType { init(_ rawValue: UInt) init(rawValue rawValue: UInt) static var PrettyPrinted: NSJSONWritingOptions { get } }

    Objective-C

    enum { NSJSONWritingPrettyPrinted = (1UL << 0) }; typedef NSUInteger NSJSONWritingOptions;

    Constants

    • PrettyPrinted

      NSJSONWritingPrettyPrinted

      Specifies that the JSON data should be generated with whitespace designed to make the output more readable. If this option is not set, the most compact possible JSON representation is generated.

      Available in iOS 5.0 and later.

    Import Statement

    import Foundation

    Availability

    Available in iOS 5.0 and later.