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


-- | Implementation of the Bech32 cryptocurrency address format (BIP 0173).
--   
--   Implementation of the Bech32 cryptocurrency address format documented
--   in the BIP (Bitcoin Improvement Proposal) 0173.
@package bech32
@version 1.1.5


-- | Implementation of the <a>Bech32</a> address format.
--   
--   From an original implementation by Marko Bencun:
--   
--   <a>sipa/bech32</a>
module Codec.Binary.Bech32.Internal

-- | Encode a Bech32 string from a human-readable prefix and data payload.
--   
--   <h2>Example</h2>
--   
--   <pre>
--   &gt;&gt;&gt; import Prelude
--   
--   &gt;&gt;&gt; import Codec.Binary.Bech32
--   
--   &gt;&gt;&gt; import Data.Text.Encoding
--   </pre>
--   
--   First, prepare a human-readable prefix:
--   
--   <pre>
--   &gt;&gt;&gt; Right prefix = humanReadablePartFromText "example"
--   </pre>
--   
--   Next, prepare a data payload:
--   
--   <pre>
--   &gt;&gt;&gt; messageToEncode = "Lorem ipsum dolor sit amet!"
--   
--   &gt;&gt;&gt; dataPart = dataPartFromBytes $ encodeUtf8 messageToEncode
--   </pre>
--   
--   Finally, produce a Bech32 string:
--   
--   <pre>
--   &gt;&gt;&gt; encode prefix dataPart
--   Right "example1f3hhyetdyp5hqum4d5sxgmmvdaezqumfwssxzmt9wsss9un3cx"
--   </pre>
encode :: HumanReadablePart -> DataPart -> Either EncodingError Text

-- | Like <a>encode</a> but allows output to be longer than 90 characters.
--   
--   This isn't ideal, as Bech32 error detection becomes worse as strings
--   get longer, but it may be useful in certain circumstances.
--   
--   From <a>BIP-0173</a>:
--   
--   "Even though the chosen code performs reasonably well up to 1023
--   characters, other designs are preferable for lengths above 89
--   characters (excluding the separator)."
encodeLenient :: HumanReadablePart -> DataPart -> Text

-- | Represents the set of error conditions that may occur while encoding a
--   Bech32 string.
data EncodingError

-- | The resultant encoded string would be <i>longer than</i>
--   <a>encodedStringMaxLength</a>.
EncodedStringTooLong :: EncodingError

-- | Decode a Bech32 string into a human-readable prefix and data payload.
--   
--   <h2>Example</h2>
--   
--   <pre>
--   &gt;&gt;&gt; import Prelude
--   
--   &gt;&gt;&gt; import Codec.Binary.Bech32
--   
--   &gt;&gt;&gt; import Data.Text.Encoding
--   </pre>
--   
--   First, decode the input:
--   
--   <pre>
--   &gt;&gt;&gt; input = "example1f3hhyetdyp5hqum4d5sxgmmvdaezqumfwssxzmt9wsss9un3cx"
--   
--   &gt;&gt;&gt; Right (prefix, dataPart) = decode input
--   </pre>
--   
--   Next, examine the decoded human-readable prefix:
--   
--   <pre>
--   &gt;&gt;&gt; humanReadablePartToText prefix
--   "example"
--   </pre>
--   
--   Finally, examine the decoded data payload:
--   
--   <pre>
--   &gt;&gt;&gt; decodeUtf8 &lt;$&gt; dataPartToBytes dataPart
--   Just "Lorem ipsum dolor sit amet!"
--   </pre>
decode :: Text -> Either DecodingError (HumanReadablePart, DataPart)

-- | Like <a>decode</a> but does not enforce a maximum length.
--   
--   See also <a>encodeLenient</a> for details.
decodeLenient :: Text -> Either DecodingError (HumanReadablePart, DataPart)

-- | Represents the set of errors that may occur while decoding a Bech32
--   string with the <a>decode</a> function.
data DecodingError

-- | The string to decode is <i>longer than</i>
--   <a>encodedStringMaxLength</a>.
StringToDecodeTooLong :: DecodingError

-- | The string to decode is <i>shorter than</i>
--   <a>encodedStringMinLength</a>.
StringToDecodeTooShort :: DecodingError

-- | The string to decode contains <i>both</i> upper case <i>and</i> lower
--   case characters.
StringToDecodeHasMixedCase :: DecodingError

-- | The string to decode is missing the <i>separator character</i>,
--   specified by <a>separatorChar</a>.
StringToDecodeMissingSeparatorChar :: DecodingError

-- | The string to decode contains one or more <i>invalid characters</i>.
--   
--   In cases where it <i>is</i> possible to determine the exact locations
--   of erroneous characters, this list will encode those locations.
--   Clients can use this information to provide user feedback.
--   
--   In cases where it <i>isn't</i> possible to reliably determine the
--   locations of erroneous characters, this list will be empty.
StringToDecodeContainsInvalidChars :: [CharPosition] -> DecodingError

-- | The length of the checksum portion of an encoded string, in bytes.
checksumLength :: Int

-- | The maximum length of an encoded string, in bytes.
--   
--   This length includes the human-readable part, the separator character,
--   the encoded data portion, and the checksum.
encodedStringMaxLength :: Int

-- | The minimum length of an encoded string, in bytes.
--   
--   This length includes the human-readable part, the separator character,
--   the encoded data portion, and the checksum.
encodedStringMinLength :: Int

-- | The separator character.
--   
--   This character appears immediately after the human-readable part and
--   before the data part in an encoded string.
separatorChar :: Char

-- | The length of the separator portion of an encoded string, in bytes.
separatorLength :: Int

-- | Represents the data part of a Bech32 string, as defined here:
--   <a>https://git.io/fj8FS</a>
data DataPart

-- | Returns true iff. the specified <a>DataPart</a> is valid.
dataPartIsValid :: DataPart -> Bool

-- | Constructs a <a>DataPart</a> from a <a>ByteString</a>.
--   
--   This function encodes a <a>ByteString</a> in such a way that
--   guarantees it can be successfully decoded with the
--   <a>dataPartToBytes</a> function:
--   
--   <pre>
--   dataPartToBytes (dataPartFromBytes b) == Just b
--   </pre>
dataPartFromBytes :: ByteString -> DataPart

-- | Constructs a <a>DataPart</a> from textual input.
--   
--   All characters in the input must be a member of <a>dataCharList</a>,
--   the set of characters permitted to appear within the data part of a
--   Bech32 string.
--   
--   Returns <a>Nothing</a> if any character in the input is not a member
--   of <a>dataCharList</a>.
--   
--   This function guarantees to satisfy the following property:
--   
--   <pre>
--   dataPartFromText (dataPartToText d) == Just d
--   </pre>
dataPartFromText :: Text -> Maybe DataPart

-- | Construct a <a>DataPart</a> directly from a list of words.
--   
--   This function guarantees to satisfy the following properties:
--   
--   <pre>
--   dataPartFromWords (dataPartToWords d) == d
--   dataPartToWords (dataPartFromWords w) == w
--   </pre>
dataPartFromWords :: [Word5] -> DataPart

-- | Attempts to extract a <a>ByteString</a> from a <a>DataPart</a>.
--   
--   This function guarantees to satisfy the following property:
--   
--   <pre>
--   dataPartToBytes (dataPartFromBytes b) == Just b
--   </pre>
dataPartToBytes :: DataPart -> Maybe ByteString

-- | Converts a <a>DataPart</a> to <a>Text</a>, using the Bech32 character
--   set to render the data.
--   
--   This function guarantees to satisfy the following property:
--   
--   <pre>
--   dataPartFromText (dataPartToText d) == Just d
--   </pre>
dataPartToText :: DataPart -> Text

-- | Unpack a <a>DataPart</a> into a list of its constituent words.
--   
--   This function guarantees to satisfy the following properties:
--   
--   <pre>
--   dataPartFromWords (dataPartToWords d) == d
--   dataPartToWords (dataPartFromWords w) == w
--   </pre>
dataPartToWords :: DataPart -> [Word5]

-- | If the specified character is permitted to appear within the data part
--   of a Bech32 string, this function returns that character's
--   corresponding <a>Word5</a> value. If the specified character is not
--   permitted, or if the specified character is upper-case, returns
--   <a>Nothing</a>.
dataCharToWord :: Char -> Maybe Word5

-- | Maps the specified <a>Word5</a> onto a character that is permitted to
--   appear within the data part of a Bech32 string.
dataCharFromWord :: Word5 -> Char

-- | A list of all characters that are permitted to appear within the data
--   part of a Bech32 string.
--   
--   See here for more details: <a>https://git.io/fj8FS</a>
dataCharList :: String

-- | Represents the human-readable part of a Bech32 string, as defined
--   here: <a>https://git.io/fj8FS</a>
data HumanReadablePart

-- | Represents the set of error conditions that may occur while parsing
--   the human-readable part of a Bech32 string.
data HumanReadablePartError

-- | The human-readable part is <i>shorter than</i>
--   <a>humanReadablePartMinLength</a>.
HumanReadablePartTooShort :: HumanReadablePartError

-- | The human-readable part is <i>longer than</i>
--   <a>humanReadablePartMaxLength</a>.
HumanReadablePartTooLong :: HumanReadablePartError

-- | The human-readable part contains one or more characters whose values
--   are <i>less than</i> <a>humanReadableCharMinBound</a> or <i>greater
--   than</i> <a>humanReadableCharMaxBound</a>.
HumanReadablePartContainsInvalidChars :: [CharPosition] -> HumanReadablePartError

-- | Parses the human-readable part of a Bech32 string, as defined here:
--   <a>https://git.io/fj8FS</a>
humanReadablePartFromText :: Text -> Either HumanReadablePartError HumanReadablePart

-- | Get the raw text of the human-readable part of a Bech32 string.
humanReadablePartToText :: HumanReadablePart -> Text

-- | Convert the specified human-readable part to a list of words.
humanReadablePartToWords :: HumanReadablePart -> [Word5]

-- | The shortest length permitted for the human-readable part of a Bech32
--   string.
humanReadablePartMinLength :: Int

-- | The longest length permitted for the human-readable part of a Bech32
--   string.
humanReadablePartMaxLength :: Int

-- | Returns true iff. the specified character is permitted to appear
--   within the human-readable part of a Bech32 string.
humanReadableCharIsValid :: Char -> Bool

-- | The lower bound of the set of characters permitted to appear within
--   the human-readable part of a Bech32 string.
humanReadableCharMinBound :: Char

-- | The upper bound of the set of characters permitted to appear within
--   the human-readable part of a Bech32 string.
humanReadableCharMaxBound :: Char

-- | Big-endian conversion of a word string from base '2^frombits' to base
--   '2^tobits'. The <tt>frombits</tt> and <tt>twobits</tt> parameters must
--   be positive, while '2^frombits' and '2^tobits' must be smaller than
--   the size of <a>Word</a>. Every value in <tt>dat</tt> must be strictly
--   smaller than '2^frombits'.
convertBits :: Functor f => [Word] -> Int -> Int -> Pad f -> f [Word]

-- | Represents a <b>data word</b> of <b>5 bits</b> in width.
--   
--   Each character in the data portion of a Bech32 string encodes exactly
--   5 bits of data.
--   
--   <h3>Construction and Deconstruction</h3>
--   
--   Use the <a>toEnum</a> and <a>fromEnum</a> functions to construct and
--   deconstruct <a>Word5</a> values.
--   
--   <h3>Packing Words into Data Payloads</h3>
--   
--   Use the <a>dataPartFromWords</a> and <a>dataPartToWords</a> functions
--   to pack and unpack <a>Word5</a> values into and out of data payloads.
data Word5
word5 :: Integral a => a -> Word5
getWord5 :: Word5 -> Word8
toBase256 :: [Word5] -> Maybe [Word8]
toBase32 :: [Word8] -> [Word5]
noPadding :: Pad Maybe
yesPadding :: Pad Identity

-- | The zero-based position of a character in a string, counting from the
--   left.
--   
--   Values of this type are typically used to reflect the positions of
--   errors.
--   
--   See <a>DecodingError</a>.
newtype CharPosition
CharPosition :: Int -> CharPosition
instance GHC.Show.Show Codec.Binary.Bech32.Internal.DataPart
instance GHC.Base.Semigroup Codec.Binary.Bech32.Internal.DataPart
instance GHC.Base.Monoid Codec.Binary.Bech32.Internal.DataPart
instance GHC.Classes.Eq Codec.Binary.Bech32.Internal.DataPart
instance GHC.Show.Show Codec.Binary.Bech32.Internal.HumanReadablePart
instance GHC.Base.Semigroup Codec.Binary.Bech32.Internal.HumanReadablePart
instance GHC.Base.Monoid Codec.Binary.Bech32.Internal.HumanReadablePart
instance GHC.Classes.Eq Codec.Binary.Bech32.Internal.HumanReadablePart
instance GHC.Show.Show Codec.Binary.Bech32.Internal.EncodingError
instance GHC.Classes.Eq Codec.Binary.Bech32.Internal.EncodingError
instance GHC.Show.Show Codec.Binary.Bech32.Internal.CharPosition
instance GHC.Classes.Ord Codec.Binary.Bech32.Internal.CharPosition
instance GHC.Classes.Eq Codec.Binary.Bech32.Internal.CharPosition
instance GHC.Show.Show Codec.Binary.Bech32.Internal.DecodingError
instance GHC.Classes.Eq Codec.Binary.Bech32.Internal.DecodingError
instance GHC.Show.Show Codec.Binary.Bech32.Internal.HumanReadablePartError
instance GHC.Classes.Eq Codec.Binary.Bech32.Internal.HumanReadablePartError
instance GHC.Show.Show Codec.Binary.Bech32.Internal.Word5
instance GHC.Classes.Ord Codec.Binary.Bech32.Internal.Word5
instance GHC.Classes.Eq Codec.Binary.Bech32.Internal.Word5
instance GHC.Enum.Bounded Codec.Binary.Bech32.Internal.Word5
instance GHC.Enum.Enum Codec.Binary.Bech32.Internal.Word5
instance GHC.Ix.Ix Codec.Binary.Bech32.Internal.Word5
instance GHC.Exception.Type.Exception Codec.Binary.Bech32.Internal.HumanReadablePartError


-- | Implementation of the <a>Bech32</a> address format.
--   
--   Based on an <a>original implementation</a> by <a>Marko Bencun</a>.
module Codec.Binary.Bech32

-- | Encode a Bech32 string from a human-readable prefix and data payload.
--   
--   <h2>Example</h2>
--   
--   <pre>
--   &gt;&gt;&gt; import Prelude
--   
--   &gt;&gt;&gt; import Codec.Binary.Bech32
--   
--   &gt;&gt;&gt; import Data.Text.Encoding
--   </pre>
--   
--   First, prepare a human-readable prefix:
--   
--   <pre>
--   &gt;&gt;&gt; Right prefix = humanReadablePartFromText "example"
--   </pre>
--   
--   Next, prepare a data payload:
--   
--   <pre>
--   &gt;&gt;&gt; messageToEncode = "Lorem ipsum dolor sit amet!"
--   
--   &gt;&gt;&gt; dataPart = dataPartFromBytes $ encodeUtf8 messageToEncode
--   </pre>
--   
--   Finally, produce a Bech32 string:
--   
--   <pre>
--   &gt;&gt;&gt; encode prefix dataPart
--   Right "example1f3hhyetdyp5hqum4d5sxgmmvdaezqumfwssxzmt9wsss9un3cx"
--   </pre>
encode :: HumanReadablePart -> DataPart -> Either EncodingError Text

-- | Decode a Bech32 string into a human-readable prefix and data payload.
--   
--   <h2>Example</h2>
--   
--   <pre>
--   &gt;&gt;&gt; import Prelude
--   
--   &gt;&gt;&gt; import Codec.Binary.Bech32
--   
--   &gt;&gt;&gt; import Data.Text.Encoding
--   </pre>
--   
--   First, decode the input:
--   
--   <pre>
--   &gt;&gt;&gt; input = "example1f3hhyetdyp5hqum4d5sxgmmvdaezqumfwssxzmt9wsss9un3cx"
--   
--   &gt;&gt;&gt; Right (prefix, dataPart) = decode input
--   </pre>
--   
--   Next, examine the decoded human-readable prefix:
--   
--   <pre>
--   &gt;&gt;&gt; humanReadablePartToText prefix
--   "example"
--   </pre>
--   
--   Finally, examine the decoded data payload:
--   
--   <pre>
--   &gt;&gt;&gt; decodeUtf8 &lt;$&gt; dataPartToBytes dataPart
--   Just "Lorem ipsum dolor sit amet!"
--   </pre>
decode :: Text -> Either DecodingError (HumanReadablePart, DataPart)

-- | Represents the set of error conditions that may occur while encoding a
--   Bech32 string.
data EncodingError

-- | The resultant encoded string would be <i>longer than</i>
--   <a>encodedStringMaxLength</a>.
EncodedStringTooLong :: EncodingError

-- | Represents the set of errors that may occur while decoding a Bech32
--   string with the <a>decode</a> function.
data DecodingError

-- | The string to decode is <i>longer than</i>
--   <a>encodedStringMaxLength</a>.
StringToDecodeTooLong :: DecodingError

-- | The string to decode is <i>shorter than</i>
--   <a>encodedStringMinLength</a>.
StringToDecodeTooShort :: DecodingError

-- | The string to decode contains <i>both</i> upper case <i>and</i> lower
--   case characters.
StringToDecodeHasMixedCase :: DecodingError

-- | The string to decode is missing the <i>separator character</i>,
--   specified by <a>separatorChar</a>.
StringToDecodeMissingSeparatorChar :: DecodingError

-- | The string to decode contains one or more <i>invalid characters</i>.
--   
--   In cases where it <i>is</i> possible to determine the exact locations
--   of erroneous characters, this list will encode those locations.
--   Clients can use this information to provide user feedback.
--   
--   In cases where it <i>isn't</i> possible to reliably determine the
--   locations of erroneous characters, this list will be empty.
StringToDecodeContainsInvalidChars :: [CharPosition] -> DecodingError

-- | Represents the data part of a Bech32 string, as defined here:
--   <a>https://git.io/fj8FS</a>
data DataPart

-- | Construct a <a>DataPart</a> directly from a list of words.
--   
--   This function guarantees to satisfy the following properties:
--   
--   <pre>
--   dataPartFromWords (dataPartToWords d) == d
--   dataPartToWords (dataPartFromWords w) == w
--   </pre>
dataPartFromWords :: [Word5] -> DataPart

-- | Unpack a <a>DataPart</a> into a list of its constituent words.
--   
--   This function guarantees to satisfy the following properties:
--   
--   <pre>
--   dataPartFromWords (dataPartToWords d) == d
--   dataPartToWords (dataPartFromWords w) == w
--   </pre>
dataPartToWords :: DataPart -> [Word5]

-- | Constructs a <a>DataPart</a> from a <a>ByteString</a>.
--   
--   This function encodes a <a>ByteString</a> in such a way that
--   guarantees it can be successfully decoded with the
--   <a>dataPartToBytes</a> function:
--   
--   <pre>
--   dataPartToBytes (dataPartFromBytes b) == Just b
--   </pre>
dataPartFromBytes :: ByteString -> DataPart

-- | Attempts to extract a <a>ByteString</a> from a <a>DataPart</a>.
--   
--   This function guarantees to satisfy the following property:
--   
--   <pre>
--   dataPartToBytes (dataPartFromBytes b) == Just b
--   </pre>
dataPartToBytes :: DataPart -> Maybe ByteString

-- | Constructs a <a>DataPart</a> from textual input.
--   
--   All characters in the input must be a member of <a>dataCharList</a>,
--   the set of characters permitted to appear within the data part of a
--   Bech32 string.
--   
--   Returns <a>Nothing</a> if any character in the input is not a member
--   of <a>dataCharList</a>.
--   
--   This function guarantees to satisfy the following property:
--   
--   <pre>
--   dataPartFromText (dataPartToText d) == Just d
--   </pre>
dataPartFromText :: Text -> Maybe DataPart

-- | Converts a <a>DataPart</a> to <a>Text</a>, using the Bech32 character
--   set to render the data.
--   
--   This function guarantees to satisfy the following property:
--   
--   <pre>
--   dataPartFromText (dataPartToText d) == Just d
--   </pre>
dataPartToText :: DataPart -> Text

-- | Represents the human-readable part of a Bech32 string, as defined
--   here: <a>https://git.io/fj8FS</a>
data HumanReadablePart

-- | Parses the human-readable part of a Bech32 string, as defined here:
--   <a>https://git.io/fj8FS</a>
humanReadablePartFromText :: Text -> Either HumanReadablePartError HumanReadablePart

-- | Get the raw text of the human-readable part of a Bech32 string.
humanReadablePartToText :: HumanReadablePart -> Text

-- | Represents the set of error conditions that may occur while parsing
--   the human-readable part of a Bech32 string.
data HumanReadablePartError

-- | The human-readable part is <i>shorter than</i>
--   <a>humanReadablePartMinLength</a>.
HumanReadablePartTooShort :: HumanReadablePartError

-- | The human-readable part is <i>longer than</i>
--   <a>humanReadablePartMaxLength</a>.
HumanReadablePartTooLong :: HumanReadablePartError

-- | The human-readable part contains one or more characters whose values
--   are <i>less than</i> <a>humanReadableCharMinBound</a> or <i>greater
--   than</i> <a>humanReadableCharMaxBound</a>.
HumanReadablePartContainsInvalidChars :: [CharPosition] -> HumanReadablePartError

-- | The zero-based position of a character in a string, counting from the
--   left.
--   
--   Values of this type are typically used to reflect the positions of
--   errors.
--   
--   See <a>DecodingError</a>.
newtype CharPosition
CharPosition :: Int -> CharPosition

-- | Represents a <b>data word</b> of <b>5 bits</b> in width.
--   
--   Each character in the data portion of a Bech32 string encodes exactly
--   5 bits of data.
--   
--   <h3>Construction and Deconstruction</h3>
--   
--   Use the <a>toEnum</a> and <a>fromEnum</a> functions to construct and
--   deconstruct <a>Word5</a> values.
--   
--   <h3>Packing Words into Data Payloads</h3>
--   
--   Use the <a>dataPartFromWords</a> and <a>dataPartToWords</a> functions
--   to pack and unpack <a>Word5</a> values into and out of data payloads.
data Word5

-- | Like <a>encode</a> but allows output to be longer than 90 characters.
--   
--   This isn't ideal, as Bech32 error detection becomes worse as strings
--   get longer, but it may be useful in certain circumstances.
--   
--   From <a>BIP-0173</a>:
--   
--   "Even though the chosen code performs reasonably well up to 1023
--   characters, other designs are preferable for lengths above 89
--   characters (excluding the separator)."
encodeLenient :: HumanReadablePart -> DataPart -> Text

-- | Like <a>decode</a> but does not enforce a maximum length.
--   
--   See also <a>encodeLenient</a> for details.
decodeLenient :: Text -> Either DecodingError (HumanReadablePart, DataPart)

-- | A list of all characters that are permitted to appear within the data
--   part of a Bech32 string.
--   
--   See here for more details: <a>https://git.io/fj8FS</a>
dataCharList :: String

-- | The shortest length permitted for the human-readable part of a Bech32
--   string.
humanReadablePartMinLength :: Int

-- | The longest length permitted for the human-readable part of a Bech32
--   string.
humanReadablePartMaxLength :: Int

-- | The lower bound of the set of characters permitted to appear within
--   the human-readable part of a Bech32 string.
humanReadableCharMinBound :: Char

-- | The upper bound of the set of characters permitted to appear within
--   the human-readable part of a Bech32 string.
humanReadableCharMaxBound :: Char

-- | The maximum length of an encoded string, in bytes.
--   
--   This length includes the human-readable part, the separator character,
--   the encoded data portion, and the checksum.
encodedStringMaxLength :: Int

-- | The minimum length of an encoded string, in bytes.
--   
--   This length includes the human-readable part, the separator character,
--   the encoded data portion, and the checksum.
encodedStringMinLength :: Int

-- | The separator character.
--   
--   This character appears immediately after the human-readable part and
--   before the data part in an encoded string.
separatorChar :: Char
