{-# LANGUAGE OverloadedStrings #-}
-- |
-- Module       : Data.ByteString.Lazy.Base16
-- Copyright    : (c) 2020-2026 Emily Pillmore
-- License      : BSD-style
--
-- Maintainer   : Emily Pillmore <emilypi@cohomolo.gy>
-- Stability    : stable
-- Portability  : non-portable
--
-- This module contains 'Data.ByteString.Lazy.ByteString'-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
( encodeBase16
, encodeBase16'
, decodeBase16
, decodeBase16'
, decodeBase16Untyped
, decodeBase16Lenient
, parseBase16
) where



import Prelude hiding (elem)

import Data.Base16.Types
import qualified Data.ByteString as B
import Data.ByteString.Lazy (elem, fromChunks, fromStrict, toChunks, toStrict)
import Data.ByteString.Lazy.Internal (ByteString(..))
import qualified Data.ByteString.Base16.Internal.Head as B16
import qualified Data.ByteString.Base16 as B16 (decodeBase16Untyped, parseBase16)
import Data.ByteString.Base16.Internal.Utils (reChunk)
import Data.Text.Lazy (Text)
import qualified Data.Text as T
import qualified Data.Text.Lazy.Encoding as TL

-- $setup
--
-- >>> import Data.Base16.Types
-- >>> :set -XOverloadedStrings
--

-- | Encode a lazy 'ByteString' value as Base16 'Text'
--
-- See: <https://tools.ietf.org/html/rfc4648#section-8 RFC-4648 section 8>
--
-- === __Examples__:
--
-- >>> encodeBase16 "Sun"
-- "53756e"
--
encodeBase16 :: ByteString -> Base16 Text
encodeBase16 :: ByteString -> Base16 Text
encodeBase16 = (ByteString -> Text) -> Base16 ByteString -> Base16 Text
forall a b. (a -> b) -> Base16 a -> Base16 b
forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
fmap ByteString -> Text
TL.decodeUtf8 (Base16 ByteString -> Base16 Text)
-> (ByteString -> Base16 ByteString) -> ByteString -> Base16 Text
forall b c a. (b -> c) -> (a -> b) -> a -> c
. ByteString -> Base16 ByteString
encodeBase16'
{-# INLINE encodeBase16 #-}

-- | Encode a lazy 'ByteString' value as a Base16 'ByteString' value
--
-- See: <https://tools.ietf.org/html/rfc4648#section-8 RFC-4648 section 8>
--
-- === __Examples__:
--
-- >>> encodeBase16' "Sun"
-- "53756e"
--
encodeBase16' :: ByteString -> Base16 ByteString
encodeBase16' :: ByteString -> Base16 ByteString
encodeBase16' ByteString
bs = ByteString -> Base16 ByteString
forall a. a -> Base16 a
assertBase16 (ByteString -> Base16 ByteString)
-> ByteString -> Base16 ByteString
forall a b. (a -> b) -> a -> b
$ case ByteString
bs of
    ByteString
Empty -> ByteString
Empty
    Chunk StrictByteString
b ByteString
bs' -> StrictByteString -> ByteString -> ByteString
Chunk (StrictByteString -> StrictByteString
B16.encodeBase16_ StrictByteString
b) (Base16 ByteString -> ByteString
forall a. Base16 a -> a
extractBase16 (Base16 ByteString -> ByteString)
-> Base16 ByteString -> ByteString
forall a b. (a -> b) -> a -> b
$ ByteString -> Base16 ByteString
encodeBase16' ByteString
bs')
{-# INLINE encodeBase16' #-}

-- | Decode a Base16-encoded lazy 'ByteString' value.
--
-- Hexadecimal byte pairs may cross chunk boundaries. Decoding remains lazy
-- in the input chunks.
--
-- See: <https://tools.ietf.org/html/rfc4648#section-8 RFC-4648 section 8>
--
-- === __Examples__:
--
-- >>> decodeBase16 $ assertBase16 "53756e"
-- "Sun"
--
decodeBase16 :: Base16 ByteString -> ByteString
decodeBase16 :: Base16 ByteString -> ByteString
decodeBase16 = [StrictByteString] -> ByteString
fromChunks
  ([StrictByteString] -> ByteString)
-> (Base16 ByteString -> [StrictByteString])
-> Base16 ByteString
-> ByteString
forall b c a. (b -> c) -> (a -> b) -> a -> c
. (StrictByteString -> StrictByteString)
-> [StrictByteString] -> [StrictByteString]
forall a b. (a -> b) -> [a] -> [b]
forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
fmap (Base16 StrictByteString -> StrictByteString
B16.decodeBase16Typed_ (Base16 StrictByteString -> StrictByteString)
-> (StrictByteString -> Base16 StrictByteString)
-> StrictByteString
-> StrictByteString
forall b c a. (b -> c) -> (a -> b) -> a -> c
. StrictByteString -> Base16 StrictByteString
forall a. a -> Base16 a
assertBase16)
  ([StrictByteString] -> [StrictByteString])
-> (Base16 ByteString -> [StrictByteString])
-> Base16 ByteString
-> [StrictByteString]
forall b c a. (b -> c) -> (a -> b) -> a -> c
. [StrictByteString] -> [StrictByteString]
reChunk
  ([StrictByteString] -> [StrictByteString])
-> (Base16 ByteString -> [StrictByteString])
-> Base16 ByteString
-> [StrictByteString]
forall b c a. (b -> c) -> (a -> b) -> a -> c
. ByteString -> [StrictByteString]
toChunks
  (ByteString -> [StrictByteString])
-> (Base16 ByteString -> ByteString)
-> Base16 ByteString
-> [StrictByteString]
forall b c a. (b -> c) -> (a -> b) -> a -> c
. Base16 ByteString -> ByteString
forall a. Base16 a -> a
extractBase16
{-# INLINE decodeBase16 #-}

-- | Decode a Base16-encoded 'Text' value.
--
-- See: <https://tools.ietf.org/html/rfc4648#section-8 RFC-4648 section 8>
--
-- === __Examples__:
--
-- >>> decodeBase16' $ assertBase16 "53756e"
-- "Sun"
--
decodeBase16' :: Base16 Text -> ByteString
decodeBase16' :: Base16 Text -> ByteString
decodeBase16' = Base16 ByteString -> ByteString
decodeBase16 (Base16 ByteString -> ByteString)
-> (Base16 Text -> Base16 ByteString) -> Base16 Text -> ByteString
forall b c a. (b -> c) -> (a -> b) -> a -> c
. (Text -> ByteString) -> Base16 Text -> Base16 ByteString
forall a b. (a -> b) -> Base16 a -> Base16 b
forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
fmap Text -> ByteString
TL.encodeUtf8
{-# INLINE decodeBase16' #-}

-- | Decode an untyped Base16-encoded lazy 'ByteString' value.
--
-- Checks the whole input, joining chunks before decoding so that lengths
-- and error offsets refer to the complete encoded value.
--
-- See: <https://tools.ietf.org/html/rfc4648#section-8 RFC-4648 section 8>
--
-- === __Examples__:
--
-- >>> decodeBase16Untyped "53756e"
-- Right "Sun"
--
-- >>> decodeBase16Untyped "6x"
-- Left "invalid character at offset: 1"
--
decodeBase16Untyped :: ByteString -> Either T.Text ByteString
decodeBase16Untyped :: ByteString -> Either Text ByteString
decodeBase16Untyped = (StrictByteString -> ByteString)
-> Either Text StrictByteString -> Either Text ByteString
forall a b. (a -> b) -> Either Text a -> Either Text b
forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
fmap StrictByteString -> ByteString
fromStrict (Either Text StrictByteString -> Either Text ByteString)
-> (ByteString -> Either Text StrictByteString)
-> ByteString
-> Either Text ByteString
forall b c a. (b -> c) -> (a -> b) -> a -> c
. StrictByteString -> Either Text StrictByteString
B16.decodeBase16Untyped (StrictByteString -> Either Text StrictByteString)
-> (ByteString -> StrictByteString)
-> ByteString
-> Either Text StrictByteString
forall b c a. (b -> c) -> (a -> b) -> a -> c
. ByteString -> StrictByteString
toStrict
{-# INLINE decodeBase16Untyped #-}


-- | Decode an untyped Base16-encoded 'ByteString' 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!
--
-- === __Examples__:
--
-- >>> decodeBase16Lenient "53756e"
-- "Sun"
--
-- >>> decodeBase16Lenient "6x6x"
-- "f"
--
decodeBase16Lenient :: ByteString -> ByteString
decodeBase16Lenient :: ByteString -> ByteString
decodeBase16Lenient = [StrictByteString] -> ByteString
fromChunks
  ([StrictByteString] -> ByteString)
-> (ByteString -> [StrictByteString]) -> ByteString -> ByteString
forall b c a. (b -> c) -> (a -> b) -> a -> c
. (StrictByteString -> StrictByteString)
-> [StrictByteString] -> [StrictByteString]
forall a b. (a -> b) -> [a] -> [b]
forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
fmap StrictByteString -> StrictByteString
B16.decodeBase16Lenient_
  ([StrictByteString] -> [StrictByteString])
-> (ByteString -> [StrictByteString])
-> ByteString
-> [StrictByteString]
forall b c a. (b -> c) -> (a -> b) -> a -> c
. [StrictByteString] -> [StrictByteString]
reChunk
  ([StrictByteString] -> [StrictByteString])
-> (ByteString -> [StrictByteString])
-> ByteString
-> [StrictByteString]
forall b c a. (b -> c) -> (a -> b) -> a -> c
. (StrictByteString -> StrictByteString)
-> [StrictByteString] -> [StrictByteString]
forall a b. (a -> b) -> [a] -> [b]
forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
fmap ((Word8 -> Bool) -> StrictByteString -> StrictByteString
B.filter ((Word8 -> ByteString -> Bool) -> ByteString -> Word8 -> Bool
forall a b c. (a -> b -> c) -> b -> a -> c
flip Word8 -> ByteString -> Bool
elem ByteString
"0123456789abcdefABCDEF"))
  ([StrictByteString] -> [StrictByteString])
-> (ByteString -> [StrictByteString])
-> ByteString
-> [StrictByteString]
forall b c a. (b -> c) -> (a -> b) -> a -> c
. ByteString -> [StrictByteString]
toChunks
{-# INLINE decodeBase16Lenient #-}

-- | 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 'decodeBase16Untyped'.
--
-- The whole input is validated before returning 'Right', regardless of
-- chunk boundaries. The returned wrapper preserves those boundaries.
--
-- === __Examples__:
--
-- >>> parseBase16 "666f6"
-- Left "invalid bytestring size"
--
-- >>> parseBase16 "666F"
-- Right "666F"
--
-- >>> fmap decodeBase16 (parseBase16 "666F")
-- Right "fo"
--
-- >>> parseBase16 "6x"
-- Left "invalid character at offset: 1"
--
-- @since 2.0
--
parseBase16 :: ByteString -> Either T.Text (Base16 ByteString)
parseBase16 :: ByteString -> Either Text (Base16 ByteString)
parseBase16 ByteString
bs = ByteString -> Base16 ByteString
forall a. a -> Base16 a
assertBase16 ByteString
bs Base16 ByteString
-> Either Text (Base16 StrictByteString)
-> Either Text (Base16 ByteString)
forall a b. a -> Either Text b -> Either Text a
forall (f :: * -> *) a b. Functor f => a -> f b -> f a
<$ StrictByteString -> Either Text (Base16 StrictByteString)
B16.parseBase16 (ByteString -> StrictByteString
toStrict ByteString
bs)
{-# INLINE parseBase16 #-}