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


-- | Lists, Texts, ByteStrings and Vectors of statically known length
--   
--   static-text provides type-level safety for basic operations on
--   string-like types (finite lists of elements), such as Data.Text,
--   String (and all lists), Data.ByteString and Data.Vector. Use it when
--   you need static guarantee on lengths of strings produced in your code.
@package static-text
@version 0.2.0.3


-- | Use this module when you need to add an <a>IsStaticText</a> instance
--   to a type.
module Data.StaticText.Class

-- | Class of types which can be assigned a type-level length.
class IsStaticText a where {
    data family Static a (i :: Nat);
    type family Elem a;
}

-- | Simply wrap a value in a Static as is, assuming any length.
--   
--   <b>WARNING</b> Use it only when you know what you're doing.
--   
--   For example, an expression like
--   
--   <pre>
--   unsafeCreate "somestring" :: Static String 50
--   </pre>
--   
--   will typecheck, although the stored length information will not match
--   actual string size. This may result in wrong behaviour of all
--   functions defined for <a>IsStaticText</a>.
--   
--   When writing new <a>IsStaticText</a> instances, make this simply apply
--   the constructor of <a>Static</a>.
unsafeCreate :: IsStaticText a => a -> Static a i

-- | Forget type-level length, obtaining the underlying value.
unwrap :: IsStaticText a => Static a i -> a
length :: IsStaticText a => a -> Int
append :: IsStaticText a => a -> a -> a
replicate :: IsStaticText a => Int -> Elem a -> a
map :: IsStaticText a => (Elem a -> Elem a) -> a -> a
take :: IsStaticText a => Int -> a -> a
drop :: IsStaticText a => Int -> a -> a
instance GHC.Classes.Ord a => GHC.Classes.Ord (Data.StaticText.Class.Static [a] i)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Data.StaticText.Class.Static [a] i)
instance GHC.Classes.Ord (Data.StaticText.Class.Static Data.Text.Internal.Text i)
instance GHC.Classes.Eq (Data.StaticText.Class.Static Data.Text.Internal.Text i)
instance GHC.Classes.Ord (Data.StaticText.Class.Static Data.ByteString.Internal.ByteString i)
instance GHC.Classes.Eq (Data.StaticText.Class.Static Data.ByteString.Internal.ByteString i)
instance GHC.Classes.Ord (Data.StaticText.Class.Static Data.ByteString.Short.Internal.ShortByteString i)
instance GHC.Classes.Eq (Data.StaticText.Class.Static Data.ByteString.Short.Internal.ShortByteString i)
instance GHC.Classes.Ord a => GHC.Classes.Ord (Data.StaticText.Class.Static (Data.Vector.Vector a) i)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Data.StaticText.Class.Static (Data.Vector.Vector a) i)
instance (GHC.Show.Show a, Data.StaticText.Class.IsStaticText a) => GHC.Show.Show (Data.StaticText.Class.Static a i)
instance Data.StaticText.Class.IsStaticText [a]
instance Data.StaticText.Class.IsStaticText Data.Text.Internal.Text
instance Data.StaticText.Class.IsStaticText Data.ByteString.Internal.ByteString
instance Data.StaticText.Class.IsStaticText Data.ByteString.Short.Internal.ShortByteString
instance Data.StaticText.Class.IsStaticText (Data.Vector.Vector a)


-- | Template Haskell helpers for StaticText.
module Data.StaticText.TH

-- | Type-safe Static constructor macro for string literals.
--   
--   Example:
--   
--   <pre>
--   $(st "Foobar")
--   </pre>
--   
--   compiles to
--   
--   <pre>
--   unsafeCreate "Foobar" :: forall a. (IsString a, IsStaticText a) =&gt; Static a 6
--   </pre>
--   
--   where 6 is the string length obtained at compile time.
st :: LitS -> Q Exp
instance Data.String.IsString Data.StaticText.TH.LitS


-- | static-text combinators are defined for members of <a>IsStaticText</a>
--   class. The package includes <a>IsStaticText</a> instances for several
--   common types.
--   
--   This module is meant to be imported qualifed, e.g.
--   
--   <pre>
--   import qualified Data.StaticText as S
--   </pre>
module Data.StaticText

-- | Safely create a Static, possibly altering the source to match target
--   length. If target length is less than that of the source, the source
--   gets truncated. If target length is greater, the source is padded
--   using the provided basic element. Elements on the left are preferred.
--   
--   <pre>
--   &gt;&gt;&gt; createLeft ' ' "foobarbaz" :: Static String 6
--   "foobar"
--   
--   &gt;&gt;&gt; createLeft '#' "foobarbaz" :: Static String 12
--   "foobarbaz###"
--   </pre>
createLeft :: forall a i. (IsStaticText a, KnownNat i) => Elem a -> a -> Static a i

-- | Just like <a>createLeft</a>, except that elements on the right are
--   preferred.
--   
--   <pre>
--   &gt;&gt;&gt; createRight '@' "foobarbaz" :: Static String 6
--   "barbaz"
--   
--   &gt;&gt;&gt; createRight '!' "foobarbaz" :: Static String 12
--   "!!!foobarbaz"
--   </pre>
createRight :: forall a i. (IsStaticText a, KnownNat i) => Elem a -> a -> Static a i

-- | Type-safe Static constructor macro for string literals.
--   
--   Example:
--   
--   <pre>
--   $(st "Foobar")
--   </pre>
--   
--   compiles to
--   
--   <pre>
--   unsafeCreate "Foobar" :: forall a. (IsString a, IsStaticText a) =&gt; Static a 6
--   </pre>
--   
--   where 6 is the string length obtained at compile time.
st :: LitS -> Q Exp

-- | Attempt to safely create a Static if it matches target length.
--   
--   <pre>
--   &gt;&gt;&gt; create "foobar" :: Maybe (Static String 6)
--   Just "foobar"
--   
--   &gt;&gt;&gt; create "barbaz" :: Maybe (Static String 8)
--   Nothing
--   </pre>
--   
--   This is safer than <a>unsafeCreate</a> and unlike with
--   <a>createLeft</a> / <a>createRight</a> the source value is left
--   unchanged. However, this implies a further run-time check for Nothing
--   values.
create :: forall a i. (IsStaticText a, KnownNat i) => a -> Maybe (Static a i)

-- | Construct a new Static from a basic element.
--   
--   <pre>
--   &gt;&gt;&gt; replicate '=' :: Static String 10
--   "=========="
--   </pre>
replicate :: forall a i. (IsStaticText a, KnownNat i) => Elem a -> Static a i

-- | Append two Statics together.
--   
--   <pre>
--   &gt;&gt;&gt; append $(st "foo") $(st "bar") :: Static String 6
--   "foobar"
--   </pre>
append :: forall a m n. (IsStaticText a) => Static a m -> Static a n -> Static a (m + n)

-- | Reduce Static length, preferring elements on the left.
--   
--   <pre>
--   &gt;&gt;&gt; take $(st "Foobar") :: Static String 3
--   "Foo"
--   </pre>
take :: forall a m n. (IsStaticText a, KnownNat m, KnownNat n, n <= m) => Static a m -> Static a n

-- | Reduce Static length, preferring elements on the right.
--   
--   <pre>
--   &gt;&gt;&gt; drop $(st "Foobar") :: Static String 2
--   "ar"
--   </pre>
drop :: forall a m n. (IsStaticText a, KnownNat m, KnownNat n, n <= m) => Static a m -> Static a n

-- | Map a Static to a Static of the same length.
--   
--   <pre>
--   &gt;&gt;&gt; map toUpper $(st "Hello") :: Static String 5
--   "HELLO"
--   </pre>
map :: IsStaticText a => (Elem a -> Elem a) -> Static a m -> Static a m

-- | Fill a Static with extra elements up to target length, padding
--   original elements to the left.
padLeft :: forall a m n. (IsStaticText a, KnownNat m, KnownNat (n - m), n ~ (n - m + m), m <= n) => Elem a -> Static a m -> Static a n

-- | Like <a>padLeft</a>, but original elements are padded to the right.
padRight :: forall a m n. (IsStaticText a, KnownNat m, KnownNat (n - m), n ~ (m + (n - m)), m <= n) => Elem a -> Static a m -> Static a n

-- | Obtain value-level length.
length :: forall a m. KnownNat m => Static a m -> Int

-- | Data family which wraps values of the underlying type giving them a
--   type-level length. <tt>Static t 6</tt> means a value of type
--   <tt>t</tt> of length 6.

-- | Class of types which can be assigned a type-level length.
class IsStaticText a where {
    type family Elem a;
}

-- | Simply wrap a value in a Static as is, assuming any length.
--   
--   <b>WARNING</b> Use it only when you know what you're doing.
--   
--   For example, an expression like
--   
--   <pre>
--   unsafeCreate "somestring" :: Static String 50
--   </pre>
--   
--   will typecheck, although the stored length information will not match
--   actual string size. This may result in wrong behaviour of all
--   functions defined for <a>IsStaticText</a>.
--   
--   When writing new <a>IsStaticText</a> instances, make this simply apply
--   the constructor of <a>Static</a>.
unsafeCreate :: IsStaticText a => a -> Static a i

-- | Forget type-level length, obtaining the underlying value.
unwrap :: IsStaticText a => Static a i -> a