README.md

 1# cford32
 2
 3```
 4package cford32 // import "gno.land/p/demo/cford32"
 5
 6Package cford32 implements a base32-like encoding/decoding package, with the
 7encoding scheme specified by Douglas Crockford.
 8
 9From the website, the requirements of said encoding scheme are to:
10
11  - Be human readable and machine readable.
12  - Be compact. Humans have difficulty in manipulating long strings of arbitrary
13    symbols.
14  - Be error resistant. Entering the symbols must not require keyboarding
15    gymnastics.
16  - Be pronounceable. Humans should be able to accurately transmit the symbols
17    to other humans using a telephone.
18
19This is slightly different from a simple difference in encoding table from
20the Go's stdlib `encoding/base32`, as when decoding the characters i I l L are
21parsed as 1, and o O is parsed as 0.
22
23This package additionally provides ways to encode uint64's efficiently, as well
24as efficient encoding to a lowercase variation of the encoding. The encodings
25never use paddings.
26
27# Uint64 Encoding
28
29Aside from lower/uppercase encoding, there is a compact encoding, allowing to
30encode all values in [0,2^34), and the full encoding, allowing all values in
31[0,2^64). The compact encoding uses 7 characters, and the full encoding uses 13
32characters. Both are parsed unambiguously by the Uint64 decoder.
33
34The compact encodings have the first character between ['0','f'], while the
35full encoding's first character ranges between ['g','z']. Practically, in your
36usage of the package, you should consider which one to use and stick with it,
37while considering that the compact encoding, once it reaches 2^34, automatically
38switches to the full encoding. The properties of the generated strings are still
39maintained: for instance, any two encoded uint64s x,y consistently generated
40with the compact encoding, if the numeric value is x < y, will also be x < y in
41lexical ordering. However, values [0,2^34) have a "double encoding", which if
42mixed together lose the lexical ordering property.
43
44The Uint64 encoding is most useful for generating string versions of Uint64 IDs.
45Practically, it allows you to retain sleek and compact IDs for your application
46for the first 2^34 (>17 billion) entities, while seamlessly rolling over to the
47full encoding should you exceed that. You are encouraged to use it unless you
48have a requirement or preferences for IDs consistently being always the same
49size.
50
51To use the cford32 encoding for IDs, you may want to consider using package
52gno.land/p/demo/seqid.
53
54[specified by Douglas Crockford]: https://www.crockford.com/base32.html
55
56func AppendCompact(id uint64, b []byte) []byte
57func AppendDecode(dst, src []byte) ([]byte, error)
58func AppendEncode(dst, src []byte) []byte
59func AppendEncodeLower(dst, src []byte) []byte
60func Decode(dst, src []byte) (n int, err error)
61func DecodeString(s string) ([]byte, error)
62func DecodedLen(n int) int
63func Encode(dst, src []byte)
64func EncodeLower(dst, src []byte)
65func EncodeToString(src []byte) string
66func EncodeToStringLower(src []byte) string
67func EncodedLen(n int) int
68func NewDecoder(r io.Reader) io.Reader
69func NewEncoder(w io.Writer) io.WriteCloser
70func NewEncoderLower(w io.Writer) io.WriteCloser
71func PutCompact(id uint64) []byte
72func PutUint64(id uint64) [13]byte
73func PutUint64Lower(id uint64) [13]byte
74func Uint64(b []byte) (uint64, error)
75type CorruptInputError int64
76```