-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Library for efficiently building up buffers, one piece at a time
--   
@package buffer-builder
@version 0.2.2.1


-- | A library for efficiently building up a buffer of data. When given
--   data known to be strict, use of BufferBuilder compiles directly into a
--   series of efficient C function calls.
module Data.BufferBuilder

-- | BufferBuilder is the type of a monadic action that appends to an
--   implicit, growable buffer. Use <a>runBufferBuilder</a> to extract the
--   resulting buffer as a <a>ByteString</a>.
data BufferBuilder a

-- | Run a sequence of <a>BufferBuilder</a> actions and extract the
--   resulting buffer as a <a>ByteString</a>.
runBufferBuilder :: BufferBuilder () -> ByteString
data Options
Options :: !Int -> !Bool -> Options
initialCapacity :: Options -> !Int
trimFinalBuffer :: Options -> !Bool
runBufferBuilderWithOptions :: Options -> BufferBuilder () -> ByteString

-- | Append a single byte to the output buffer. To append multiple bytes in
--   sequence and avoid redundant bounds checks, consider using
--   <a>appendBS</a>, <a>appendLiteral</a>, or <a>unsafeAppendLiteralN</a>.
appendByte :: Word8 -> BufferBuilder ()

-- | Appends a character to the buffer, truncating it to the bottom 8 bits.
appendChar8 :: Char -> BufferBuilder ()

-- | Appends a <a>ByteString</a> to the buffer. When appending constant,
--   hardcoded strings, to avoid a CAF and the costs of its associated tag
--   check and indirect jump, use <a>appendLiteral</a> or
--   <a>unsafeAppendLiteralN</a> instead.
appendBS :: ByteString -> BufferBuilder ()

-- | Appends a lazy <a>ByteString</a> to the buffer. This function operates
--   by traversing the lazy <a>ByteString</a> chunks, appending each in
--   turn.
appendLBS :: ByteString -> BufferBuilder ()

-- | Appends a zero-terminated MagicHash string literal. Use this function
--   instead of <a>appendBS</a> for string constants. For example:
--   
--   <pre>
--   appendLiteral "true"#
--   </pre>
--   
--   If the length of the string literal is known, calling
--   <a>unsafeAppendLiteralN</a> is faster, as <a>unsafeAppendLiteralN</a>
--   avoids a strlen operation which has nontrivial cost in some
--   benchmarks.
appendLiteral :: Addr# -> BufferBuilder ()

-- | Appends a MagicHash string literal with a known length. Use this when
--   the string literal's length is known. For example:
--   
--   <pre>
--   unsafeAppendLiteralN 4 "true"#
--   </pre>
--   
--   Per byte, this is the fastest append function. It amounts to a C
--   function call with two constant arguments. The C function checks to
--   see if it needs to grow the buffer and then it simply calls memcpy.
--   
--   <b>WARNING</b>: passing an incorrect length value is likely to cause
--   an access violation or worse.
unsafeAppendLiteralN :: Int -> Addr# -> BufferBuilder ()
appendByte7 :: Word8 -> BufferBuilder ()
appendChar7 :: Char -> BufferBuilder ()
appendBS7 :: ByteString -> BufferBuilder ()
appendLiteral7 :: Addr# -> BufferBuilder ()
unsafeAppendLiteralN7 :: Int -> Addr# -> BufferBuilder ()

-- | Appends a UTF-8-encoded <a>Char</a> to the buffer.
appendCharUtf8 :: Char -> BufferBuilder ()

-- | Appends a UTF-8-encoded <a>String</a> to the buffer. The best way to
--   improve performance here is to use <a>ByteString</a> or <a>Text</a>
--   instead of <a>String</a>.
appendStringUtf8 :: String -> BufferBuilder ()

-- | Appends a decimal integer, just like calling printf("%d", ...)
appendDecimalSignedInt :: Int -> BufferBuilder ()

-- | Appends a decimal double, just like calling printf("%f", ...)
appendDecimalDouble :: Double -> BufferBuilder ()
appendEscapedJson :: ByteString -> BufferBuilder ()
appendEscapedJsonLiteral :: Addr# -> BufferBuilder ()
appendEscapedJsonText :: Text -> BufferBuilder ()

-- | Append a percent-encoded ByteString. All characters except for
--   alphanumerics, -, ., _, and ~ will be encoded. The string produced by
--   URL encoding is guaranteed ASCII-7 and thus valid UTF-8. Moreover, it
--   is not required to be JSON-escaped.
appendUrlEncoded :: ByteString -> BufferBuilder ()
instance Typeable BufferOutOfMemoryError
instance Show BufferOutOfMemoryError
instance Exception BufferOutOfMemoryError
instance Monad BufferBuilder
instance Applicative BufferBuilder
instance Functor BufferBuilder


-- | A library for efficiently building up a buffer of UTF-8-encoded text.
--   If only safe functions are used, the resulting <a>ByteString</a> is
--   guaranteed to be valid UTF-8.
--   
--   To run a sequence of Utf8Builder actions and retrieve the resulting
--   buffer, use <a>runUtf8Builder</a>.
--   
--   In special situations, for maximum performance, unsafe functions are
--   also provided. The unsafe functions do not guarantee the buffer is
--   correct UTF-8.
--   
--   This module is built on top of <a>Data.BufferBuilder</a>.
module Data.BufferBuilder.Utf8
data Utf8Builder a

-- | Run a sequence of <a>Utf8Builder</a> actions and extracting the
--   resulting buffer as a <a>ByteString</a>.
runUtf8Builder :: Utf8Builder () -> ByteString

-- | Encodes the given <a>Text</a> in UTF-8, appending it to the buffer.
appendText :: Text -> Utf8Builder ()

-- | Encodes the given <a>String</a> in UTF-8, appending it to the buffer.
appendString :: String -> Utf8Builder ()

-- | Encodes a single <a>Char</a> in UTF-8, appending it to the buffer.
appendChar :: Char -> Utf8Builder ()

-- | Appends the bottom 7 bits of a byte to the buffer.
appendByte7 :: Word8 -> Utf8Builder ()

-- | Appends the bottom 7 bits of a <a>Char</a> to the buffer.
appendChar7 :: Char -> Utf8Builder ()

-- | Appends the given ByteString to the buffer, taking the bottom 7 bits
--   of each byte.
appendBS7 :: ByteString -> Utf8Builder ()

-- | Appends the zero-terminated byte string at the given address to the
--   buffer, taking the bottom 7 bits of each byte.
appendLiteral7 :: Addr# -> Utf8Builder ()
appendDecimalSignedInt :: Int -> Utf8Builder ()
appendDecimalDouble :: Double -> Utf8Builder ()
appendEscapedJson :: ByteString -> Utf8Builder ()
appendEscapedJsonLiteral :: Addr# -> Utf8Builder ()
appendEscapedJsonText :: Text -> Utf8Builder ()

-- | Directly append a byte into the UTF-8 code stream. Incorrect use of
--   this function can result in invalid UTF-8.
unsafeAppendByte :: Word8 -> Utf8Builder ()

-- | Directly append the bottom 8 bits of the given character to the UTF-8
--   code stream. Incorrect use of this function can result in invalid
--   UTF-8.
unsafeAppendChar8 :: Char -> Utf8Builder ()

-- | Directly append the zero-terminated byte sequence pointed to by the
--   given address. Be careful that the referenced byte sequence contains
--   valid UTF-8.
unsafeAppendLiteral :: Addr# -> Utf8Builder ()

-- | Directly append the given byte sequence pointed to by the given
--   address. Be careful that the referenced byte sequence contains valid
--   UTF-8.
--   
--   <b>WARNING</b>: passing an incorrect length value is likely to cause
--   an access violation or worse.
unsafeAppendLiteralN :: Int -> Addr# -> Utf8Builder ()

-- | Directly append the given <a>ByteString</a> to the output buffer. Be
--   careful that the referenced <a>ByteString</a> contains valid UTF-8.
unsafeAppendBS :: ByteString -> Utf8Builder ()
instance Functor Utf8Builder
instance Applicative Utf8Builder
instance Monad Utf8Builder


-- | A library for efficiently building up a valid JSON document.
--   
--   The difference between <a>Data.BufferBuilder.Json</a> and the
--   excellent <a>Data.Aeson</a> is that Aeson represents the JSON document
--   as an in-memory tree structure before encoding it into bytes. This
--   module, on the other hand, represents each value as an action that
--   writes its representation directly into the output buffer. At the cost
--   of reduced flexibility, this results in significantly improved
--   encoding performance. At the time of this writing, encoding a custom
--   record type into JSON using this module was almost 5x faster than
--   using Aeson.
--   
--   This module is built on top of <a>Data.Utf8Builder</a>.
module Data.BufferBuilder.Json

-- | Represents a JSON value.
--   
--   <a>Value</a>s are built up from either <a>ToJson</a> instances or from
--   primitives like <a>emptyObject</a>, <a>array</a>, and <a>null</a>.
--   
--   In special cases, or when performance is of utmost importance, the
--   unsafe functions <a>unsafeAppendUtf8Builder</a> are available.
--   
--   Internally, Value encodes an action or sequence of actions that append
--   JSON-encoded text to the underlying <a>Utf8Builder</a>.
data Value

-- | The class of types that can be converted to JSON values. See
--   <a>ObjectBuilder</a> for an example of writing a <a>ToJson</a>
--   instance for a custom data type.
--   
--   <a>ToJson</a> instances are provided for many common types. For
--   example, to create a JSON array, call <a>toJson</a> on a list or
--   <a>Vector</a>. To create a JSON object, call <a>toJson</a> on a
--   <a>HashMap</a>.
class ToJson a
toJson :: ToJson a => a -> Value

-- | Encode a value into a <a>ByteString</a> containing valid UTF-8-encoded
--   JSON. The argument value must have a corresponding <a>ToJson</a>
--   instance.
--   
--   <b>WARNING</b>: There are three cases where the resulting
--   <a>ByteString</a> may not contain legal JSON:
--   
--   <ul>
--   <li>An unsafe function was used to encode a JSON value.</li>
--   <li>The root value is not an object or array, as the JSON
--   specification requires.</li>
--   <li>An object has multiple keys with the same value. For maximum
--   efficiency, <a>ObjectBuilder</a> does not check key names for
--   uniqueness, so it's possible to construct objects with duplicate
--   keys.</li>
--   </ul>
encodeJson :: ToJson a => a -> ByteString

-- | Represents a JSON string.
data JsonString

-- | 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.
class ToJson a => ToJsonString a
toJsonString :: ToJsonString a => a -> JsonString

-- | Builds a JSON object.
--   
--   An <a>ObjectBuilder</a> builds one or more key-value pairs of a JSON
--   object. They are constructed with the <a>.=</a> operator and combined
--   with <a>&lt;&gt;</a>.
--   
--   To turn an <a>ObjectBuilder</a> into a <a>Value</a>, use its
--   <a>ToJson</a> class instance.
--   
--   <pre>
--   data Friend = Friend
--       { fId :: !Int
--       , fName :: !Text
--       } deriving (Eq, Show)
--   
--   instance ToJson Friend where
--       toJson friend = toJson $
--                  "id"   .= fId friend
--               &lt;&gt; "name" .= fName friend
--   </pre>
--   
--   <b>WARNING</b>: <a>ObjectBuilder</a> does not check uniqueness of
--   object keys. If two keys with the same value are inserted, then the
--   resulting JSON document will be illegal.
data ObjectBuilder

-- | A <a>Value</a> that produces the empty object.
emptyObject :: Value

-- | Create an <a>ObjectBuilder</a> from a key and a value.
(.=) :: ToJson a => Text -> a -> ObjectBuilder

-- | Create an <a>ObjectBuilder</a> from a key and a value. The key is an
--   ASCII-7, unescaped, zero-terminated <a>Addr#</a>.
--   
--   <b>WARNING</b>: 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.
--   
--   <pre>
--   data Friend = Friend
--       { fId :: !Int
--       , fName :: !Text
--       } deriving (Eq, Show)
--   
--   instance ToJson Friend where
--       toJson friend = toJson $
--                  "id"#   .=# fId friend
--               &lt;&gt; "name"# .=# fName friend
--   </pre>
(.=#) :: ToJson a => Addr# -> a -> ObjectBuilder

-- | Create an ObjectBuilder from an arbitrary key and value. The key can
--   be any type with a <a>ToJsonString</a> instance.
row :: (ToJsonString k, ToJson v) => k -> v -> ObjectBuilder

-- | Serialize any <a>Foldable</a> as a JSON array. This is generally
--   slower than directly calling <a>toJson</a> on a list or <a>Vector</a>,
--   but it will convert any <a>Foldable</a> type into an array.
array :: (Foldable t, ToJson a) => t a -> Value

-- | Represents a JSON "null".
nullValue :: Value

-- | Unsafely convert a <a>Utf8Builder</a> into a JSON value. This function
--   does not escape, quote, or decorate the string in any way. This
--   function is <i>unsafe</i> because you can trivially use it to generate
--   illegal JSON.
unsafeValueUtf8Builder :: Utf8Builder () -> Value

-- | Unsafely convert a <a>Utf8Builder</a> into a JSON string. This
--   function does not escape, quote, or decorate the string in any way.
--   This function is <i>unsafe</i> because you can trivially use it to
--   generate illegal JSON.
unsafeStringUtf8Builder :: Utf8Builder () -> JsonString

-- | <i>Deprecated: Use unsafeValueUtf8Builder or unsafeStringUtf8Builder
--   instead</i>
unsafeAppendUtf8Builder :: Utf8Builder () -> Value

-- | <i>Deprecated: Use unsafeValueUtf8Builder or unsafeStringUtf8Builder
--   instead</i>
unsafeAppendBS :: ByteString -> Value
instance ToJsonString Text
instance ToJson JsonString
instance ToJsonString JsonString
instance ToJson Int
instance ToJson Double
instance ToJson Text
instance ToJson a => ToJson (Maybe a)
instance ToJson Bool
instance ToJson Value
instance (Vector Vector a, ToJson a) => ToJson (Vector a)
instance (Prim a, ToJson a) => ToJson (Vector a)
instance (Storable a, ToJson a) => ToJson (Vector a)
instance ToJson a => ToJson (Vector a)
instance ToJson a => ToJson [a]
instance (ToJsonString k, ToJson v) => ToJson (HashMap k v)
instance ToJson ObjectBuilder
instance Monoid ObjectBuilder