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


-- | Builders for arrays
--   
--   Builders for arrays
@package array-builder
@version 0.1.1.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)

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)