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


-- | RFC 4648-compliant Base16 encodings and decodings. This library
--   provides performant encoding and decoding primitives, as well as
--   support for textual values.
@package base16
@version 2.0


-- | This module contains the opaque <a>Base16</a> type and combinators for
--   working with Base16-encoded values.
module Data.Base16.Types

-- | Wrap a value that is or is intended to be Base16-encoded.
--   
--   Use the <tt>parseBase16</tt> function in the corresponding ByteString
--   or Text module to validate external input. Encoding functions also
--   produce this wrapper. <a>assertBase16</a> and the <a>Functor</a>,
--   <a>Applicative</a>, and <a>Monad</a> instances do not validate their
--   results.
data Base16 a

-- | Assert the provenance of a value.
--   
--   For untrusted input, use the <tt>parseBase16</tt> function in the
--   corresponding ByteString or Text module to validate it first.
--   
--   <i>Warning</i>: This is a blind assertion that a particular value is
--   base16 encoded in some alphabet. If you are not sure of the provenance
--   of the value, you may experience odd behavior when attempting to
--   decode. Use at your own risk. If I see any issues logged on this
--   project from negligent use of this, Sofia and I will smite you.
assertBase16 :: a -> Base16 a

-- | Forget that a particular value is Base16-encoded
extractBase16 :: Base16 a -> a
instance GHC.Internal.Base.Applicative Data.Base16.Types.Base16
instance Data.Functor.Classes.Eq1 Data.Base16.Types.Base16
instance GHC.Classes.Eq a => GHC.Classes.Eq (Data.Base16.Types.Base16 a)
instance GHC.Internal.Base.Functor Data.Base16.Types.Base16
instance GHC.Internal.Base.Monad Data.Base16.Types.Base16
instance Control.DeepSeq.NFData a => Control.DeepSeq.NFData (Data.Base16.Types.Base16 a)
instance Data.Functor.Classes.Ord1 Data.Base16.Types.Base16
instance GHC.Classes.Ord a => GHC.Classes.Ord (Data.Base16.Types.Base16 a)
instance GHC.Internal.Show.Show a => GHC.Internal.Show.Show (Data.Base16.Types.Base16 a)

module Data.ByteString.Base16.Internal.Utils

-- | Read <a>Word8</a> index off alphabet addr
aix :: Word8 -> Addr# -> Word8

-- | Form a list of chunks, and rechunk the list of bytestrings into length
--   multiples of 2
reChunk :: [ByteString] -> [ByteString]

-- | Write a byte array directly to Short bytestring
runShortST :: (forall s. () => ST s ByteArray) -> ShortByteString

-- | Used for writing <a>ByteArray#</a>-based encodes
runDecodeST :: (forall s. () => ST s (Either Text ByteArray)) -> Either Text ShortByteString
runDecodeST' :: (forall s. () => ST s ByteArray) -> ShortByteString


-- | Encoding loop optimized for <a>Word16</a> architectures
module Data.ByteString.Base16.Internal.W16.Loop

-- | Hex encoding inner loop optimized for 16-bit architectures
innerLoop :: Ptr Word8 -> Ptr Word8 -> Ptr Word8 -> IO ()

-- | Hex decoding loop optimized for 16-bit architectures
decodeLoop :: ForeignPtr Word8 -> Ptr Word8 -> Ptr Word8 -> Ptr Word8 -> Int -> IO (Either Text ByteString)

-- | Hex decoding loop optimized for 16-bit architectures
decodeLoopTyped :: Ptr Word8 -> Ptr Word8 -> Ptr Word8 -> IO ()

-- | Lenient lazy hex decoding loop optimized for 16-bit architectures.
--   When the <a>Right</a> case is returned, a byte
lenientLoop :: ForeignPtr Word8 -> Ptr Word8 -> Ptr Word8 -> Ptr Word8 -> Int -> IO ByteString

module Data.ByteString.Base16.Internal.W16.ShortLoop
innerLoop :: Int -> MutableByteArray s -> ByteArray -> ST s ()
decodeLoop :: Int -> MutableByteArray s -> ByteArray -> ST s (Either Text ByteArray)
decodeLoopTyped :: Int -> MutableByteArray s -> ByteArray -> ST s ByteArray
lenientLoop :: Int -> MutableByteArray s -> ByteArray -> ST s Int

module Data.ByteString.Base16.Internal.Head

-- | Head of the base16 encoding loop - marshal data, assemble loops
encodeBase16_ :: ByteString -> ByteString
decodeBase16_ :: ByteString -> Either Text ByteString
decodeBase16Typed_ :: Base16 ByteString -> ByteString
decodeBase16Lenient_ :: ByteString -> ByteString
encodeBase16Short_ :: ShortByteString -> ShortByteString
decodeBase16Short_ :: ShortByteString -> Either Text ShortByteString
decodeBase16ShortTyped_ :: Base16 ShortByteString -> ShortByteString
decodeBase16ShortLenient_ :: ShortByteString -> ShortByteString


-- | This module contains <a>ByteString</a>-valued combinators for
--   implementing the RFC 4648 specification of the Base16 encoding format.
--   This includes lenient decoding variants, as well as internal and
--   external validation for canonicity.
module Data.ByteString.Base16

-- | Encode a <a>ByteString</a> value as Base16 <a>Text</a>
--   
--   See: <a>RFC-4648 section 8</a>
--   
--   <h3><b>Examples</b>:</h3>
--   
--   <pre>
--   &gt;&gt;&gt; encodeBase16 "Sun"
--   "53756e"
--   </pre>
encodeBase16 :: ByteString -> Base16 Text

-- | Encode a <a>ByteString</a> value as a Base16 <a>ByteString</a> value
--   
--   See: <a>RFC-4648 section 8</a>
--   
--   <h3><b>Examples</b>:</h3>
--   
--   <pre>
--   &gt;&gt;&gt; encodeBase16' "Sun"
--   "53756e"
--   </pre>
encodeBase16' :: ByteString -> Base16 ByteString

-- | Decode a Base16-encoded <a>ByteString</a> value.
--   
--   See: <a>RFC-4648 section 8</a>
--   
--   <h3><b>Examples</b>:</h3>
--   
--   <pre>
--   &gt;&gt;&gt; decodeBase16 $ assertBase16 "53756e"
--   "Sun"
--   </pre>
decodeBase16 :: Base16 ByteString -> ByteString

-- | Decode Base16 <a>Text</a>.
--   
--   See: <a>RFC-4648 section 8</a>
--   
--   <h3><b>Examples</b>:</h3>
--   
--   <pre>
--   &gt;&gt;&gt; decodeBase16' $ assertBase16 "53756e"
--   "Sun"
--   </pre>
decodeBase16' :: Base16 Text -> ByteString

-- | Decode an untyped Base16-encoded <a>ByteString</a> value with
--   error-checking.
--   
--   See: <a>RFC-4648 section 8</a>
--   
--   <h3><b>Examples</b>:</h3>
--   
--   <pre>
--   &gt;&gt;&gt; decodeBase16Untyped "53756e"
--   Right "Sun"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; decodeBase16Untyped "6x"
--   Left "invalid character at offset: 1"
--   </pre>
decodeBase16Untyped :: ByteString -> Either Text ByteString

-- | Decode a Base16-encoded <a>ByteString</a> value leniently, using a
--   strategy that never fails
--   
--   N.B.: this is not RFC 4648-compliant
--   
--   <h3><b>Examples</b>:</h3>
--   
--   <pre>
--   &gt;&gt;&gt; decodeBase16Lenient "53756e"
--   "Sun"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; decodeBase16Lenient "6x6x"
--   "f"
--   </pre>
decodeBase16Lenient :: ByteString -> ByteString

-- | Validate an untyped Base16 value and retain its encoded
--   representation.
--   
--   Accepts even-length ASCII hexadecimal input, including upper-case and
--   mixed-case digits. Empty input is valid. The original input is
--   preserved, and errors match <a>decodeBase16Untyped</a>.
--   
--   <h3><b>Examples</b>:</h3>
--   
--   <pre>
--   &gt;&gt;&gt; parseBase16 "666f6"
--   Left "invalid bytestring size"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; parseBase16 "666F"
--   Right "666F"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; fmap decodeBase16 (parseBase16 "666F")
--   Right "fo"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; parseBase16 "6x"
--   Left "invalid character at offset: 1"
--   </pre>
parseBase16 :: ByteString -> Either Text (Base16 ByteString)


-- | This module contains <a>ByteString</a>-valued combinators for
--   implementing the RFC 4648 specification of the Base16 encoding format.
--   This includes lenient decoding variants, as well as internal and
--   external validation for canonicity.
module Data.ByteString.Lazy.Base16

-- | Encode a lazy <a>ByteString</a> value as Base16 <a>Text</a>
--   
--   See: <a>RFC-4648 section 8</a>
--   
--   <h3><b>Examples</b>:</h3>
--   
--   <pre>
--   &gt;&gt;&gt; encodeBase16 "Sun"
--   "53756e"
--   </pre>
encodeBase16 :: ByteString -> Base16 Text

-- | Encode a lazy <a>ByteString</a> value as a Base16 <a>ByteString</a>
--   value
--   
--   See: <a>RFC-4648 section 8</a>
--   
--   <h3><b>Examples</b>:</h3>
--   
--   <pre>
--   &gt;&gt;&gt; encodeBase16' "Sun"
--   "53756e"
--   </pre>
encodeBase16' :: ByteString -> Base16 ByteString

-- | Decode a Base16-encoded lazy <a>ByteString</a> value.
--   
--   Hexadecimal byte pairs may cross chunk boundaries. Decoding remains
--   lazy in the input chunks.
--   
--   See: <a>RFC-4648 section 8</a>
--   
--   <h3><b>Examples</b>:</h3>
--   
--   <pre>
--   &gt;&gt;&gt; decodeBase16 $ assertBase16 "53756e"
--   "Sun"
--   </pre>
decodeBase16 :: Base16 ByteString -> ByteString

-- | Decode a Base16-encoded <a>Text</a> value.
--   
--   See: <a>RFC-4648 section 8</a>
--   
--   <h3><b>Examples</b>:</h3>
--   
--   <pre>
--   &gt;&gt;&gt; decodeBase16' $ assertBase16 "53756e"
--   "Sun"
--   </pre>
decodeBase16' :: Base16 Text -> ByteString

-- | Decode an untyped Base16-encoded lazy <a>ByteString</a> value.
--   
--   Checks the whole input, joining chunks before decoding so that lengths
--   and error offsets refer to the complete encoded value.
--   
--   See: <a>RFC-4648 section 8</a>
--   
--   <h3><b>Examples</b>:</h3>
--   
--   <pre>
--   &gt;&gt;&gt; decodeBase16Untyped "53756e"
--   Right "Sun"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; decodeBase16Untyped "6x"
--   Left "invalid character at offset: 1"
--   </pre>
decodeBase16Untyped :: ByteString -> Either Text ByteString

-- | Decode an untyped Base16-encoded <a>ByteString</a> value leniently,
--   using a strategy that never fails
--   
--   N.B.: this is not RFC 4648-compliant. It may give you garbage if
--   you're not careful!
--   
--   <h3><b>Examples</b>:</h3>
--   
--   <pre>
--   &gt;&gt;&gt; decodeBase16Lenient "53756e"
--   "Sun"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; decodeBase16Lenient "6x6x"
--   "f"
--   </pre>
decodeBase16Lenient :: ByteString -> ByteString

-- | Validate an untyped Base16 value and retain its encoded
--   representation.
--   
--   Accepts even-length ASCII hexadecimal input, including upper-case and
--   mixed-case digits. Empty input is valid. The original input is
--   preserved, and errors match <a>decodeBase16Untyped</a>.
--   
--   The whole input is validated before returning <a>Right</a>, regardless
--   of chunk boundaries. The returned wrapper preserves those boundaries.
--   
--   <h3><b>Examples</b>:</h3>
--   
--   <pre>
--   &gt;&gt;&gt; parseBase16 "666f6"
--   Left "invalid bytestring size"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; parseBase16 "666F"
--   Right "666F"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; fmap decodeBase16 (parseBase16 "666F")
--   Right "fo"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; parseBase16 "6x"
--   Left "invalid character at offset: 1"
--   </pre>
parseBase16 :: ByteString -> Either Text (Base16 ByteString)


-- | This module contains <a>ShortByteString</a>-valued combinators for
--   implementing the RFC 4648 specification of the Base16 encoding format.
--   This includes lenient decoding variants, as well as internal and
--   external validation for canonicity.
module Data.ByteString.Short.Base16

-- | Encode a <a>ShortByteString</a> value as Base16 <a>ShortText</a>
--   
--   See: <a>RFC-4648 section 8</a>
--   
--   <h3><b>Examples</b>:</h3>
--   
--   <pre>
--   &gt;&gt;&gt; encodeBase16 "Sun"
--   "53756e"
--   </pre>
encodeBase16 :: ShortByteString -> Base16 ShortText

-- | Encode a <a>ShortByteString</a> value as a Base16
--   <a>ShortByteString</a> value
--   
--   See: <a>RFC-4648 section 8</a>
--   
--   <h3><b>Examples</b>:</h3>
--   
--   <pre>
--   &gt;&gt;&gt; encodeBase16' "Sun"
--   "53756e"
--   </pre>
encodeBase16' :: ShortByteString -> Base16 ShortByteString

-- | Decode a Base16-encoded <a>ShortByteString</a> value.
--   
--   See: <a>RFC-4648 section 8</a>
--   
--   <h3><b>Examples</b>:</h3>
--   
--   <pre>
--   &gt;&gt;&gt; decodeBase16 $ assertBase16 "53756e"
--   "Sun"
--   </pre>
decodeBase16 :: Base16 ShortByteString -> ShortByteString

-- | Decode Base16-encoded <a>ShortText</a> value.
--   
--   See: <a>RFC-4648 section 8</a>
--   
--   <h3><b>Examples</b>:</h3>
--   
--   <pre>
--   &gt;&gt;&gt; decodeBase16' $ assertBase16 "53756e"
--   "Sun"
--   </pre>
decodeBase16' :: Base16 ShortText -> ShortByteString

-- | Decode an untyped Base16-encoded <tt>ByteString</tt> value with
--   error-checking.
--   
--   See: <a>RFC-4648 section 8</a>
--   
--   <h3><b>Examples</b>:</h3>
--   
--   <pre>
--   &gt;&gt;&gt; decodeBase16Untyped "53756e"
--   Right "Sun"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; decodeBase16Untyped "6x"
--   Left "invalid character at offset: 1"
--   </pre>
decodeBase16Untyped :: ShortByteString -> Either Text ShortByteString

-- | Decode an untyped Base16-encoded <a>ShortByteString</a> value
--   leniently, using a strategy that never fails
--   
--   N.B.: this is not RFC 4648-compliant
--   
--   <h3><b>Examples</b>:</h3>
--   
--   <pre>
--   &gt;&gt;&gt; decodeBase16Lenient "53756e"
--   "Sun"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; decodeBase16Lenient "6x6x"
--   "f"
--   </pre>
decodeBase16Lenient :: ShortByteString -> ShortByteString

-- | Validate an untyped Base16 value and retain its encoded
--   representation.
--   
--   Accepts even-length ASCII hexadecimal input, including upper-case and
--   mixed-case digits. Empty input is valid. The original input is
--   preserved, and errors match <a>decodeBase16Untyped</a>.
--   
--   <h3><b>Examples</b>:</h3>
--   
--   <pre>
--   &gt;&gt;&gt; parseBase16 "666f6"
--   Left "invalid bytestring size"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; parseBase16 "666F"
--   Right "666F"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; fmap decodeBase16 (parseBase16 "666F")
--   Right "fo"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; parseBase16 "6x"
--   Left "invalid character at offset: 1"
--   </pre>
parseBase16 :: ShortByteString -> Either Text (Base16 ShortByteString)


-- | This module contains the error types raised in the decoding process.
module Data.Text.Encoding.Base16.Error

-- | This data type represents the type of decoding errors of various kinds
--   as they pertain to decoding <a>Text</a> values. Namely, to distinguish
--   between decoding errors from opaque unicode exceptions caught in the
--   unicode decoding process.
data Base16Error e

-- | The error associated with decoding failure as a result of the Base16
--   decoding process
DecodeError :: Text -> Base16Error e

-- | The error associated with the decoding failure as a result of the
--   conversion process
ConversionError :: e -> Base16Error e
instance GHC.Classes.Eq e => GHC.Classes.Eq (Data.Text.Encoding.Base16.Error.Base16Error e)
instance GHC.Internal.Exception.Type.Exception e => GHC.Internal.Exception.Type.Exception (Data.Text.Encoding.Base16.Error.Base16Error e)
instance GHC.Internal.Generics.Generic (Data.Text.Encoding.Base16.Error.Base16Error e)
instance Control.DeepSeq.NFData e => Control.DeepSeq.NFData (Data.Text.Encoding.Base16.Error.Base16Error e)
instance GHC.Internal.Show.Show e => GHC.Internal.Show.Show (Data.Text.Encoding.Base16.Error.Base16Error e)


-- | This module contains <a>Text</a>-valued combinators for implementing
--   the RFC 4648 specification of the Base16 encoding format. This
--   includes lenient decoding variants, as well as internal and external
--   validation for canonicity.
module Data.Text.Encoding.Base16

-- | Encode a <a>Text</a> value in Base16.
--   
--   See: <a>RFC-4648 section 8</a>
--   
--   <h3><b>Examples</b>:</h3>
--   
--   <pre>
--   &gt;&gt;&gt; encodeBase16 "Sun"
--   "53756e"
--   </pre>
encodeBase16 :: Text -> Base16 Text

-- | Decode a Base16-encoded <a>Text</a> value.
--   
--   See: <a>RFC-4648 section 8</a>
--   
--   <h3><b>Examples</b>:</h3>
--   
--   <pre>
--   &gt;&gt;&gt; decodeBase16 $ assertBase16 "53756e"
--   "Sun"
--   </pre>
decodeBase16 :: Base16 Text -> Text

-- | Decode an untyped Base16-encoded <a>Text</a> value.
--   
--   See: <a>RFC-4648 section 8</a>
--   
--   <h3><b>Examples</b>:</h3>
--   
--   <pre>
--   &gt;&gt;&gt; decodeBase16Untyped "53756e"
--   Right "Sun"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; decodeBase16Untyped "6x"
--   Left "invalid character at offset: 1"
--   </pre>
decodeBase16Untyped :: Text -> Either Text Text

-- | Attempt to decode an untyped <a>Text</a> value as Base16, converting
--   from <a>ByteString</a> to <a>Text</a> according to some encoding
--   function. In practice, This is something like <a>decodeUtf8'</a>,
--   which may produce an error.
--   
--   See: <a>RFC-4648 section 8</a>
--   
--   <h3><b>Example</b>:</h3>
--   
--   <pre>
--   <a>decodeBase16With</a> <a>decodeUtf8'</a>
--     :: <a>ByteString</a> -&gt; <a>Either</a> (<a>Base16Error</a> <tt>UnicodeException</tt>) <a>Text</a>
--   </pre>
decodeBase16With :: (ByteString -> Either err Text) -> ByteString -> Either (Base16Error err) Text

-- | Decode an untyped Base16-encoded <a>Text</a> value leniently.
--   
--   Non-hexadecimal characters and a final unpaired hex digit are ignored.
--   Valid UTF-8 sequences in the decoded bytes are preserved. Each invalid
--   UTF-8 byte is interpreted as its Latin-1 character (U+0000 through
--   U+00FF), so malformed input does not raise Unicode exceptions.
--   
--   N.B.: this is not RFC 4648-compliant.
--   
--   <h3><b>Examples</b>:</h3>
--   
--   <pre>
--   &gt;&gt;&gt; decodeBase16Lenient "53756e"
--   "Sun"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; decodeBase16Lenient "6x6x"
--   "f"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; decodeBase16Lenient "df" == "\223"
--   True
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; decodeBase16Lenient "c39f" == "\223"
--   True
--   </pre>
decodeBase16Lenient :: Text -> Text

-- | Validate an untyped Base16 value and retain its encoded
--   representation.
--   
--   Accepts even-length ASCII hexadecimal input, including upper-case and
--   mixed-case digits. Empty input is valid. The original input is
--   preserved, and errors match <a>decodeBase16Untyped</a>.
--   
--   This validates the Base16 encoding, not the UTF-8 validity of its
--   decoded payload. Use <a>decodeBase16With</a> with a checked conversion
--   for text decoding.
--   
--   <h3><b>Examples</b>:</h3>
--   
--   <pre>
--   &gt;&gt;&gt; parseBase16 "666f6"
--   Left "invalid bytestring size"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; parseBase16 "666F"
--   Right "666F"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; fmap decodeBase16 (parseBase16 "666F")
--   Right "fo"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; parseBase16 "6x"
--   Left "invalid character at offset: 1"
--   </pre>
parseBase16 :: Text -> Either Text (Base16 Text)


-- | This module contains <a>Text</a>-valued combinators for implementing
--   the RFC 4648 specification of the Base16 encoding format. This
--   includes lenient decoding variants, as well as internal and external
--   validation for canonicity.
module Data.Text.Lazy.Encoding.Base16

-- | Encode a lazy <a>Text</a> value in Base16.
--   
--   See: <a>RFC-4648 section 8</a>
--   
--   <h3><b>Examples</b>:</h3>
--   
--   <pre>
--   &gt;&gt;&gt; encodeBase16 "Sun"
--   "53756e"
--   </pre>
encodeBase16 :: Text -> Base16 Text

-- | Decode a Base16-encoded lazy <a>Text</a> value.
--   
--   See: <a>RFC-4648 section 8</a>
--   
--   <h3><b>Examples</b>:</h3>
--   
--   <pre>
--   &gt;&gt;&gt; decodeBase16 $ assertBase16 "53756e"
--   "Sun"
--   </pre>
decodeBase16 :: Base16 Text -> Text

-- | Decode an untyped Base16-encoded lazy <a>Text</a> value.
--   
--   See: <a>RFC-4648 section 8</a>
--   
--   <h3><b>Examples</b>:</h3>
--   
--   <pre>
--   &gt;&gt;&gt; decodeBase16Untyped "53756e"
--   Right "Sun"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; decodeBase16Untyped "6x"
--   Left "invalid character at offset: 1"
--   </pre>
decodeBase16Untyped :: Text -> Either Text Text

-- | Attempt to decode an untyped lazy <a>Text</a> value as Base16,
--   converting from <a>ByteString</a> to <a>Text</a> according to some
--   encoding function. In practice, This is something like
--   <a>decodeUtf8'</a>, which may produce an error.
--   
--   See: <a>RFC-4648 section 8</a>
--   
--   <pre>
--   <a>decodeBase16With</a> <a>decodeUtf8'</a>
--     :: <a>ByteString</a> -&gt; <a>Either</a> (<a>Base16Error</a> <tt>UnicodeException</tt>) <a>Text</a>
--   </pre>
decodeBase16With :: (ByteString -> Either err Text) -> ByteString -> Either (Base16Error err) Text

-- | Decode a Base16-encoded lazy <a>Text</a> value leniently.
--   
--   Non-hexadecimal characters and a final unpaired hex digit are ignored.
--   Valid UTF-8 sequences are preserved, including across chunk
--   boundaries. Each invalid UTF-8 byte is interpreted as its Latin-1
--   character (U+0000 through U+00FF), so malformed input does not raise
--   Unicode exceptions. Decoding remains lazy in the input chunks.
--   
--   N.B.: this is not RFC 4648-compliant.
--   
--   <h3><b>Examples</b>:</h3>
--   
--   <pre>
--   &gt;&gt;&gt; decodeBase16Lenient "53756e"
--   "Sun"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; decodeBase16Lenient "6x6x"
--   "f"
--   </pre>
decodeBase16Lenient :: Text -> Text

-- | Validate an untyped Base16 value and retain its encoded
--   representation.
--   
--   Accepts even-length ASCII hexadecimal input, including upper-case and
--   mixed-case digits. Empty input is valid. The original input is
--   preserved, and errors match <a>decodeBase16Untyped</a>.
--   
--   The whole input is validated before returning <a>Right</a>, regardless
--   of chunk boundaries. The returned wrapper preserves those boundaries.
--   
--   This validates the Base16 encoding, not the UTF-8 validity of its
--   decoded payload. Use <a>decodeBase16With</a> with a checked conversion
--   for text decoding.
--   
--   <h3><b>Examples</b>:</h3>
--   
--   <pre>
--   &gt;&gt;&gt; parseBase16 "666f6"
--   Left "invalid bytestring size"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; parseBase16 "666F"
--   Right "666F"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; fmap decodeBase16 (parseBase16 "666F")
--   Right "fo"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; parseBase16 "6x"
--   Left "invalid character at offset: 1"
--   </pre>
parseBase16 :: Text -> Either Text (Base16 Text)


-- | This module contains <a>ShortText</a>-valued combinators for
--   implementing the RFC 4648 specification of the Base16 encoding format.
--   This includes lenient decoding variants, as well as internal and
--   external validation for canonicity.
module Data.Text.Short.Encoding.Base16

-- | Encode a <a>ShortText</a> value in Base16.
--   
--   See: <a>RFC-4648 section 8</a>
--   
--   <h3><b>Examples</b>:</h3>
--   
--   <pre>
--   &gt;&gt;&gt; encodeBase16 "Sun"
--   "53756e"
--   </pre>
encodeBase16 :: ShortText -> Base16 ShortText

-- | Decode a Base16-encoded <a>ShortText</a> value.
--   
--   See: <a>RFC-4648 section 8</a>
--   
--   <h3><b>Examples</b>:</h3>
--   
--   <pre>
--   &gt;&gt;&gt; decodeBase16 $ assertBase16 "53756e"
--   "Sun"
--   </pre>
decodeBase16 :: Base16 ShortText -> ShortText

-- | Decode an untyped Base16-encoded <a>ShortText</a> value.
--   
--   See: <a>RFC-4648 section 8</a>
--   
--   <h3><b>Examples</b>:</h3>
--   
--   <pre>
--   &gt;&gt;&gt; decodeBase16Untyped "53756e"
--   Right "Sun"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; decodeBase16Untyped "6x"
--   Left "invalid character at offset: 1"
--   </pre>
decodeBase16Untyped :: ShortText -> Either Text ShortText

-- | Attempt to decode an untyped <a>ShortText</a> value as Base16,
--   converting from <tt>ByteString</tt> to <a>ShortText</a> according to
--   some encoding function. In practice, This is something like
--   <tt>decodeUtf8'</tt>, which may produce an error.
--   
--   See: <a>RFC-4648 section 8</a>
--   
--   <h3><b>Example</b>:</h3>
--   
--   <pre>
--   <a>decodeBase16With</a> (fmap <a>fromText</a> . <a>decodeUtf8'</a> . <a>fromShort</a>)
--     :: <a>ShortByteString</a> -&gt; <a>Either</a> (<a>Base16Error</a> <tt>UnicodeException</tt>) <a>ShortText</a>
--   </pre>
decodeBase16With :: (ShortByteString -> Either err ShortText) -> ShortByteString -> Either (Base16Error err) ShortText

-- | Decode an untyped Base16-encoded <a>ShortText</a> value leniently.
--   
--   Non-hexadecimal characters and a final unpaired hex digit are ignored.
--   Valid UTF-8 sequences are preserved. Each invalid UTF-8 byte is
--   interpreted as its Latin-1 character (U+0000 through U+00FF), ensuring
--   the result is valid <a>ShortText</a> without raising Unicode
--   exceptions.
--   
--   N.B.: this is not RFC 4648-compliant.
--   
--   <h3><b>Examples</b>:</h3>
--   
--   <pre>
--   &gt;&gt;&gt; decodeBase16Lenient "53756e"
--   "Sun"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; decodeBase16Lenient "6x6x"
--   "f"
--   </pre>
decodeBase16Lenient :: ShortText -> ShortText

-- | Validate an untyped Base16 value and retain its encoded
--   representation.
--   
--   Accepts even-length ASCII hexadecimal input, including upper-case and
--   mixed-case digits. Empty input is valid. The original input is
--   preserved, and errors match <a>decodeBase16Untyped</a>.
--   
--   This validates the Base16 encoding, not the UTF-8 validity of its
--   decoded payload. Use <a>decodeBase16With</a> with a checked conversion
--   for text decoding.
--   
--   <h3><b>Examples</b>:</h3>
--   
--   <pre>
--   &gt;&gt;&gt; parseBase16 "666f6"
--   Left "invalid bytestring size"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; parseBase16 "666F"
--   Right "666F"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; fmap decodeBase16 (parseBase16 "666F")
--   Right "fo"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; parseBase16 "6x"
--   Left "invalid character at offset: 1"
--   </pre>
parseBase16 :: ShortText -> Either Text (Base16 ShortText)
