1 // Copyright 2019 The Go Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style
3 // license that can be found in the LICENSE file.
14 // Key is used as the identity of a Label.
15 // Keys are intended to be compared by pointer only, the name should be unique
16 // for communicating with external systems, but it is not required or enforced.
18 // Name returns the key name.
20 // Description returns a string that can be used to describe the value.
23 // Format is used in formatting to append the value of the label to the
25 // The formatter may use the supplied buf as a scratch area to avoid
27 Format(w io.Writer, buf []byte, l Label)
30 // Label holds a key and value pair.
31 // It is normally used when passing around lists of labels.
38 // Map is the interface to a collection of Labels indexed by key.
40 // Find returns the label that matches the supplied key.
44 // List is the interface to something that provides an iterable
46 // Iteration should start from 0 and continue until Valid returns false.
48 // Valid returns true if the index is within range for the list.
49 // It does not imply the label at that index will itself be valid.
51 // Label returns the label at the given index.
52 Label(index int) Label
55 // list implements LabelList for a list of Labels.
60 // filter wraps a LabelList filtering out specific labels.
66 // listMap implements LabelMap for a simple list of labels.
71 // mapChain implements LabelMap for a list of underlying LabelMap.
72 type mapChain struct {
76 // OfValue creates a new label from the key and value.
77 // This method is for implementing new key types, label creation should
78 // normally be done with the Of method of the key.
79 func OfValue(k Key, value interface{}) Label { return Label{key: k, untyped: value} }
81 // UnpackValue assumes the label was built using LabelOfValue and returns the value
82 // that was passed to that constructor.
83 // This method is for implementing new key types, for type safety normal
84 // access should be done with the From method of the key.
85 func (t Label) UnpackValue() interface{} { return t.untyped }
87 // Of64 creates a new label from a key and a uint64. This is often
88 // used for non uint64 values that can be packed into a uint64.
89 // This method is for implementing new key types, label creation should
90 // normally be done with the Of method of the key.
91 func Of64(k Key, v uint64) Label { return Label{key: k, packed: v} }
93 // Unpack64 assumes the label was built using LabelOf64 and returns the value that
94 // was passed to that constructor.
95 // This method is for implementing new key types, for type safety normal
96 // access should be done with the From method of the key.
97 func (t Label) Unpack64() uint64 { return t.packed }
99 // OfString creates a new label from a key and a string.
100 // This method is for implementing new key types, label creation should
101 // normally be done with the Of method of the key.
102 func OfString(k Key, v string) Label {
103 hdr := (*reflect.StringHeader)(unsafe.Pointer(&v))
106 packed: uint64(hdr.Len),
107 untyped: unsafe.Pointer(hdr.Data),
111 // UnpackString assumes the label was built using LabelOfString and returns the
112 // value that was passed to that constructor.
113 // This method is for implementing new key types, for type safety normal
114 // access should be done with the From method of the key.
115 func (t Label) UnpackString() string {
117 hdr := (*reflect.StringHeader)(unsafe.Pointer(&v))
118 hdr.Data = uintptr(t.untyped.(unsafe.Pointer))
119 hdr.Len = int(t.packed)
120 return *(*string)(unsafe.Pointer(hdr))
123 // Valid returns true if the Label is a valid one (it has a key).
124 func (t Label) Valid() bool { return t.key != nil }
126 // Key returns the key of this Label.
127 func (t Label) Key() Key { return t.key }
129 // Format is used for debug printing of labels.
130 func (t Label) Format(f fmt.State, r rune) {
132 io.WriteString(f, `nil`)
135 io.WriteString(f, t.Key().Name())
136 io.WriteString(f, "=")
138 t.Key().Format(f, buf[:0], t)
141 func (l *list) Valid(index int) bool {
142 return index >= 0 && index < len(l.labels)
145 func (l *list) Label(index int) Label {
146 return l.labels[index]
149 func (f *filter) Valid(index int) bool {
150 return f.underlying.Valid(index)
153 func (f *filter) Label(index int) Label {
154 l := f.underlying.Label(index)
155 for _, f := range f.keys {
163 func (lm listMap) Find(key Key) Label {
164 for _, l := range lm.labels {
172 func (c mapChain) Find(key Key) Label {
173 for _, src := range c.maps {
182 var emptyList = &list{}
184 func NewList(labels ...Label) List {
185 if len(labels) == 0 {
188 return &list{labels: labels}
191 func Filter(l List, keys ...Key) List {
195 return &filter{keys: keys, underlying: l}
198 func NewMap(labels ...Label) Map {
199 return listMap{labels: labels}
202 func MergeMaps(srcs ...Map) Map {
204 for _, src := range srcs {
206 nonNil = append(nonNil, src)
209 if len(nonNil) == 1 {
212 return mapChain{maps: nonNil}