Base16.hs

{-# 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 = fmap TL.decodeUtf8 . 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' bs = assertBase16 $ case bs of
    Empty -> Empty
    Chunk b bs' -> Chunk (B16.encodeBase16_ b) (extractBase16 $ encodeBase16' 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 = fromChunks
  . fmap (B16.decodeBase16Typed_ . assertBase16)
  . reChunk
  . toChunks
  . 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' = decodeBase16 . fmap 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 = fmap fromStrict . B16.decodeBase16Untyped . 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 = fromChunks
  . fmap B16.decodeBase16Lenient_
  . reChunk
  . fmap (B.filter (flip elem "0123456789abcdefABCDEF"))
  . 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 bs = assertBase16 bs <$ B16.parseBase16 (toStrict bs)
{-# INLINE parseBase16 #-}