1 package ldcontext 2 3 // New creates a Context with a Kind of [DefaultKind] and the specified key. 4 // 5 // To specify additional properties, use [NewBuilder]. To create a multi-context, use 6 // [NewMulti] or [NewMultiBuilder]. To create a single Context of a different kind than 7 // [DefaultKind], use [NewWithKind]; New is simply a shortcut for calling NewWithKind(DefaultKind, key). 8 func New(key string) Context { 9 return NewWithKind(DefaultKind, key) 10 } 11 12 // NewWithKind creates a Context with only the Kind and Key properties specified. 13 // 14 // To specify additional properties, use [NewBuilder]. To create a multi-context, use 15 // [NewMulti] or [NewMultiBuilder]. As a shortcut if the Kind is [DefaultKind], you can 16 // use [New]. 17 func NewWithKind(kind Kind, key string) Context { 18 // Here we'll use Builder rather than directly constructing the Context struct. That 19 // allows us to take advantage of logic in Builder like the setting of FullyQualifiedKey. 20 // We avoid the heap allocation overhead of NewBuilder by declaring a Builder locally. 21 var b Builder 22 b.Kind(kind) 23 b.Key(key) 24 return b.Build() 25 } 26 27 // NewMulti creates a multi-context out of the specified Contexts. 28 // 29 // To create a single [Context], use [New], [NewWithKind], or [NewBuilder]. 30 // 31 // For the returned Context to be valid, the contexts list must not be empty, and all of its 32 // elements must be valid Contexts. Otherwise, the returned Context will be invalid as reported 33 // by [Context.Err]. 34 // 35 // If only one context parameter is given, NewMulti returns that same context. 36 // 37 // If one of the nested contexts is a multi-context, this is exactly equivalent to adding each 38 // of the individual contexts from it separately. For instance, in the following example, 39 // "multi1" and "multi2" end up being exactly the same: 40 // 41 // c1 := ldcontext.NewWithKind("kind1", "key1") 42 // c2 := ldcontext.NewWithKind("kind2", "key2") 43 // c3 := ldcontext.NewWithKind("kind3", "key3") 44 // 45 // multi1 := ldcontext.NewMulti(c1, c2, c3) 46 // 47 // c1plus2 := ldcontext.NewMulti(c1, c2) 48 // multi2 := ldcontext.NewMulti(c1plus2, c3) 49 func NewMulti(contexts ...Context) Context { 50 // Same rationale as for New/NewWithKey of using the builder instead of constructing directly. 51 var m MultiBuilder 52 for _, c := range contexts { 53 m.Add(c) 54 } 55 return m.Build() 56 } 57