key

package
v0.5.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 19, 2021 License: MIT Imports: 9 Imported by: 14

Documentation

Overview

Package key provides the Key interface and the KeySlice type, along with some utility functions around key.

Index

Constants

This section is empty.

Variables

View Source 
var (
	EmptyBytesKey = NewBytesKey([]byte{})

	ErrNotBytesKey = errors.New("argument is not of type BytesKey")
)
View Source 
var (
	EmptyStrKey = RawStrKey("/")

	ErrNotStrKey = errors.New("argument is not of type StrKey")
)
View Source 
var (
	ErrKeyTypeNotSupported = errors.New("key type not supported")
)

Functions

func Compare 

func Compare(a, b Key) int

Compare returns an integer comparing two Keys lexicographically. The result will be 0 if a.Equal(b), -1 if a.Less(b), and +1 if b.Less(a).

func NamespaceType 

func NamespaceType(namespace string) string

NamespaceType is the first component of a namespace. `foo` in `foo:bar`

func NamespaceValue 

func NamespaceValue(namespace string) string

NamespaceValue returns the last component of a namespace. `baz` in `f:b:baz`

Types

type BytesKey 

type BytesKey struct {
	// contains filtered or unexported fields
}

BytesKey is a Key implementation backed by byte slice. It could improve performance in some cases compared to StrKey by preventing type conversion and reducing key size.

func BytesKeyWithNamespaces 

func BytesKeyWithNamespaces(ns [][]byte) BytesKey

KeyWithNamespaces constructs a key out of a namespace slice.

func NewBytesKey 

func NewBytesKey(bytes []byte) BytesKey

NewBytesKey constructs a BytesKey from byte slice.

func NewBytesKeyFromString 

func NewBytesKeyFromString(s string) BytesKey

NewBytesKeyFromString constructs a BytesKey from s.

func NewBytesKeyFromStringUnsafe added in v0.4.6 

func NewBytesKeyFromStringUnsafe(s string) BytesKey

NewBytesKeyFromStringUnsafe constructs a BytesKey from `s` using "unsafe" package to avoid copying. Be cautious that `s` should be discarded right after calling this method because its value may change.

func (BytesKey) Bytes 

func (k BytesKey) Bytes() []byte

Bytes returns a copy of the underlying byte slice of Key.

func (BytesKey) BytesUnsafe added in v0.4.6 

func (k BytesKey) BytesUnsafe() []byte

Bytes returns the underlying byte slice of Key. You should probably not modify the returned byte slice as it may have unintended side effects.

func (BytesKey) Child 

func (k BytesKey) Child(k2 Key) Key

Child returns the `child` Key of this Key. 

NewBytesKey({{BYTES1}}).Child(NewBytesKey({{BYTES2}}))
NewBytesKey({{BYTES1 || BYTES2}})

Panic if `k2` is not a BytesKey.

func (BytesKey) ChildBytes 

func (k BytesKey) ChildBytes(b []byte) Key

ChildBytes returns the `child` Key of this Key -- bytes helper. 

NewBytesKey({{BYTES1}}).Child({{BYTES2}}))
NewBytesKey({{BYTES1 || BYTES2}})

func (BytesKey) Equal 

func (k BytesKey) Equal(k2 Key) bool

Equal checks equality of two keys

func (BytesKey) HasPrefix 

func (k BytesKey) HasPrefix(prefix Key) bool

HasPrefix returns whether this key contains another as a prefix (including equals). Panic if `prefix` is not a BytesKey.

func (BytesKey) HasSuffix 

func (k BytesKey) HasSuffix(suffix Key) bool

HasPrefix returns whether this key contains another as a suffix (including equals). Panic if `suffix` is not a BytesKey.

func (BytesKey) IsAncestorOf 

func (k BytesKey) IsAncestorOf(other Key) bool

IsAncestorOf returns whether this key is a prefix of `other` (excluding equals). 

NewBytesKey({{BYTES1}}).IsAncestorOf(NewBytesKey({{BYTES1 || BYTES2}}))
true

Panic if `other` is not a BytesKey.

func (BytesKey) IsDescendantOf 

func (k BytesKey) IsDescendantOf(other Key) bool

IsDescendantOf returns whether this key contains another as a prefix (excluding equals). 

NewBytesKey({{BYTES1 || BYTES2}}).IsDescendantOf({{BYTES1}})
true

Panic if `other` is not a BytesKey.

func (BytesKey) KeyType 

func (k BytesKey) KeyType() KeyType

KeyType returns the key type (KeyTypeBytes)

func (BytesKey) Less 

func (k BytesKey) Less(k2 Key) bool

Less checks whether this key is sorted lower than another. Panic if `k2` is not a BytesKey.

func (BytesKey) MarshalJSON 

func (k BytesKey) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface, keys are represented as base64-encoded JSON string

func (BytesKey) String 

func (k BytesKey) String() string

String gets the string value of Key

func (BytesKey) StringUnsafe added in v0.4.6 

func (k BytesKey) StringUnsafe() string

StringUnsafe gets the string value of Key using "unsafe" package to avoid copying. Be cautious that the string returned may change if the underlying byte slice is modified elsewhere, e.g. after being returned from BytesUnsafe.

func (BytesKey) TrimPrefix 

func (k BytesKey) TrimPrefix(prefix Key) Key

TrimPrefix returns a new key equals to this key without the provided leading prefix key. If `s` doesn't start with prefix, this key is returned unchanged. Panic if `prefix` is not a BytesKey.

func (BytesKey) TrimSuffix 

func (k BytesKey) TrimSuffix(suffix Key) Key

TrimSuffix returns a new key equals to this key without the provided trailing suffix key. If `s` doesn't end with suffix, this key is returned unchanged. Panic if `suffix` is not a BytesKey.

func (*BytesKey) UnmarshalJSON 

func (k *BytesKey) UnmarshalJSON(data []byte) (err error)

UnmarshalJSON implements the json.Unmarshaler interface, keys will decode base64-encoded JSON string to raw bytes

type Key 

type Key interface {
	fmt.Stringer
	// KeyType returns the key type.
	KeyType() KeyType
	// StringUnsafe returns the string value of Key.
	// It's the same as String for StrKey.
	StringUnsafe() string
	// Bytes returns the value of Key as a []byte.
	Bytes() []byte
	// Bytes returns the value of Key as a []byte. You should probably not
	// modify the returned byte slice as it may have unintended side effects.
	BytesUnsafe() []byte
	// Equal checks equality of two keys.
	Equal(k2 Key) bool
	// Less checks whether this key is sorted lower than another.
	Less(k2 Key) bool
	// Child returns the `child` Key of this Key.
	Child(k2 Key) Key
	// IsAncestorOf returns whether this key is a prefix of `other`.
	IsAncestorOf(other Key) bool
	// IsDescendantOf returns whether this key contains another as a prefix (excluding equals).
	IsDescendantOf(other Key) bool
	// HasPrefix returns whether this key contains another as a prefix (including equals).
	HasPrefix(prefix Key) bool
	// HasPrefix returns whether this key contains another as a suffix (including equals).
	HasSuffix(suffix Key) bool
	// TrimPrefix returns a new key equals to this key without the provided leading prefix key.
	// If s doesn't start with prefix, this key is returned unchanged.
	TrimPrefix(prefix Key) Key
	// TrimSuffix returns a new key equals to this key without the provided trailing suffix key.
	// If s doesn't end with suffix, this key is returned unchanged.
	TrimSuffix(suffix Key) Key
	// MarshalJSON implements the json.Marshaler interface,
	// keys are represented as JSON strings.
	MarshalJSON() ([]byte, error)
}

A Key represents the unique identifier of an object. Keys are meant to be unique across a system. There are two Key implementations: StrKey backed by string and BytesKey backed by byte slice.

func Clean 

func Clean(k Key) Key

Clean up a StrKey, using path.Clean, no-op for BytesKey.

func EmptyKeyFromType added in v0.4.7 

func EmptyKeyFromType(keyType KeyType) Key

EmptyKeyFromType returns the empty key of keyType. for StrKey: RawStrKey("/") for BytesKey: NewBytesKey([]byte{})

func NewKeyFromTypeAndBytes added in v0.4.8 

func NewKeyFromTypeAndBytes(keyType KeyType, bytes []byte) Key

NewKeyFromTypeAndBytes constructs a Key of keyType from bytes.

func NewKeyFromTypeAndString added in v0.4.6 

func NewKeyFromTypeAndString(keyType KeyType, s string) Key

NewKeyFromTypeAndString constructs a Key of keyType from s.

func QueryKeyFromTypeAndString added in v0.4.6 

func QueryKeyFromTypeAndString(keyType KeyType, s string) Key

QueryKeyFromTypeAndString constructs a Key of keyType from s. For StrKey, is uses QueryStrKey instead of NewStrKey.

func RandomBytesKey 

func RandomBytesKey() Key

RandomBytesKey returns a randomly (uuid) generated key. 

RandomBytesKey()
NewBytesKey([]byte("f98719ea086343f7b71f32ea9d9d521d"))

func RandomKey deprecated 

func RandomKey() Key

Deprecated: RandomKey just proxy calls to RandomStrKey for backward compatibility.

func RandomStrKey 

func RandomStrKey() Key

RandomStrKey returns a randomly (uuid) generated key. 

RandomStrKey()
NewStrKey("/f98719ea086343f7b71f32ea9d9d521d")

func StrsToBytesKeys 

func StrsToBytesKeys(strs []string) []Key

func StrsToKeys 

func StrsToKeys(strs []string) []Key

StrsToKeys is an alias that proxies calls to StrsToStrKeys for backwards compatibility.

func StrsToQueryKeys 

func StrsToQueryKeys(strs []string) []Key

func StrsToStrKeys added in v0.4.6 

func StrsToStrKeys(strs []string) []Key

func TypeAndStrsToKeys added in v0.4.6 

func TypeAndStrsToKeys(keyType KeyType, strs []string) []Key

TypeAndStrsToKeys constructs a slice of Key of keyType from strs.

func TypeAndStrsToQueryKeys added in v0.4.6 

func TypeAndStrsToQueryKeys(keyType KeyType, strs []string) []Key

type KeySlice 

type KeySlice []Key

KeySlice attaches the methods of sort.Interface to []Key, sorting in increasing order.

func (KeySlice) Join 

func (p KeySlice) Join() Key

Join Joins keys in the KeySlice into a single key, returns EmptyStrKey if slice is empty.

func (KeySlice) Len 

func (p KeySlice) Len() int

func (KeySlice) Less 

func (p KeySlice) Less(i, j int) bool

func (KeySlice) Swap 

func (p KeySlice) Swap(i, j int)

type KeyType 

type KeyType uint8
const (
	// Key backed by string
	KeyTypeString KeyType = iota
	// Key backed by byte slice
	KeyTypeBytes
)

func (KeyType) Available added in v0.4.6 

func (h KeyType) Available() bool

Available reports whether the given key type is avialable.

type StrKey 

type StrKey struct {
	// contains filtered or unexported fields
}

A StrKey represents the unique identifier of an object. StrKeys are meant to be unique across a system.

Our Key scheme is inspired by file systems and Google App Engine key model. StrKeys are hierarchical, incorporating more and more specific namespaces. Thus keys can be deemed 'children' or 'ancestors' of other keys:: 

StrKey("/Comedy")
StrKey("/Comedy/MontyPython")

Also, every namespace can be parametrized to embed relevant object information. For example, the StrKey `name` (most specific namespace) could include the object type:: 

StrKey("/Comedy/MontyPython/Actor:JohnCleese")
StrKey("/Comedy/MontyPython/Sketch:CheeseShop")
StrKey("/Comedy/MontyPython/Sketch:CheeseShop/Character:Mousebender")

func KeyWithNamespaces 

func KeyWithNamespaces(ns []string) StrKey

KeyWithNamespaces constructs a key out of a namespace slice.

func NewKey deprecated 

func NewKey(s string) StrKey

Deprecated: NewKey just proxies calls to NewStrKey for backward compatibility.

func NewStrKey 

func NewStrKey(s string) StrKey

NewStrKey constructs a StrKey from string. it will clean the value.

func NewStrKeyFromBytes added in v0.4.8 

func NewStrKeyFromBytes(bytes []byte) StrKey

func QueryStrKey 

func QueryStrKey(s string) StrKey

QueryStrKey creates a new StrKey without safety checking the input, intended to be used for query. Use with care.

func RawKey deprecated 

func RawKey(s string) StrKey

Deprecated: RawKey just proxies calls to RawStrKey for backward compatibility.

func RawStrKey 

func RawStrKey(s string) StrKey

RawStrKey creates a new StrKey without safety checking the input. Use with care.

func (StrKey) BaseNamespace 

func (k StrKey) BaseNamespace() string

BaseNamespace returns the "base" namespace of this key (path.Base(filename)) 

NewStrKey("/Comedy/MontyPython/Actor:JohnCleese").BaseNamespace()
"Actor:JohnCleese"

func (StrKey) Bytes 

func (k StrKey) Bytes() []byte

Bytes gets the value of Key as a []byte

func (StrKey) BytesUnsafe added in v0.4.6 

func (k StrKey) BytesUnsafe() []byte

BytesUnsafe gets the value of Key as a []byte using "unsafe" package to avoid copying. You should probably not modify the returned byte slice as it may have unintended side effects.

func (StrKey) Child 

func (k StrKey) Child(k2 Key) Key

Child returns the `child` Key of this Key. 

NewStrKey("/Comedy/MontyPython").Child(NewStrKey("Actor:JohnCleese"))
NewStrKey("/Comedy/MontyPython/Actor:JohnCleese")

Panic if `k2` is not a StrKey.

func (StrKey) ChildStrKey 

func (k StrKey) ChildStrKey(k2 Key) StrKey

ChildStrKey is the same as Child but returns a StrKey.

func (StrKey) ChildString 

func (k StrKey) ChildString(s string) Key

ChildString returns the `child` Key of this Key -- string helper. 

NewStrKey("/Comedy/MontyPython").ChildString("Actor:JohnCleese")
NewStrKey("/Comedy/MontyPython/Actor:JohnCleese")

func (StrKey) ChildStringStrKey 

func (k StrKey) ChildStringStrKey(s string) StrKey

ChildStringStrKey is the same as ChildString but returns a StrKey.

func (*StrKey) Clean 

func (k *StrKey) Clean()

Clean up a StrKey, using path.Clean.

func (StrKey) Equal 

func (k StrKey) Equal(k2 Key) bool

Equal checks equality of two keys

func (StrKey) HasPrefix 

func (k StrKey) HasPrefix(prefix Key) bool

HasPrefix returns whether this key contains another as a prefix (including equals). Panic if `prefix` is not a StrKey.

func (StrKey) HasSuffix 

func (k StrKey) HasSuffix(suffix Key) bool

HasPrefix returns whether this key contains another as a suffix (including equals). Panic if `suffix` is not a StrKey.

func (StrKey) Instance 

func (k StrKey) Instance(s string) Key

Instance returns an "instance" of this type key (appends value to namespace). 

NewStrKey("/Comedy/MontyPython/Actor").Instance("JohnClesse")
NewStrKey("/Comedy/MontyPython/Actor:JohnCleese")

func (StrKey) IsAncestorOf 

func (k StrKey) IsAncestorOf(other Key) bool

IsAncestorOf returns whether this key is a prefix of `other` (excluding equals). 

NewStrKey("/Comedy").IsAncestorOf("/Comedy/MontyPython")
true

Panic if `other` is not a StrKey.

func (StrKey) IsDescendantOf 

func (k StrKey) IsDescendantOf(other Key) bool

IsDescendantOf returns whether this key contains another as a prefix (excluding equals). 

NewStrKey("/Comedy/MontyPython").IsDescendantOf("/Comedy")
true

Panic if `other` is not a StrKey.

func (StrKey) IsTopLevel 

func (k StrKey) IsTopLevel() bool

IsTopLevel returns whether this key has only one namespace.

func (StrKey) KeyType 

func (k StrKey) KeyType() KeyType

KeyType returns the key type (KeyTypeString)

func (StrKey) Less 

func (k StrKey) Less(k2 Key) bool

Less checks whether this key is sorted lower than another. Panic if `k2` is not a StrKey.

func (StrKey) List 

func (k StrKey) List() []string

List returns the `list` representation of this Key. 

NewStrKey("/Comedy/MontyPython/Actor:JohnCleese").List()
["Comedy", "MontyPythong", "Actor:JohnCleese"]

func (StrKey) MarshalJSON 

func (k StrKey) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface, keys are represented as JSON strings

func (StrKey) Name 

func (k StrKey) Name() string

Name returns the "name" of this key (field of last namespace). 

NewStrKey("/Comedy/MontyPython/Actor:JohnCleese").Name()
"JohnCleese"

func (StrKey) Namespaces 

func (k StrKey) Namespaces() []string

Namespaces returns the `namespaces` making up this Key. 

NewStrKey("/Comedy/MontyPython/Actor:JohnCleese").Namespaces()
["Comedy", "MontyPython", "Actor:JohnCleese"]

func (StrKey) Parent 

func (k StrKey) Parent() StrKey

Parent returns the `parent` Key of this Key. 

NewStrKey("/Comedy/MontyPython/Actor:JohnCleese").Parent()
NewStrKey("/Comedy/MontyPython")

func (StrKey) Path 

func (k StrKey) Path() Key

Path returns the "path" of this key (parent + type). 

NewStrKey("/Comedy/MontyPython/Actor:JohnCleese").Path()
NewStrKey("/Comedy/MontyPython/Actor")

func (StrKey) Reverse 

func (k StrKey) Reverse() Key

Reverse returns the reverse of this Key. 

NewStrKey("/Comedy/MontyPython/Actor:JohnCleese").Reverse()
NewStrKey("/Actor:JohnCleese/MontyPython/Comedy")

func (StrKey) String 

func (k StrKey) String() string

String returns the string value of Key

func (StrKey) StringUnsafe added in v0.4.6 

func (k StrKey) StringUnsafe() string

StringUnsafe is the same as String

func (StrKey) TrimPrefix 

func (k StrKey) TrimPrefix(prefix Key) Key

TrimPrefix returns a new key equals to this key without the provided leading prefix key. If s doesn't start with prefix, this key is returned unchanged. Panic if `prefix` is not a StrKey.

func (StrKey) TrimSuffix 

func (k StrKey) TrimSuffix(suffix Key) Key

TrimSuffix returns a new key equals to this key without the provided trailing suffix key. If s doesn't end with suffix, this key is returned unchanged. Panic if `suffix` is not a StrKey.

func (StrKey) Type 

func (k StrKey) Type() string

Type returns the "type" of this key (value of last namespace). 

NewStrKey("/Comedy/MontyPython/Actor:JohnCleese").Type()
"Actor"

func (*StrKey) UnmarshalJSON 

func (k *StrKey) UnmarshalJSON(data []byte) error

UnmarshalJSON implements the json.Unmarshaler interface, keys will parse any value specified as a key to a string

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.