README
¶
Fast UUID implementation for Go
This package provides a fast implementation for representing UUIDs, parsing and generating them. It also includes methods for marshalling and unmarshalling JSON as well as reading and storing them in a SQL database.
Installation
go get github.com/m4rw3r/uuid
Documentation
See http://godoc.org/github.com/m4rw3r/uuid or the embedded godoc in the source.
Documentation
¶
Overview ¶
Package uuid implements a fast representation of UUIDs (Universally Unique Identifiers) and integrates with JSON and SQL drivers.
This package supports reading of multiple formats of UUIDs, including but not limited to:
a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11
A0EEBC99-9C0B-4EF8-BB6D-6BB9BD380A11
{a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11}
a0eebc999c0b4ef8bb6d6bb9bd380a11
a0ee-bc99-9c0b-4ef8-bb6d-6bb9-bd38-0a11
{a0eebc99-9c0b4ef8-bb6d6bb9-bd380a11}
The parsing-speed of UUIDs in this package is achieved in several ways:
A lookup table converts hexadecimal digits to bytes.
Scanning and parsing is done in place without allocating anything.
Resulting bytes are written to the UUID as it is parsed. On parse errors this will leave the UUID only partially populated with data from the input string, leaving the rest of the UUID unmodified.
This package just ignores non-hexadecimal digits when scanning. This can cause some odd representations of hexadecimal data to be parsed as valid UUIDs, and longer strings like these will parse successfully:
a0eebc99,9c0b,4ef8,bb6d,6bb9bd380a11 a0eebc99This9cIs0b4eOKf8bb6d6bb9bdLOL380a11 a0-ee-bc-99-9c-0b-4e-f8-bb-6d-6b-b9-bd-38-0a-11
However, the hexadecimal digits MUST come in pairs, and the total number of bytes represented by them MUST equal 16, or it will generate a parse error. For example, invalid UUIDs like these will not parse:
a0eebc999-c0b-4ef8-bb6d-6bb9bd380a11 a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a111 a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a1111
All string-creating functions will generate UUIDs in the canonical format of:
a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11
Index ¶
- type ErrInvalidType
- type ErrNotJSONString
- type ErrTooLong
- type ErrTooShort
- type ErrUneven
- type NullUUID
- type ScanError
- type UUID
- func (u UUID) IsZero() bool
- func (u UUID) MarshalJSON() ([]byte, error)
- func (u UUID) MarshalText() ([]byte, error)
- func (u *UUID) ReadBytes(str []byte) error
- func (u *UUID) Scan(val interface{}) error
- func (u *UUID) SetString(str string) error
- func (u *UUID) SetZero()
- func (u UUID) String() string
- func (u *UUID) UnmarshalJSON(data []byte) error
- func (u *UUID) UnmarshalText(data []byte) error
- func (u UUID) Value() (driver.Value, error)
- func (u UUID) Version() int
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ErrInvalidType ¶
ErrInvalidType occurs when *UUID.Scan() does not receive a string.
func (ErrInvalidType) Error ¶
func (e ErrInvalidType) Error() string
type ErrNotJSONString ¶ added in v1.0.1
type ErrNotJSONString struct{}
ErrNotJSONString occurs when attempting to parse an UUID from a JSON string which is too short or is missing quotes.
func (ErrNotJSONString) Error ¶ added in v1.0.1
func (e ErrNotJSONString) Error() string
type ErrTooLong ¶
type ErrTooLong ScanError
ErrTooLong occurs when the supplied string contains more than the required number of hexadecimal characters to represent a UUID.
func (ErrTooLong) Error ¶
func (e ErrTooLong) Error() string
type ErrTooShort ¶
type ErrTooShort ScanError
ErrTooShort occurs when the supplied string does not contain enough hexadecimal characters to represent a UUID.
func (ErrTooShort) Error ¶
func (e ErrTooShort) Error() string
type ErrUneven ¶
type ErrUneven ScanError
ErrUneven occurs when a hexadecimal digit is not part of a pair, making it impossible to decode it to a byte.
type NullUUID ¶
NullUUID represents a UUID that may be null. NullUUID implements the Scanner interface so it can be used as a scan destination.
func (NullUUID) MarshalJSON ¶
MarshalJSON marshals a potentially null UUID into either a string- representation of the UUID or the null-constant depending on the Valid property.
func (NullUUID) MarshalText ¶
MarshalText marshals a potentially null UUID into either a string- representation of the UUID or the null-constant depending on the Valid property.
func (*NullUUID) Scan ¶
Scan scans a uuid or null from the given value. If the supplied value is nil, Valid will be set to false and the UUID will be zeroed.
func (*NullUUID) UnmarshalJSON ¶
UnmarshalJSON parses a potentially null UUID into a NullUUI instance. If the source is the null-constant ("null"), Valid is set to false, otherwise it will attempt to parse the given string into the UUID property of the NullUUID instance, setting Valid to true if no error is encountered. If an error is encountered, Valid is set to false.
func (*NullUUID) UnmarshalText ¶
UnmarshalText parses a potentially null UUID into a NullUUI instance. If the source is the null-constant ("null"), Valid is set to false, otherwise it will attempt to parse the given string into the UUID property of the NullUUID instance, setting Valid to true if no error is encountered. If an error is encountered, Valid is set to false.
type ScanError ¶
type ScanError struct {
// Scanned is the number of bytes of the source string which has been
// considered.
Scanned int
// Written is the number of decoded hexadecimal bytes which has
// been written to the UUID instance.
Written int
// Length is the length of the source string.
Length int
}
ScanError contains the scanner-state for when the error occurred.
type UUID ¶
type UUID [16]byte
UUID represents a Universally-Unique-Identifier.
func FromString ¶
FromString reads a UUID into a new UUID instance.
func MaybeFromString ¶
MaybeFromString reads a UUID into a new UUID instance, setting the instance to zero if it fails.
func MustFromString ¶
MustFromString reads a UUID into a new UUID instance, panicing on failure.
func (UUID) MarshalJSON ¶
MarshalJSON returns the string-representation of the UUID as a JSON-string.
func (UUID) MarshalText ¶
MarshalText returns the string-representation of the UUID as a byte-array.
func (*UUID) ReadBytes ¶
ReadBytes reads the supplied byte array of hexadecimal characters representing a UUID into the instance. On invalid UUID an error is returned and the UUID state will be undetermined. This function will ignore all non-hexadecimal digits.
func (*UUID) Scan ¶
Scan scans a uuid from the given interface instance. If scanning fails the state of the UUID is undetermined.
func (*UUID) SetString ¶
SetString reads the supplied string-representation of the UUID into the instance. On invalid UUID an error is returned and the UUID state will be undetermined. This function will ignore all non-hexadecimal digits.
func (UUID) String ¶
String returns the string representation of the UUID. This method returns the canonical representation of “xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx“.
func (*UUID) UnmarshalJSON ¶
UnmarshalJSON reads an UUID from a JSON-string into the UUID instance. If this fails the state of the UUID is undetermined.
func (*UUID) UnmarshalText ¶
UnmarshalText reads an UUID from a string into the UUID instance. If this fails the state of the UUID is undetermined.
Source Files