-- 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


-- | 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.
--   
--   For example, an expression like
--   
--   <pre>
--   unsafeCreate "somestring" :: Static 50 String
--   </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 Static.
--   
--   Use it only when you know what you're doing.
--   
--   When implementing new IsStaticText instances, code this to simply
--   apply the constructor of <tt>StaticText</tt>.
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 StaticText constructor macro for string literals.
--   
--   Example:
--   
--   <pre>
--   $(st "Foobar")
--   </pre>
--   
--   compiles to
--   
--   <pre>
--   unsafeCreate "Foobar" :: forall a. (IsString a, IsStaticText a) =&gt; StaticText 6 a
--   </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 provides type-level safety for basic operations on
--   string-like types (finite lists of elements), such as
--   <a>Data.Text</a>, <a>String</a> (and all lists),
--   <a>Data.ByteString</a> and <a>Data.Vector</a>. Use it when you need
--   static guarantee on lengths of strings produced in your code.
--   
--   An example application would be a network exchange protocol built of
--   packets with fixed-width fields:
--   
--   <pre>
--   {-# LANGUAGE DataKinds #-}
--   {-# LANGUAGE OverloadedStrings #-}
--   {-# LANGUAGE TemplateHaskell #-}
--   </pre>
--   
--   <pre>
--   import Data.StaticText
--   
--   mkPacket :: ByteString -&gt; Static 32 ByteString
--   mkPacket inp =
--     -- 5-character version signature
--     $(st "PKT10") `append`
--     -- 25-character payload
--     payload `append`
--     -- 2-character payload checksum
--     checksum
--     where
--       payload = createLeft 0x20 inp
--       checksum :: Static 2 ByteString
--       checksum = createLeft 0x20 $
--                  pack $ show $ Data.Static.length payload `mod` 100
--   
--   message :: Static 64 ByteString
--   message = mkPacket "Hello" `append` mkPacket "world"
--   </pre>
--   
--   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 StaticText constructor macro for string literals.
--   
--   Example:
--   
--   <pre>
--   $(st "Foobar")
--   </pre>
--   
--   compiles to
--   
--   <pre>
--   unsafeCreate "Foobar" :: forall a. (IsString a, IsStaticText a) =&gt; StaticText 6 a
--   </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

-- | 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.
--   
--   For example, an expression like
--   
--   <pre>
--   unsafeCreate "somestring" :: Static 50 String
--   </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 Static.
--   
--   Use it only when you know what you're doing.
--   
--   When implementing new IsStaticText instances, code this to simply
--   apply the constructor of <tt>StaticText</tt>.
unsafeCreate :: IsStaticText a => a -> Static a i

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