func FromBinary
FromBinary creates a new ID from the given string, expected to be a binary big-endian encoding of an ID (such as that of ID.Binary). The second return value is true if the conversion was successful.
v0 source pure
v0 - Unaudited: This is an initial version that has not yet been formally audited. A fully audited version will be pu...
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.
seqid - Sequential IDs
Sequential ID generator producing ordered binary and string representations suitable for use as AVL tree keys. String IDs use cford32's compact encoding and preserve lexicographic ordering.
Usage
1import (
2 "gno.land/p/nt/avl/v0"
3 "gno.land/p/nt/seqid/v0"
4)
5
6var (
7 id seqid.ID
8 users avl.Tree
9)
10
11func NewUser(name string) {
12 user := &User{Name: name}
13
14 // String() is human-friendly and preserves ordering.
15 users.Set(id.Next().String(), user)
16
17 // Or persist the binary form as a fixed-width 8-byte AVL key.
18 users.Set(id.Next().Binary(), user)
19}
20
21// Recover an ID from user input (case-insensitive, sanitized).
22func Lookup(raw string) (seqid.ID, error) {
23 return seqid.FromString(raw)
24}
API
1// An ID is a sequential ID. The zero value is valid; the first
2// Next() call returns 1.
3type ID uint64
4
5// Next advances the ID and returns the new value. Panics on overflow.
6func (i *ID) Next() ID
7
8// TryNext is like Next but returns false instead of panicking on overflow.
9func (i *ID) TryNext() (ID, bool)
10
11// Binary returns a fixed 8-byte big-endian encoding of the ID, suitable
12// as an AVL key. Lexicographic order matches numeric order.
13func (i ID) Binary() string
14
15// String returns the cford32 compact encoding of the ID: 7 bytes for
16// IDs in [0, 2^34), 13 bytes after that. Lexicographic order matches
17// numeric order across the rollover.
18func (i ID) String() string
19
20// FromBinary parses a value produced by Binary.
21func FromBinary(b string) (ID, bool)
22
23// FromString parses a cford32-encoded ID. Case-insensitive; maps
24// I/L to 1 and O to 0. Always re-encode user input via FromString
25// then String() before using it as a key.
26func FromString(b string) (ID, error)
Notes
Binary()is the cheapest and most compact key (8 bytes, fixed width). Prefer it for internal storage. The keys work with anyITree(gno.land/p/nt/avl/v0orgno.land/p/nt/bptree/v0); their monotonic order suits bptree's append path especially well.String()is human-friendly and URL-safe; use it for IDs surfaced to users.- Because cford32 accepts multiple spellings for the same value, always normalize external input through
FromStringthenString()before using it as a lookup key.
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 seqid provides a simple way to have sequential IDs which will be ordered correctly when inserted in an AVL tree.
Package seqid provides a simple way to have sequential IDs which will be ordered correctly when inserted in an AVL tree.
Sample usage:
2
func FromString
FromString creates a new ID from the given string, expected to be a string representation using cford32, such as that returned by ID.String.
The encoding scheme used by cford32 allows the same ID to have many different representations (though the one returned by ID.String is only one, deterministic and safe to be used in AVL). The encoding scheme is "human-centric" and is thus case insensitive, and maps some ambiguous characters to be the same, ie. L = I = 1, O = 0. For this reason, when parsing user input to retrieve a key (encoded as a string), always sanitize it first using FromString, then run String(), instead of using the user's input directly.
1
type ID
identAn ID is a simple sequential ID generator.
Methods on ID
func Binary
method on IDBinary returns a big-endian binary representation of the ID, suitable to be used as an AVL key.
func Next
method on IDNext advances the ID i. It will panic if increasing ID would overflow.
func String
method on IDString encodes i using cford32's compact encoding. For more information, see the documentation for package gno.land/p/nt/cford32/v0.
The result of String will be a 7-byte string for IDs [0,2^34), and a 13-byte string for all values following that. All generated string IDs follow the same lexicographic order as their number values; that is, for any two IDs (x, y) such that x < y, x.String() < y.String(). As such, this string representation is suitable to be used as an AVL key.
func TryNext
method on IDTryNext increases i by 1 and returns its value. It returns true if successful, or false if the increment would result in an overflow.
2
- encoding/binary stdlib
- gno.land/p/nt/cford32/v0 package