Map

public class Map

A wrapper around a JSON object that conveniently returns parsed objects or adds complex objects into the JSON object.

Basic example of returning objects:

let jsonString = // Source of JSON string
let map = Map(jsonString: jsonString, encoding: .utf8)

let string: String = try map.value("some_key")

Basic example of adding objects:

let map = Map()
map.add("some string", for: "some_key")
let jsonString = map.jsonString(encoding: .utf8)

  • Initialize this map from a JSON dictionary. You should only pass MapPrimitive (JSON) values in this dictionary.

    Declaration

    Swift

    public init(json: [String: Any?] = [:])

  • Initialize this Map from a MapEncodable object using its fill method.

    Declaration

    Swift

    public convenience init(_ mapEncodable: MapEncodable) throws

  • Initialize this object from a JSON String.

    Throws

    Throws an error if the JSON string cannot be deserialized.

    Declaration

    Swift

    public convenience init(jsonString: String, encoding: String.Encoding = .utf8) throws

    Parameters

    jsonString

    The JSON String that will be deserialized.
    encoding

    The encoding used on the string.

  • Initialize this object from a JSON String.

    Throws

    Throws an error if the JSON string cannot be deserialized.

    Declaration

    Swift

    public convenience init(jsonData: Data, encoding: String.Encoding = .utf8) throws

    Parameters

    jsonString

    The JSON String that will be deserialized.
    encoding

    The encoding used on the string.

  • Create a Map Array from a JSON String

    Throws

    Throws an error if the JSON string cannot be deserialized.

    Declaration

    Swift

    public static func parseArray(jsonString: String, encoding: String.Encoding = .utf8) throws -> [Map]

    Parameters

    jsonString

    The JSON String that will be deserialized
    encoding

    The encoding used on the string

  • Create a Map Array from a JSON Data

    Throws

    Throws an error if the JSON string cannot be deserialized.

    Declaration

    Swift

    public static func parseArray(jsonData: Data) throws -> [Map]

    Parameters

    jsonData

    The JSON Data that will be deserialized
    encoding

    The encoding used on the string

  • Returns the JSON dictionary representation of this map.

    Declaration

    Swift

    public func makeDictionary() -> [String : Any?]

    Return Value

    A dictionary object representing this map.

  • Serializes this object into a JSON Data object.

    Throws

    Throws an error if this object failed to serialize.

    Declaration

    Swift

    public func jsonData(options: JSONSerialization.WritingOptions = []) throws -> Data

    Parameters

    options

    The writing options.

    Return Value

    The serialized object.

  • Serializes this object into a JSON String.

    Throws

    Throws an error if this object failed to serialize.

    Declaration

    Swift

    public func jsonString(options: JSONSerialization.WritingOptions = [], encoding: String.Encoding = .utf8) throws -> String?

    Parameters

    options

    The writing options.
    encoding

    The string encoding that should be used.

    Return Value

    The serialized object.

  • Add a value to the map. The object added should always be a MapPrimitive (JSON value) otherwise parsing this object into JSON will result in a runtime exception.

    Declaration

    Swift

    public func add(_ value: Any?, for key: MapKey) throws

    Parameters

    value

    The value that will be stored in the map.
    key

    The key that will be used to store this value and that can be used to retrive this value.

  • Returns a value from the map. All values returned will always conform to MapPrimitive unless the add method was used incorrectly.

    Declaration

    Swift

    public func value(from key: MapKey) throws -> Any?

    Parameters

    key

    The key that that is used to store this value in the map.

    Return Value

    The stored object.

MapEncodable

  • Add a value to the map encoding it using the provided MapEncoder.

    Declaration

    Swift

    public func add<T>(_ value: T.Object?, for key: MapKey, using encoder: T) throws where T : MapEncoder

    Parameters

    value

    The value that will be stored in this map.
    key

    The JSON key that will be used for the JSON object.
    encoder

    The encoder that will be used to serialize the object.

  • Returns a value from the map. The value will be decoded it using the provided MapDecoder.

    Throws

    Throws an error if the value could not be deserialized or if it is nil.

    Declaration

    Swift

    public func value<T>(from key: MapKey, using decoder: T) throws -> T.Object where T : MapDecoder

    Parameters

    key

    The JSON key for the object that will be deserialized.

    Return Value

    The deserialized object.

MapPrimitive

  • Add a MapPrimitive value to the map. A MapPrimitive is any value supported by a JSON object. MapPrimitive values includes (but not limited to):

    Declaration

    Swift

    public func add<T>(_ value: T?, for key: MapKey) throws where T : MapPrimitive

    Parameters

    value

    The value that will be stored in the map.
    key

    The JSON key that will be used for the JSON object.

  • Returns a value from the map if it conforms to the specified MapPrimitive type.

    Throws

    Throws an error if the value could not be deserialized or it is nil.

    Declaration

    Swift

    public func value<T>(from key: MapKey) throws -> T where T : MapPrimitive

    Parameters

    key

    The JSON key for the primitive that will be returned.

    Return Value

    The deserialized object.

  • Returns a set of values from the map if they all conform to the specified MapPrimitive type.

    Throws

    Throws an error if the value could not be deserialized or it is nil.

    Declaration

    Swift

    public func value<T>(from key: MapKey) throws -> Set<T> where T : MapPrimitive, T : Hashable

    Parameters

    key

    The JSON key for the array that will be deserialized.

    Return Value

    The deserialized object.

RawRepresentable

  • Add a value to the map. The object will be converted to its raw type.

    Declaration

    Swift

    public func add<T>(_ value: T?, for key: MapKey) throws where T : RawRepresentable

    Parameters

    value

    The value that will be stored in the map.
    key

    The JSON key that will be used for the JSON object.

  • Returns a value from the map. The object will be converted from its RawType into the .

    Throws

    Throws an error if the value could not be converted to the specified type or it is nil.

    Declaration

    Swift

    public func value<T>(from key: MapKey) throws -> T where T : RawRepresentable

    Parameters

    key

    The JSON key for the object that will be deserialized.

    Return Value

    The deserialized object.

  • Add a value to the map

    Declaration

    Swift

    public func add<T>(_ value: [T]?, for key: MapKey) throws where T : RawRepresentable

    Parameters

    value

    The value that will be stored in the map. Will be converted to its RawType.
    key

    The JSON key that will be used for the JSON object.

  • Returns a value from the map

    Throws

    Throws an error if the value is invalid or it is nil. Filters out any enums that don’t serialize properly instead of failing.

    Declaration

    Swift

    public func value<T>(from key: MapKey) throws -> [T] where T : RawRepresentable

    Parameters

    key

    The JSON key for the array that will be deserialized.

    Return Value

    The deserialized object.

  • Add a dictionary of the RawRepresentable types converted to JSON primatives.

    Declaration

    Swift

    public func add<T>(_ value: [String : T]?, for key: MapKey) throws where T : RawRepresentable

    Parameters

    value

    The value that will be stored in the map. Will be converted to its RawType.
    key

    The JSON key that will be used for the JSON object.

  • Returns a dictionary of the specified RawRepresentable types.

    Throws

    Throws an error if the value is invalid or it is nil. Filters out any enums that don’t serialize properly instead of failing.

    Declaration

    Swift

    public func value<T>(from key: MapKey) throws -> [String : T] where T : RawRepresentable

    Parameters

    key

    The JSON key for the dictionary that will be deserialized.

    Return Value

    The deserialized object.

  • Add a value to the map. The object will be converted to a JSON primative.

    Declaration

    Swift

    public func add<T>(_ value: Set<T>?, for key: MapKey) throws where T : Hashable, T : RawRepresentable

    Parameters

    value

    The value that will be stored in the map. Will be converted to its RawType.
    key

    The JSON key that will be used for the JSON object.

  • Returns a set of objects converted to the specified RawRepresentable type.

    Throws

    Throws an error if the value is invalid or it is nil. Filters out any enums that don’t serialize properly instead of failing.

    Declaration

    Swift

    public func value<T>(from key: MapKey) throws -> Set<T> where T : Hashable, T : RawRepresentable

    Parameters

    key

    The JSON key for the array that will be deserialized.

    Return Value

    The deserialized object.

Codable

  • Add a value to the map.

    Declaration

    Swift

    public func add<T>(encodable: T?, for key: MapKey) throws where T : Encodable

    Parameters

    value

    the nested Encodable object that will be serialized to JSON be stored in the map.
    key

    The JSON key that will be used for the JSON object.

  • Returns a Decodable value from the map.

    Throws

    Throws an error if the value could not be decoded or if it is nil.

    Declaration

    Swift

    public func decodable<T>(from key: MapKey) throws -> T where T : Decodable

    Parameters

    key

    The JSON key for the object that will be deserialized.

    Return Value

    The decoded object.

MapCodable

  • Add a value to the map. The object will be serialized to JSON.

    Declaration

    Swift

    public func add<T>(_ encodable: T?, for key: MapKey) throws where T : MapEncodable

    Parameters

    value

    the nested MapEncodable object that will be stored in the map.
    key

    The JSON key that will be used for the JSON object.

  • Returns a value from the map. The object will be converted from JSON..

    Throws

    Throws an error if the value could not be deserialized or if it is nil.

    Declaration

    Swift

    public func value<T>(from key: MapKey) throws -> T where T : MapDecodable

    Parameters

    key

    The JSON key for the object that will be deserialized.

    Return Value

    The deserialized object.

  • Add an array to the map. The objects will be converted by using their mapping function.

    Declaration

    Swift

    public func add<T>(_ encodableArray: [T], for key: MapKey) throws where T : MapEncodable

    Parameters

    value

    The nested MapEncodable array that will be stored in the map.
    key

    The JSON key that will be used for the JSON object.

  • Returns a value from the map. Deserializes the object from [[String: Any?]]`. The object will be converted by using its mapping function.

    Throws

    Throws an error if the value could not be deserialized or it is nil and no default value was specified.

    Declaration

    Swift

    public func value<T: MapDecodable>(from key: MapKey, stopOnFailure: Bool = false) throws -> [T]

    Parameters

    key

    The JSON key for the array of objects that will be deserialized.

    Return Value

    The deserialized object.

  • Add an array to the map. The objects will be converted by using their mapping function.

    Declaration

    Swift

    public func add<T>(_ values: [String : T], for key: MapKey) throws where T : MapEncodable

    Parameters

    value

    The nested MapEncodable array that will be stored in the map.
    key

    The JSON key that will be used for the JSON object.

  • Returns a value from the map. Deserializes the object from [String: [String: Any?]]. The object will be converted by using its mapping function.

    Throws

    Throws an error if the value could not be deserialized or it is nil.

    Declaration

    Swift

    public func value<T: MapDecodable>(from key: MapKey, stopOnFailure: Bool = false) throws -> [String: T]

    Parameters

    key

    The JSON key for the dictionary of objects that will be deserialized.

    Return Value

    The deserialized object.