Represents a JSON value.

Values are built up from either ToJson instances or from primitives like emptyObject, array, and null.

In special cases, or when performance is of utmost importance, the unsafe functions unsafeAppendUtf8Builder are available.

Internally, Value encodes an action or sequence of actions that append JSON-encoded text to the underlying Utf8Builder.

The class of types that can be converted to JSON values. See ObjectBuilder for an example of writing a ToJson instance for a custom data type.

ToJson instances are provided for many common types. For example, to create a JSON array, call toJson on a list or Vector. To create a JSON object, call toJson on a HashMap.

Encode a value into a ByteString containing valid UTF-8-encoded JSON. The argument value must have a corresponding ToJson instance.

WARNING: There are three cases where the resulting ByteString may not contain legal JSON:

• An unsafe function was used to encode a JSON value.
• The root value is not an object or array, as the JSON specification requires.
• An object has multiple keys with the same value. For maximum efficiency, ObjectBuilder does not check key names for uniqueness, so it's possible to construct objects with duplicate keys.

Represents a JSON string.

The class of types that can be converted to JSON strings. Any type that provides ToJsonString also provides ToJson, and thus can be used as JSON values.

Builds a JSON object.

An ObjectBuilder builds one or more key-value pairs of a JSON object. They are constructed with the .= operator and combined with <>.

To turn an ObjectBuilder into a Value, use its ToJson class instance.

    data Friend = Friend
        { fId :: !Int
        , fName :: !Text
        } deriving (Eq, Show)

    instance ToJson Friend where
        toJson friend = toJson $
                   "id"   .= fId friend
                <> "name" .= fName friend

WARNING: ObjectBuilder does not check uniqueness of object keys. If two keys with the same value are inserted, then the resulting JSON document will be illegal.

A Value that produces the empty object.

Create an ObjectBuilder from a key and a value.

Create an ObjectBuilder from a key and a value. The key is an ASCII-7, unescaped, zero-terminated Addr#.

WARNING: This function is unsafe. If the key is NOT zero-terminated, then an access violation might result. If the key is not a sequence of unescaped ASCII characters, the resulting JSON document will be illegal.

This function is provided for maximum performance in the common case that object keys are ASCII-7. It achieves performance by avoiding the CAF for a Text literal and avoiding the need to transcode UTF-16 to UTF-8 and escape.

To use this function, the calling source file must have the MagicHash extension enabled.

    data Friend = Friend
        { fId :: !Int
        , fName :: !Text
        } deriving (Eq, Show)

    instance ToJson Friend where
        toJson friend = toJson $
                   "id"#   .=# fId friend
                <> "name"# .=# fName friend

Create an ObjectBuilder from an arbitrary key and value. The key can be any type with a ToJsonString instance.

Serialize any Foldable as a JSON array. This is generally slower than directly calling toJson on a list or Vector, but it will convert any Foldable type into an array.

Represents a JSON "null".

Unsafely convert a Utf8Builder into a JSON value. This function does not escape, quote, or decorate the string in any way. This function is unsafe because you can trivially use it to generate illegal JSON.

Unsafely convert a Utf8Builder into a JSON string. This function does not escape, quote, or decorate the string in any way. This function is unsafe because you can trivially use it to generate illegal JSON.