package ulid
Import Path
github.com/oklog/ulid/v2 (on go.dev)
Dependency Relation
imports 11 packages, and imported by one package
Involved Source Files
ulid.go
Package-Level Type Names (total 4)
LockedMonotonicReader wraps a MonotonicReader with a sync.Mutex for
safe concurrent use.
MonotonicReader MonotonicReader
MonotonicRead synchronizes calls to the wrapped MonotonicReader.
( LockedMonotonicReader) Read(p []byte) (n int, err error)
*LockedMonotonicReader : MonotonicReader
LockedMonotonicReader : io.Reader
MonotonicEntropy is an opaque type that provides monotonic entropy.
Reader io.Reader
MonotonicRead implements the MonotonicReader interface.
( MonotonicEntropy) Read(p []byte) (n int, err error)
*MonotonicEntropy : MonotonicReader
MonotonicEntropy : io.Reader
func Monotonic(entropy io.Reader, inc uint64) *MonotonicEntropy
MonotonicReader is an interface that should yield monotonically increasing
entropy into the provided slice for all calls with the same ms parameter. If
a MonotonicReader is provided to the New constructor, its MonotonicRead
method will be used instead of Read.
( MonotonicReader) MonotonicRead(ms uint64, p []byte) error
( MonotonicReader) Read(p []byte) (n int, err error)
*LockedMonotonicReader
*MonotonicEntropy
MonotonicReader : io.Reader
An ULID is a 16 byte Universally Unique Lexicographically Sortable Identifier
The components are encoded as 16 octets.
Each component is encoded with the MSB first (network byte order).
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 32_bit_uint_time_high |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 16_bit_uint_time_low | 16_bit_uint_random |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 32_bit_uint_random |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 32_bit_uint_random |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Bytes returns bytes slice representation of ULID.
Compare returns an integer comparing id and other lexicographically.
The result will be 0 if id==other, -1 if id < other, and +1 if id > other.
Entropy returns the entropy from the ULID.
MarshalBinary implements the encoding.BinaryMarshaler interface by
returning the ULID as a byte slice.
MarshalBinaryTo writes the binary encoding of the ULID to the given buffer.
ErrBufferSize is returned when the len(dst) != 16.
MarshalText implements the encoding.TextMarshaler interface by
returning the string encoded ULID.
MarshalTextTo writes the ULID as a string to the given buffer.
ErrBufferSize is returned when the len(dst) != 26.
Scan implements the sql.Scanner interface. It supports scanning
a string or byte slice.
SetEntropy sets the ULID entropy to the passed byte slice.
ErrDataSize is returned if len(e) != 10.
SetTime sets the time component of the ULID to the given Unix time
in milliseconds.
String returns a lexicographically sortable string encoded ULID
(26 characters, non-standard base 32) e.g. 01AN4Z07BY79KA1307SR9X4MV3.
Format: tttttttttteeeeeeeeeeeeeeee where t is time and e is entropy.
Time returns the Unix time in milliseconds encoded in the ULID.
Use the top level Time function to convert the returned value to
a time.Time.
UnmarshalBinary implements the encoding.BinaryUnmarshaler interface by
copying the passed data and converting it to an ULID. ErrDataSize is
returned if the data length is different from ULID length.
UnmarshalText implements the encoding.TextUnmarshaler interface by
parsing the data as string encoded ULID.
ErrDataSize is returned if the len(v) is different from an encoded
ULID's length. Invalid encodings produce undefined ULIDs.
Value implements the sql/driver.Valuer interface, returning the ULID as a
slice of bytes, by invoking MarshalBinary. If your use case requires a string
representation instead, you can create a wrapper type that calls String()
instead.
type stringValuer ulid.ULID
func (v stringValuer) Value() (driver.Value, error) {
return ulid.ULID(v).String(), nil
}
// Example usage.
db.Exec("...", stringValuer(id))
All valid ULIDs, including zero-value ULIDs, return a valid Value with a nil
error. If your use case requires zero-value ULIDs to return a non-nil error,
you can create a wrapper type that special-cases this behavior.
var zeroValueULID ulid.ULID
type invalidZeroValuer ulid.ULID
func (v invalidZeroValuer) Value() (driver.Value, error) {
if ulid.ULID(v).Compare(zeroValueULID) == 0 {
return nil, fmt.Errorf("zero value")
}
return ulid.ULID(v).Value()
}
// Example usage.
db.Exec("...", invalidZeroValuer(id))
ULID : github.com/apache/arrow-go/v18/internal/hashing.ByteSlice
*ULID : database/sql.Scanner
ULID : database/sql/driver.Valuer
ULID : encoding.BinaryMarshaler
*ULID : encoding.BinaryUnmarshaler
ULID : encoding.TextMarshaler
*ULID : encoding.TextUnmarshaler
ULID : expvar.Var
ULID : fmt.Stringer
func Make() (id ULID)
func MustNew(ms uint64, entropy io.Reader) ULID
func MustParse(ulid string) ULID
func MustParseStrict(ulid string) ULID
func New(ms uint64, entropy io.Reader) (id ULID, err error)
func Parse(ulid string) (id ULID, err error)
func ParseStrict(ulid string) (id ULID, err error)
func ULID.Compare(other ULID) int
Package-Level Functions (total 13)
DefaultEntropy returns a thread-safe per process monotonically increasing
entropy source.
Make returns an ULID with the current time in Unix milliseconds and
monotonically increasing entropy for the same millisecond.
It is safe for concurrent use, leveraging a sync.Pool underneath for minimal
contention.
MaxTime returns the maximum Unix time in milliseconds that
can be encoded in an ULID.
Monotonic returns an entropy source that is guaranteed to yield
strictly increasing entropy bytes for the same ULID timestamp.
On conflicts, the previous ULID entropy is incremented with a
random number between 1 and `inc` (inclusive).
The provided entropy source must actually yield random bytes or else
monotonic reads are not guaranteed to terminate, since there isn't
enough randomness to compute an increment number.
When `inc == 0`, it'll be set to a secure default of `math.MaxUint32`.
The lower the value of `inc`, the easier the next ULID within the
same millisecond is to guess. If your code depends on ULIDs having
secure entropy bytes, then don't go under this default unless you know
what you're doing.
The returned type isn't safe for concurrent use.
MustNew is a convenience function equivalent to New that panics on failure
instead of returning an error.
MustParse is a convenience function equivalent to Parse that panics on failure
instead of returning an error.
MustParseStrict is a convenience function equivalent to ParseStrict that
panics on failure instead of returning an error.
New returns an ULID with the given Unix milliseconds timestamp and an
optional entropy source. Use the Timestamp function to convert
a time.Time to Unix milliseconds.
ErrBigTime is returned when passing a timestamp bigger than MaxTime.
Reading from the entropy source may also return an error.
Safety for concurrent use is only dependent on the safety of the
entropy source.
Now is a convenience function that returns the current
UTC time in Unix milliseconds. Equivalent to:
Timestamp(time.Now().UTC())
Parse parses an encoded ULID, returning an error in case of failure.
ErrDataSize is returned if the len(ulid) is different from an encoded
ULID's length. Invalid encodings produce undefined ULIDs. For a version that
returns an error instead, see ParseStrict.
ParseStrict parses an encoded ULID, returning an error in case of failure.
It is like Parse, but additionally validates that the parsed ULID consists
only of valid base32 characters. It is slightly slower than Parse.
ErrDataSize is returned if the len(ulid) is different from an encoded
ULID's length. Invalid encodings return ErrInvalidCharacters.
Time converts Unix milliseconds in the format
returned by the Timestamp function to a time.Time.
Timestamp converts a time.Time to Unix milliseconds.
Because of the way ULID stores time, times from the year
10889 produces undefined results.
Package-Level Variables (total 7)
ErrBigTime is returned when constructing an ULID with a time that is larger
than MaxTime.
ErrBufferSize is returned when marshalling ULIDs to a buffer of insufficient
size.
ErrDataSize is returned when parsing or unmarshaling ULIDs with the wrong
data size.
ErrInvalidCharacters is returned when parsing or unmarshaling ULIDs with
invalid Base32 encodings.
ErrMonotonicOverflow is returned by a Monotonic entropy source when
incrementing the previous ULID's entropy bytes would result in overflow.
ErrOverflow is returned when unmarshaling a ULID whose first character is
larger than 7, thereby exceeding the valid bit depth of 128.
ErrScanValue is returned when the value passed to scan cannot be unmarshaled
into the ULID.
Package-Level Constants (total 2)
EncodedSize is the length of a text encoded ULID.
Encoding is the base 32 encoding alphabet used in ULID strings.
 |
The pages are generated with Golds v0.8.2. (GOOS=linux GOARCH=amd64) Golds is a Go 101 project developed by Tapir Liu. PR and bug reports are welcome and can be submitted to the issue list. Please follow @zigo_101 (reachable from the left QR code) to get the latest news of Golds. |