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 - Crockford Base32 encoding
Modified base32 encoding using the Crockford alphabet. Designed to be human-readable, error-resistant, and pronounceable: the ambiguous characters I, L, O, U are excluded from the encoding, and decoding accepts I/L as 1 and O as 0. Output is never padded.
Usage
1import "gno.land/p/nt/cford32/v0"
2
3// Byte slice encode/decode.
4encoded := cford32.EncodeToString([]byte("hello")) // uppercase, no padding
5decoded, err := cford32.DecodeString(encoded) // []byte("hello")
6
7// Lowercase variant.
8lower := cford32.EncodeToStringLower([]byte("hello"))
9
10// Compact uint64 encoding: 7 bytes for id < 2^34, else 13 bytes.
11enc := cford32.PutCompact(42)
12back, _ := cford32.Uint64(enc) // 42
13
14// Full fixed-width uint64 encoding (always 13 bytes).
15full := cford32.PutUint64(42)
API
1// Errors.
2type CorruptInputError int64
3func (e CorruptInputError) Error() string
4
5// Length helpers.
6func DecodedLen(n int) int
7func EncodedLen(n int) int
8
9// Byte slice encoding.
10func Encode(dst, src []byte) // uppercase
11func EncodeLower(dst, src []byte) // lowercase
12func EncodeToString(src []byte) string // uppercase
13func EncodeToStringLower(src []byte) string // lowercase
14func AppendEncode(dst, src []byte) []byte
15func AppendEncodeLower(dst, src []byte) []byte
16
17// Byte slice decoding. Case-insensitive; ignores \r and \n.
18func Decode(dst, src []byte) (n int, err error)
19func DecodeString(s string) ([]byte, error)
20func AppendDecode(dst, src []byte) ([]byte, error)
21
22// uint64 encoding.
23func PutUint64(id uint64) [13]byte // full, uppercase
24func PutUint64Lower(id uint64) [13]byte // full, lowercase
25func PutCompact(id uint64) []byte // 7 bytes if id < 2^34, else 13, lowercase
26func AppendCompact(id uint64, b []byte) []byte
27func Uint64(b []byte) (uint64, error) // accepts both compact (7) and full (13)
28
29// Streaming I/O.
30func NewEncoder(w io.Writer) io.WriteCloser
31func NewEncoderLower(w io.Writer) io.WriteCloser
32func NewDecoder(r io.Reader) io.Reader
Notes
- Alphabet:
0123456789ABCDEFGHJKMNPQRSTVWXYZ(noI,L,O,U). - Decoding is case-insensitive;
I/i/L/ldecode as1, andO/odecode as0. - The compact uint64 encoding preserves lexicographic order with numeric order, making encoded IDs suitable as ordered keys.
- The compact and full uint64 encodings are unambiguously distinguished by their first character:
0-findicates compact (7 bytes),g-zindicates full (13 bytes). - Values in
[0, 2^34)have BOTH a compact and a full encoding. Pick one scheme per key space and stick to it: mixing both for the same value breaks the lexicographic-order property.PutCompactrolls over from compact to full at2^34automatically, which is safe as long as everything in that space is generated the same way. - For sequential IDs, see
gno.land/p/nt/seqid/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.
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