JSONPathExtractable

public protocol JSONPathExtractable<Root>

A generic container of items that can return a DataItem for a given JSONPath.

  • The root type that defines the starting point for JSON path extraction (if it’s an object or an array).

    Declaration

    Swift

    associatedtype Root : PathRoot

  • Extracts a nested DataItem according to the given JSONPath.

    Declaration

    Swift

    func extractDataItem(path: JSONPath<Root>) -> DataItem?

    Parameters

    path

    The JSONPath describing the path to a potentially nested item.

    Return Value

    The required DataItem if found; else nil.

  • extract(path:as:) Extension method

    Returns the data at the given path in the requested type if the conversion is possible.

    This is equivalent to get(key:as:), except it can search for nested values inside dictionaries and arrays by using a JSONPath<Root>.

    As an example, in the following snippet:

     let object = DataObject(dictionary: [
   "root": [
      "item"
   ]
 ])
 let result = object.extract(path: JSONPath<Root>("root")[0], as: String.self)

    The result would be the string “item”.

    Supported types are:

    • Double
    • Float
    • Int
    • Int64
    • Bool
    • String
    • NSNumber

    You can call this method without parameters if the return type can be inferred:

     let dataExtractor: DataItemExtractor = ...
 let anInt: Int? = dataExtractor.extract(path: JSONPath<Root>("someKey"))

    Alternatively the type must be specified as a parameter:

     let dataExtractor: DataItemExtractor = ...
 let anInt = dataExtractor.extract(path: JSONPath<Root>("someKey"), as: Int.self)

    Every numeric type (Int, Int64, Float, Double, NSNumber) can be used interchangeably and the conversion will be made following NSNumber conversion methods.

     let nsNumber = NSNumber(1.5)
 let dataExtractor: DataItemExtractor = DataObject(dictionary: ["someKey": nsNumber])
 let aDouble: Double? = dataExtractor.extract(path: JSONPath<Root>("someKey")) // Double(1.5)
 let anInt: Int? = dataExtractor.extract(path: JSONPath<Root>("someKey")) // Int(1)

    Declaration

    Swift

    func extract<T>(path: JSONPath<Root>, as type: T.Type = T.self) -> T? where T : DataInput

    Parameters

    path

    The path at which to look for the item.
    type

    The expected type of the item.

    Return Value

    The value at the given path if it was found and if it was of the correct type.

  • Gets and converts the item at the given path using the given converter.

    This is equivalent to getConvertible(key:converter:), except it can search for nested values inside dictionaries and arrays by using a JSONPath<Root>.

    Declaration

    Swift

    func extractConvertible<T>(path: JSONPath<Root>, converter: any DataItemConverter<T>) -> T?

    Parameters

    path

    The path at which to look for the item.
    converter

    The converter used to convert the item to the expected type.

    Return Value

    The value at the given path after having been converted by the DataItemConverter.

  • extractDataArray(path:) Extension method

    Returns the value as an Array of DataItems if the underlying value is an Array.

    This is equivalent to getDataArray(key:), except it can search for nested values inside dictionaries and arrays by using a JSONPath<Root>.

    Warning

    Do not cast the return object as any cast will likely fail. Use the appropriate methods to extract value from a DataItem.

    Declaration

    Swift

    func extractDataArray(path: JSONPath<Root>) -> [DataItem]?

    Parameters

    path

    The path at which to look for the array.

    Return Value

    The array of DataItems, if an array is found at the given path.

  • extractDataDictionary(path:) Extension method

    Returns the value as a Dictionary of DataItems if the underlying value is a Dictionary.

    This is equivalent to getDataDictionary(key:), except it can search for nested values inside dictionaries and arrays by using a JSONPath<Root>.

    Warning

    Do not cast the return object as any cast will likely fail. Use the appropriate methods to extract value from a DataItem.

    Declaration

    Swift

    func extractDataDictionary(path: JSONPath<Root>) -> [String : DataItem]?

    Parameters

    path

    The path at which to look for the dictionary.

    Return Value

    The dictionary of DataItems, if a dictionary is found at the given path.

  • extractArray(path:of:) Extension method

    Returns the value at the given path as an Array of the (optional) given type.

    This is equivalent to getArray(key:of:), except it can search for nested values inside dictionaries and arrays by using a JSONPath<Root>.

    This method will follow the same principles of the extract<T: DataInput>(path:as:) counterpart, but applies them on the individual Array elements.

    Supported types are:

    • Double
    • Float
    • Int
    • Int64
    • Bool
    • String
    • NSNumber

    You can call this method without parameters if the return type can be inferred:

     let dataExtractor: DataItemExtractor = ...
 let anIntArray: [Int?]? = dataExtractor.extractArray(path: JSONPath<Root>("someKey"))

    Alternatively the type must be specified as a parameter:

     let dataExtractor: DataItemExtractor = ...
 let anIntArray = dataExtractor.extractArray(path: JSONPath<Root>("someKey"), of: Int.self)

    Every numeric type (Int, Int64, Float, Double, NSNumber) can be used interchangeably and the conversion will be made following NSNumber conversion methods.

     let nsNumber = NSNumber(1.5)
 let dataExtractor: DataItemExtractor = DataObject(dictionary: ["someKey": [nsNumber]])
 let aDoubleArray = dataExtractor.extractArray(path: JSONPath<Root>("someKey"), of: Double.self) // [Double(1.5)]
 let anIntArray = dataExtractor.extractArray(path: JSONPath<Root>("someKey"), of: Int.self) // [Int(1)]

    Declaration

    Swift

    func extractArray<T>(path: JSONPath<Root>, of type: T.Type = T.self) -> [T?]? where T : DataInput

    Parameters

    path

    The path at which to look for the array.
    type

    The expected type of each item of the array is expected to be.

    Return Value

    The array of items of optional type at the given path if it was found. Each item will be nil if they were of the wrong type.

  • extractDictionary(path:of:) Extension method

    Returns the value at the given path as a Dictionary of the (optional) given type.

    This is equivalent to getDictionary(key:of:), except it can search for nested values inside dictionaries and arrays by using a JSONPath<Root>.

    This method will follow the same principles of the extract<T: DataInput>(path:as:) counterpart, but applies them on the individual Dictionary elements.

    Supported types are:

    • Double
    • Float
    • Int
    • Int64
    • Bool
    • String
    • NSNumber

    You can call this method without parameters if the return type can be inferred:

     let dataExtractor: DataItemExtractor = ...
 let anIntDictionary: [String: Int?]? = dataExtractor.extractDictionary(path: JSONPath<Root>("someKey"))

    Alternatively the type must be specified as a parameter:

     let dataExtractor: DataItemExtractor = ...
 let anIntDictionary = dataExtractor.extractDictionary(path: JSONPath<Root>("someKey"), of: Int.self)

    Every numeric type (Int, Int64, Float, Double, NSNumber) can be used interchangeably and the conversion will be made following NSNumber conversion methods.

     let nsNumber = NSNumber(1.5)
 let dataExtractor: DataItemExtractor = DataObject(dictionary: ["someKey": nsNumber])
 let aDoubleDictionary = dataExtractor.extractDictionary(path: JSONPath<Root>("someKey"), of: Double.self) // ["someKey": Double(1.5)]
 let anIntDictionary = dataExtractor.extractDictionary(path: JSONPath<Root>("someKey"), of: Int.self) // ["someKey": Int(1)]

    Declaration

    Swift

    func extractDictionary<T>(path: JSONPath<Root>, of type: T.Type = T.self) -> [String : T?]? where T : DataInput

    Parameters

    path

    The path at which to look for the dictionary.
    type

    The expected type of each item of the dictionary.

    Return Value

    The dictionary of items of optional type at the given path if it was found. Each item will be nil if they were of the wrong type.

Available where Self: DataItemExtractor

  • extractDataItem(path:) Extension method

    Extracts a nested DataItem according to the given JSONObjectPath.

    This is equivalent to getDataItem(key:), except it can search for nested values inside dictionaries and arrays by using a JSONObjectPath.

    If any component of the JSONObjectPath is not found in this DataItemExtractor or its nested objects and arrays, or if it is of the wrong type, nil will be returned.

    As an example, in the following snippet:

     let object = DataObject(dictionary: [
   "root": [
      "item"
   ]
 ])
 let result = object.extractDataItem(path: JSONPath["root"][0])

    The result would be a DataItem containing the string “item”.

    Declaration

    Swift

    func extractDataItem(path: JSONObjectPath) -> DataItem?

    Parameters

    path

    The JSONObjectPath describing the path to a potentially nested item.

    Return Value

    The required DataItem if found; else nil.