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


-- | Builders for arrays
--   
--   Builders for arrays
@package array-builder
@version 0.1.2.0

module Data.Builder

-- | Builder for an array of boxed elements.
newtype Builder a
Builder :: (forall s. SmallMutableArray# s a -> Int# -> Int# -> Chunks a -> State# s -> (# State# s, SmallMutableArray# s a, Int#, Int#, Chunks a #)) -> Builder a
cons :: a -> Builder a -> Builder a

-- | A builder with one element.
singleton :: a -> Builder a

-- | A builder with two elements.
doubleton :: a -> a -> Builder a

-- | A builder with three elements.
tripleton :: a -> a -> a -> Builder a
run :: Builder a -> Chunks a
instance GHC.Base.Monoid (Data.Builder.Builder a)
instance GHC.Base.Semigroup (Data.Builder.Builder a)


-- | <tt>Data.Builder.Bytes</tt> specialized to <tt>Bytes</tt>.
module Data.Builder.Catenable.Bytes
data Builder
Empty :: Builder
Cons :: {-# UNPACK #-} !Bytes -> !Builder -> Builder
Snoc :: !Builder -> {-# UNPACK #-} !Bytes -> Builder
Append :: !Builder -> !Builder -> Builder
pattern (:<) :: Bytes -> Builder -> Builder
infixr 5 :<
pattern (:>) :: Builder -> Bytes -> Builder
infixl 5 :>
run :: Builder -> Chunks
instance GHC.Base.Monoid Data.Builder.Catenable.Bytes.Builder
instance GHC.Base.Semigroup Data.Builder.Catenable.Bytes.Builder


-- | <tt>Data.Builder.Catenable</tt> specialized to <tt>ShortText</tt>.
module Data.Builder.Catenable.Text
data Builder
Empty :: Builder
Cons :: !ShortText -> !Builder -> Builder
Snoc :: !Builder -> !ShortText -> Builder
Append :: !Builder -> !Builder -> Builder
pattern (:<) :: ShortText -> Builder -> Builder
infixr 5 :<
pattern (:>) :: Builder -> ShortText -> Builder
infixl 5 :>

-- | The result is chunks, but this is guaranteed to be UTF-8 encoded text,
--   so if needed, you can flatten out the chunks and convert back to
--   <tt>ShortText</tt>.
run :: Builder -> Chunks
instance Data.String.IsString Data.Builder.Catenable.Text.Builder
instance GHC.Base.Monoid Data.Builder.Catenable.Text.Builder
instance GHC.Base.Semigroup Data.Builder.Catenable.Text.Builder

module Data.Builder.ST

-- | Builder for an array of boxed elements. This type is appropriate when
--   constructing an array of unknown size in an effectful (<tt>ST</tt> or
--   <tt>IO</tt>) setting. In a non-effectful setting, consider the
--   <tt>Builder</tt> from <tt>Data.Builder</tt> instead.
--   
--   A <a>Builder</a> must be used linearly. The type system does not
--   enforce this, so users must be careful when handling a <a>Builder</a>.
data Builder s a
Builder :: !SmallMutableArray s a -> !Int -> !Int -> !Chunks a -> Builder s a

-- | Create a new <a>Builder</a> with no elements in it.
new :: ST s (Builder s a)

-- | Create a new <a>Builder</a> with a single element. Useful when builder
--   creation is immidiately followed by <a>push</a>. Note that:
--   
--   <pre>
--   new &gt;&gt;= push x ≡ new1 x
--   </pre>
--   
--   But <a>new1</a> performs slightly better.
new1 :: a -> ST s (Builder s a)

-- | Push an element onto the end of the builder. This is not strict in the
--   element, so force it before pushing it on to the builder if doing so
--   is needed to prevent space leaks.
push :: a -> Builder s a -> ST s (Builder s a)

-- | Convert a <a>Builder</a> to <a>Chunks</a>. The <a>Builder</a> must not
--   be reused after this operation.
freeze :: Builder s a -> ST s (Chunks a)


-- | Builder with cheap concatenation. Like the builder type from
--   <tt>Data.Builder.ST</tt>, this builder can be stored somewhere and
--   this used again later. However, this builder type has several
--   advantages:
--   
--   <ul>
--   <li>Supports both cons and snoc (<tt>Data.Builder.ST</tt> only
--   supports snoc)</li>
--   <li>No linear-use restriction</li>
--   <li>Extremely cheap concatenation (not supported by
--   <tt>Data.Builder.ST</tt> at all)</li>
--   </ul>
--   
--   In exchange for all of these, this implementation trades performance.
--   Performance is degraded for two reasons:
--   
--   <ul>
--   <li>Evaluation of the builder is deferred, and the evaluation requires
--   walking a tree of nodes.</li>
--   <li>This builder stores individual elements rather than chunks. There
--   is no fundamental reason for this. It is possible to store a
--   SmallArray in each Cons and Snoc instead, but this makes the
--   implementation a little more simple.</li>
--   </ul>
--   
--   One reason to prefer this module instead of <tt>Data.Builder.ST</tt>
--   is that this module lets the user works with builder in a more
--   monoidal style rather than a stateful style. Consider a data type with
--   several fields that is being converted to a builder. Here,
--   <tt>Data.Builder.ST</tt> would require that <tt>Builder</tt> appear as
--   both an argument and an result for each field's encode function. The
--   linearly-used builder must be threaded through by hand or by clever
--   use of <tt>StateT</tt>. With <tt>Data.Builder.Catenable</tt>, the
--   encode functions only need return the builder.
module Data.Builder.Catenable
data Builder a
Empty :: Builder a
Cons :: a -> !Builder a -> Builder a
Snoc :: !Builder a -> a -> Builder a
Append :: !Builder a -> !Builder a -> Builder a
pattern (:<) :: a -> Builder a -> Builder a
infixr 5 :<
pattern (:>) :: Builder a -> a -> Builder a
infixl 5 :>
run :: Builder a -> Chunks a
instance GHC.Base.Monoid (Data.Builder.Catenable.Builder a)
instance GHC.Base.Semigroup (Data.Builder.Catenable.Builder a)
instance GHC.Exts.IsList (Data.Builder.Catenable.Builder a)