func AppendCompact
AppendCompact works like PutCompact but appends to the given byte slice instead of allocating one anew.
v0 source pure
Package cford32 implements a base32-like encoding/decoding package, with the encoding scheme [specified by Douglas Cr...
View source
v0 - Unaudited This is an initial version of this package that has not yet been formally audited. A fully audited version will be published as a subsequent release. Use in production at your own risk.
cford32
package cford32 // import "gno.land/p/nt/cford32/v0"
Package cford32 implements a base32-like encoding/decoding package, with the
encoding scheme specified by Douglas Crockford.
From the website, the requirements of said encoding scheme are to:
- Be human readable and machine readable.
- Be compact. Humans have difficulty in manipulating long strings of arbitrary
symbols.
- Be error resistant. Entering the symbols must not require keyboarding
gymnastics.
- Be pronounceable. Humans should be able to accurately transmit the symbols
to other humans using a telephone.
This is slightly different from a simple difference in encoding table from
the Go's stdlib `encoding/base32`, as when decoding the characters i I l L are
parsed as 1, and o O is parsed as 0.
This package additionally provides ways to encode uint64's efficiently, as well
as efficient encoding to a lowercase variation of the encoding. The encodings
never use paddings.
# Uint64 Encoding
Aside from lower/uppercase encoding, there is a compact encoding, allowing to
encode all values in [0,2^34), and the full encoding, allowing all values in
[0,2^64). The compact encoding uses 7 characters, and the full encoding uses 13
characters. Both are parsed unambiguously by the Uint64 decoder.
The compact encodings have the first character between ['0','f'], while the
full encoding's first character ranges between ['g','z']. Practically, in your
usage of the package, you should consider which one to use and stick with it,
while considering that the compact encoding, once it reaches 2^34, automatically
switches to the full encoding. The properties of the generated strings are still
maintained: for instance, any two encoded uint64s x,y consistently generated
with the compact encoding, if the numeric value is x < y, will also be x < y in
lexical ordering. However, values [0,2^34) have a "double encoding", which if
mixed together lose the lexical ordering property.
The Uint64 encoding is most useful for generating string versions of Uint64 IDs.
Practically, it allows you to retain sleek and compact IDs for your application
for the first 2^34 (>17 billion) entities, while seamlessly rolling over to the
full encoding should you exceed that. You are encouraged to use it unless you
have a requirement or preferences for IDs consistently being always the same
size.
To use the cford32 encoding for IDs, you may want to consider using package
gno.land/p/nt/seqid/v0.
[specified by Douglas Crockford]: https://www.crockford.com/base32.html
func AppendCompact(id uint64, b []byte) []byte
func AppendDecode(dst, src []byte) ([]byte, error)
func AppendEncode(dst, src []byte) []byte
func AppendEncodeLower(dst, src []byte) []byte
func Decode(dst, src []byte) (n int, err error)
func DecodeString(s string) ([]byte, error)
func DecodedLen(n int) int
func Encode(dst, src []byte)
func EncodeLower(dst, src []byte)
func EncodeToString(src []byte) string
func EncodeToStringLower(src []byte) string
func EncodedLen(n int) int
func NewDecoder(r io.Reader) io.Reader
func NewEncoder(w io.Writer) io.WriteCloser
func NewEncoderLower(w io.Writer) io.WriteCloser
func PutCompact(id uint64) []byte
func PutUint64(id uint64) [13]byte
func PutUint64Lower(id uint64) [13]byte
func Uint64(b []byte) (uint64, error)
type CorruptInputError int64
Package cford32 implements a base32-like encoding/decoding package, with the encoding scheme specified by Douglas Crockford.
From the website, the requirements of said encoding scheme are to:
- Be human readable and machine readable.
- Be compact. Humans have difficulty in manipulating long strings of arbitrary symbols.
- Be error resistant. Entering the symbols must not require keyboarding gymnastics.
- Be pronounceable. Humans should be able to accurately transmit the symbols to other humans using a telephone.
This is slightly different from a simple difference in encoding table from the Go's stdlib `encoding/base32`, as when decoding the characters i I l L are parsed as 1, and o O is parsed as 0.
This package additionally provides ways to encode uint64's efficiently, as well as efficient encoding to a lowercase variation of the encoding. The encodings never use paddings.
Uint64 Encoding
Aside from lower/uppercase encoding, there is a compact encoding, allowing to encode all values in [0,2^34), and the full encoding, allowing all values in [0,2^64). The compact encoding uses 7 characters, and the full encoding uses 13 characters. Both are parsed unambiguously by the Uint64 decoder.
The compact encodings have the first character between ['0','f'], while the full encoding's first character ranges between ['g','z']. Practically, in your usage of the package, you should consider which one to use and stick with it, while considering that the compact encoding, once it reaches 2^34, automatically switches to the full encoding. The properties of the generated strings are still maintained: for instance, any two encoded uint64s x,y consistently generated with the compact encoding, if the numeric value is x < y, will also be x < y in lexical ordering. However, values [0,2^34) have a "double encoding", which if mixed together lose the lexical ordering property.
The Uint64 encoding is most useful for generating string versions of Uint64 IDs. Practically, it allows you to retain sleek and compact IDs for your application for the first 2^34 (>17 billion) entities, while seamlessly rolling over to the full encoding should you exceed that. You are encouraged to use it unless you have a requirement or preferences for IDs consistently being always the same size.
To use the cford32 encoding for IDs, you may want to consider using package gno.land/p/nt/seqid/v0.
v0 - Unaudited: This is an initial version that has not yet been formally audited. A fully audited version will be published as a subsequent release. Use in production at your own risk.
Package cford32 implements a modified base32 encoding based on Douglas Crockford's base32 encoding.
19
func AppendDecode
AppendDecode appends the cford32 decoded src to dst and returns the extended buffer. If the input is malformed, it returns the partially decoded src and an error.
func AppendEncode
AppendEncode appends the cford32 encoded src to dst and returns the extended buffer.
func AppendEncodeLower
AppendEncodeLower appends the lowercase cford32 encoded src to dst and returns the extended buffer.
func Decode
Decode decodes src using cford32. It writes at most DecodedLen(len(src)) bytes to dst and returns the number of bytes written. If src contains invalid cford32 data, it will return the number of bytes successfully written and CorruptInputError. Newline characters (\r and \n) are ignored.
func DecodeString
DecodeString returns the bytes represented by the cford32 string s.
func DecodedLen
func Encode
Encode encodes src using the encoding enc, writing EncodedLen(len(src)) bytes to dst.
The encoding does not contain any padding, unlike Go's base32.
func EncodeLower
EncodeLower is like Encode, but uses the lowercase
func EncodeToString
EncodeToString returns the cford32 encoding of src.
func EncodeToStringLower
EncodeToStringLower returns the cford32 lowercase encoding of src.
func EncodedLen
func NewDecoder
NewDecoder constructs a new base32 stream decoder.
func NewEncoder
func NewEncoderLower
func PutCompact
PutCompact returns a cford32-encoded byte slice, using the compact representation of cford32 described in the package documentation where possible (all values of id < 1<<34). The lowercase encoding is used.
The resulting byte slice will be 7 bytes long for all compact values, and 13 bytes long for
func PutUint64
PutUint64 returns a cford32-encoded byte slice.
func PutUint64Lower
PutUint64Lower returns a cford32-encoded byte array, swapping uppercase letters with lowercase.
For more information on how the value is encoded, see Uint64.
func Uint64
Uint64 parses a cford32-encoded byte slice into a uint64.
- The parser requires all provided character to be valid cford32 characters.
- The parser disregards case.
- If the first character is '0' <= c <= 'f', then the passed value is assumed encoded in the compact encoding, and must be 7 characters long.
- If the first character is 'g' <= c <= 'z', then the passed value is assumed encoded in the full encoding, and must be 13 characters long.
If any of these requirements fail, a CorruptInputError will be returned.
1
type CorruptInputError
identCorruptInputError is returned by parsing functions when an invalid character in the input is found. The integer value represents the byte index where the error occurred.
This is typically because the given character does not exist in the encoding.
2
- io stdlib
- strconv stdlib
