proxy.golang.org : github.com/phiryll/lexy
Package lexy defines an API for lexicographically ordered binary encodings. Implementations are provided for most builtin Go data types, and supporting functionality is provided to allow for the creation of user-defined encodings. The Codec[T] interface defines an encoding, with methods to encode and decode values of type T. Functions returning Codecs for different types constitute the majority of this API. There are two kinds of Codec-returning functions defined by this package, those for which Go can infer the type arguments, and those for which Go cannot. The former have terser names, as in Int16. The latter have names starting with "Cast", as in CastInt16[MyIntType]. These latter functions are only needed when creating a Codec for a type that is not the same as its underlying type. Empty also requires a type argument when used and is the only exception to this naming convention. All Codecs provided by lexy are safe for concurrent use if their delegate Codecs (if any) are. All Codecs provided by lexy will order nils first if nil can be encoded. Invoking NilsLast(codec) on a Codec will return a Codec which orders nils last, but only for the pointer, slice, map, []byte, and *big.Int/Float/Rat Codecs provided by lexy. See [Codec.RequiresTerminator] for details on when escaping and terminating encoded bytes is required. These Codec-returning functions do not require specifying a type parameter when invoked. These Codec-returning functions require specifying a type parameter when invoked. These are implementations of Prefix, used when creating user-defined Codecs that can encode types whose instances can be nil. ExampleArray shows how to define a Codec for an array type. ExamplePointerToStruct shows how to use pointers for efficiency in a user-defined Codec, to avoid unnecessarily copying large data structures. Note that types in Go other than structs and arrays do not have this problem. Complex numbers, strings, pointers, slices, and maps all have a relatively small footprint when passed by value. The same is true of time.Time and time.Duration instances. Normally, a Codec[BigStruct] would be defined and Container's Codec would use it as lexy.PointerTo(bigStructCodec). However, calls to a Codec[BigStruct] will pass BigStruct instances by value, even though the wrapping pointer Codec is only copying pointers. The order isn't relevant for this example, so other fields are not shown. ExampleRangeQuery shows how a range query might be implemented. ExampleSchemaChange shows one way to allow for schema changes. The gist of this example is to encode field names as well as field values. This can be done in other ways, and more or less leniently. This is just an example. Note that different encodings of the same type will generally not be ordered correctly with respect to each other, regardless of the technique used. Only field values should be encoded if any of the following are true: The kinds of schema change addressed by this example are: If a field's type might change, the best option is to use versioning. Otherwise, it would be necessary to encode the field's type before its value, because there's no way to know how to read the value otherwise, and then the type would be the primary sort key for that field. Encoding a value's type is strongly discouraged. The sort order of encoded data cannot be changed. However, there is nothing wrong with creating multiple Codecs with different orderings for the same type, nor with storing the same data ordered in different ways in the same data store. ExampleSchemaVersion shows how schema versioning could be implemented. This can be done in other ways, and more or less leniently. This is just an example, and likely a poorly structured one at that. Note that different encodings of the same type will generally not be ordered correctly with respect to each other, regardless of the technique used. The sort order of encoded data cannot be changed. However, there is nothing wrong with creating multiple Codecs with different orderings for the same type, nor with storing the same data ordered in different ways in the same data store. ExampleStruct shows how to define a typical user-defined Codec. someStructCodec in this example demonstrates an idiomatic Codec definition. The same pattern is used for non-struct types, see the array example for one such use case. The rules of thumb are:
Registry
-
Source
- Documentation
- JSON
- codemeta.json
purl: pkg:golang/github.com/phiryll/lexy
Keywords:
binary
, encoder-decoder
, go
, golang
, golang-library
, lexicographical-order
License: MIT
Latest release: over 1 year ago
First release: over 1 year ago
Namespace: github.com/phiryll
Stars: 0 on GitHub
Forks: 0 on GitHub
See more repository details: repos.ecosyste.ms
Last synced: 6 days ago