EnumerationJSON

JSON

A JSON variant value. This value may contain a fragment, an array, or an object.

enum JSON

Overview

You can parse JSON from any Collection of UTF-8 data using the init(parsing:) initializer. For example, you can parse from a (sub)string via its UTF8View.

let json:JSON = try .init(parsing: "{\"hello\": \"world\"}".utf8)

All instances of this type, including number(_:) instances, can be round-tripped losslessly, as long as the initial encoding is performed by swift-json.

As of version 0.3.0, re-encoding a swift-json-encoded message is guaranteed to produce bytewise-identical output.

When re-encoding arbitrary JSON, the implementation makes a reasonable effort to preserve features of the original input. It will not re-order object fields, strip explicit null values, or convert decimals to floating point. The parser does not preserve structural whitespace.

The implementation guarantees canonical equivalence when re-encoding values, but it may not preserve the exact expressions used to represent them. For example, it will normalize the escape sequences in "6\\/14\\/1946" to "6/14/1946", because the escaped forward-slashes (/) are non-canonical.

Decoding with `Codable`

JSON implements Decoder, so you can use it with any type that conforms to Decodable.

Decoding with high-performance APIs

The standard library’s decoding system suffers from inherent inefficiencies due to how it is defined. The recommended way to decode JSON is to use its LintingDictionary API, alongside this module’s Array extensions.

Most of swift-json’s linting and array APIs take closure arguments. You should perform decoding subtasks inside the closure bodies in order to take full advantage of the library’s error reporting.

These APIs are low-cost abstractions that only incur overhead when decoding fails. They can be significantly faster than the standard library’s Decoder hooks, and only slightly more verbose than an equivalent Decodable implementation.

Members

Enumeration Cases

case array([JSON])
An array, which can recursively contain instances of Self.
case bool(Bool)
A boolean value.
case null
A null value.
case number(JSON.Number)
A numerical value.
case object([(key: String, value: JSON)])
A String-keyed object, which can recursively contain instances of Self.
case string(String)
A string value.

Initializers

init(arrayLiteral: JSON...)
Creates an instance initialized with the given elements.
init(booleanLiteral: Bool)
Creates an instance initialized to the given Boolean value.
init(dictionaryLiteral: (String, JSON)...)
Creates an instance initialized with the given key-value pairs.
init(extendedGraphemeClusterLiteral: Self.StringLiteralType)
Creates an instance initialized to the given value.
init<UTF8>(parsing: UTF8) throws
Attempts to parse a complete JSON message (either an Array or an Object) from UTF-8-encoded text.
init(stringLiteral: String)
Creates an instance initialized to the given string value.
init(unicodeScalarLiteral: Self.ExtendedGraphemeClusterLiteralType)
Creates an instance initialized to the given value.

Instance Properties

var codingPath: [CodingKey]
The path of coding keys taken to get to this point in decoding.
var description: String
Returns this value serialized as a minified string.
var halfWidthCornerQuoted: String
var userInfo: [CodingUserInfoKey : Any]
Any contextual information set by the user for decoding.

Type Methods

static func escape<S>(S) -> String
Escapes and formats a string as a JSON string literal, including the beginning and ending quote characters.
static func number<T>(T) -> JSON
Wraps a signed integer as a numeric value.
static func number<T>(T) -> JSON
Wraps an usigned integer as a numeric value.

Instance Methods

func `as`([(key: String, value: JSON)].Type) throws -> [(key: String, value: JSON)]
func `as`<Integer>(Integer.Type) throws -> Integer
func `as`<Integer>(Integer.Type) throws -> Integer
func `as`(String.Type) throws -> String
func `as`([JSON].Type) throws -> [JSON]
func `as`(Bool?.Type) throws -> Bool?
func `as`<Integer>(Integer.Type) throws -> Integer?
Attempts to load an instance of some SignedInteger from this variant.
func `as`<Binary>(Binary.Type) -> Binary?
Attempts to load an instance of some BinaryFloatingPoint type from this variant.
func `as`<Binary>(Binary?.Type) throws -> Binary?
func `as`(String?.Type) throws -> String?
func `as`([JSON]?.Type) throws -> [JSON]?
func `as`(String.Type) -> String?
Attempts to unwrap an instance of String from this variant.
func `as`([(key: String, value: JSON)]?.Type) throws -> [(key: String, value: JSON)]?
func `as`<Integer>(Integer?.Type) throws -> Integer?
func `as`([(key: String, value: JSON)].Type) -> [(key: String, value: JSON)]?
Attempts to unwrap an Array of key-value pairs from this variant.
func `as`<Integer>(Integer.Type) throws -> Integer?
Attempts to load an instance of some UnsignedInteger from this variant.
func `as`(Void.Type) throws
Attempts to unwrap an explicit null from this variant.
func `as`(Void.Type) -> Void?
Attempts to unwrap an explicit null from this variant.
func `as`(Bool.Type) throws -> Bool
func `as`([JSON].Type) -> [JSON]?
func `as`(Bool.Type) -> Bool?
Attempts to unwrap an instance of Bool from this variant.
func `as`<Integer>(Integer?.Type) throws -> Integer?
func `as`<Binary>(Binary.Type) throws -> Binary
func `as`([JSON]?.Type, count: Int) throws -> [JSON]?
Attempts to unwrap a fixed-length Array of Self or an explicit null from this variant.
func `as`([JSON].Type, count: Int) throws -> [JSON]
Attempts to unwrap a fixed-length Array of Self from this variant.
func `as`([String : JSON].Type, uniquingKeysWith: (JSON, JSON) throws -> JSON) throws -> [String : JSON]
Attempts to load a Dictionary from this variant, de-duplicating keys with the given closure.
func `as`([String : JSON].Type, uniquingKeysWith: (JSON, JSON) throws -> JSON) rethrows -> [String : JSON]?
Attempts to load a Dictionary from this variant, de-duplicating keys with the given closure.
func `as`([String : JSON]?.Type, uniquingKeysWith: (JSON, JSON) throws -> JSON) throws -> [String : JSON]?
Attempts to load a Dictionary from this variant, de-duplicating keys with the given closure.
func `as`([JSON].Type, where: (Int) throws -> Bool) throws -> [JSON]
Attempts to unwrap an Array of Self from this variant, whose length satifies the given criteria.
func `as`([JSON]?.Type, where: (Int) throws -> Bool) throws -> [JSON]?
Attempts to unwrap an Array of Self from this variant, whose length satifies the given criteria, or an explicit null.
func `as`<StringCoded>(cases: StringCoded.Type) throws -> StringCoded
Attempts to load an instance of some String-backed type from this variant.
func `as`<CharacterCoded>(cases: CharacterCoded.Type) throws -> CharacterCoded
Attempts to load an instance of some Character-backed type from this variant.
func `as`<ScalarCoded>(cases: ScalarCoded.Type) throws -> ScalarCoded
Attempts to load an instance of some Unicode.Scalar-backed type from this variant.
func `as`<IntegerCoded>(cases: IntegerCoded.Type) throws -> IntegerCoded
Attempts to load an instance of some SignedInteger-backed type from this variant.
func `as`<UnsignedIntegerCoded>(cases: UnsignedIntegerCoded.Type) throws -> UnsignedIntegerCoded
Attempts to load an instance of some UnsignedInteger-backed type from this variant.
func container<Key>(keyedBy: Key.Type) throws -> KeyedDecodingContainer<Key>
Returns the data stored in this decoder as represented in a container keyed by the given key type.
func flatMatch<T>((JSON) -> (T.Type) throws -> T?) throws -> T?
Promotes a nil result to a thrown PrimitiveError, if this variant is not an explicit null.
func `is`(Void.Type) -> Bool
Indicates if this variant is null.
func lint<T>((inout JSON.LintingDictionary) throws -> T) throws -> T
Provides a linting context for the given decoding task.
func lint<Discards, T>(discarding: Discards, (inout JSON.LintingDictionary) throws -> T) throws -> T
Provides a linting context for the given decoding task, removing the specified keys beforehand.
func lint<Whitelist, T>(whitelisting: Whitelist, (inout JSON.LintingDictionary) throws -> T) throws -> T
Provides a linting context for the given decoding task, removing the specified keys afterwards if the decoder did not consume them.
func match<T>((JSON) -> (T.Type) throws -> T?) throws -> T
Promotes a nil result to a thrown PrimitiveError.
func singleValueContainer() -> SingleValueDecodingContainer
Returns the data stored in this decoder as represented in a container appropriate for holding a single primitive value.
func unkeyedContainer() throws -> UnkeyedDecodingContainer
Returns the data stored in this decoder as represented in a container appropriate for holding values with no keys.

Enumerations

enum Base10
A namespace for decimal-related functionality.
enum PrimitiveError
A primitive decoding operation failed.
enum RecursiveError
An error occurred while performing a decoding operation on an element of an array or object.
enum Rule
All of the parsing rules in this library are defined at the UTF-8 level.

Structures

struct Decoder
A single-value decoding container, for use with compiler-generated Decodable implementations.
struct IntegerOverflowError
An integer overflow occurred while converting a number literal to a desired type.
struct InvalidUnicodeScalarError
A string literal contained a unicode escape sequence that does not encode a valid Unicode.Scalar.
struct LintingDictionary
A mutable wrapper around a JSON object for efficient, type-safe decoding.
struct LintingError
A decoder did not consume, discard, or whitelist all the available keys in a JSON object.
struct Number
A lossless representation of a numeric literal.

JSON

Overview

Decoding with Codable

Decoding with high-performance APIs

Members

Enumeration Cases

Initializers

Instance Properties

Type Methods

Instance Methods

Enumerations

Structures

Conforms To

Removed Members

Instance Methods

Decoding with `Codable`