Documentation
¶
Overview ¶
Package label defines the Label type and its associated operations for Argo. Labels are signed variable-length integers (encoded using ZigZag ULEB128) that serve multiple purposes in the Argo binary format:
- Encoding lengths of data segments (e.g., string length, array size).
- Representing special marker values like Null, Absent, or Error.
- Encoding backreferences to previously seen values for data deduplication.
The package provides constants for common marker labels (Null, Absent, True, False, etc.), functions to create labels from integer values, methods to determine a label's kind (Length, Null, Backreference, etc.), and functions for encoding labels to and decoding labels from byte streams.
Index ¶
- Variables
- type Label
- func (l Label) Encode() []byte
- func (l Label) Is(other Label) bool
- func (l Label) IsAbsent() bool
- func (l Label) IsBackref() bool
- func (l Label) IsError() bool
- func (l Label) IsLength() bool
- func (l Label) IsNull() bool
- func (l Label) Kind() LabelKind
- func (l Label) String() string
- func (l Label) ToOffset() (int64, error)
- func (l Label) Value() *big.Int
- type LabelKind
Constants ¶
This section is empty.
Variables ¶
var ( Null []byte // Encoded form of NullMarker (-1). Absent []byte // Encoded form of AbsentMarker (-2). Error []byte // Encoded form of ErrorMarker (-3). Zero []byte // Encoded form of 0 (used for FalseMarker, NonNullMarker, and length 0). NonNull []byte // Encoded form of NonNullMarker (0); alias for Zero. False []byte // Encoded form of FalseMarker (0); alias for Zero. True []byte // Encoded form of TrueMarker (1). )
--- Exported pre-encoded byte slices for common Label values --- These are the ZigZag ULEB128 encoded forms of the marker labels.
Functions ¶
This section is empty.
Types ¶
type Label ¶
type Label struct {
// contains filtered or unexported fields
}
Label wraps a *big.Int to represent an Argo label. Its value determines its kind (length, null, backreference, etc.) and specific meaning. Labels are immutable once created; their underlying *big.Int should not be modified after creation, especially for the global Label constants.
var ( TrueMarker Label // Label for boolean True (value 1). FalseMarker Label // Label for boolean False (value 0). NonNullMarker Label // Label for NonNull marker (value 0); alias for FalseMarker. NullMarker Label // Label for Null (value -1). AbsentMarker Label // Label for Absent (value -2). ErrorMarker Label // Label for Error (value -3). LowestReservedValue Label // Label instance for the lowest reserved non-backreference value (-3). )
--- Exported Label constants --- These provide convenient access to common, predefined label values.
var ( WireTypeMarkerString Label WireTypeMarkerBoolean Label WireTypeMarkerVarint Label WireTypeMarkerFloat64 Label WireTypeMarkerBytes Label WireTypeMarkerFixed Label WireTypeMarkerBlock Label WireTypeMarkerNullable Label WireTypeMarkerArray Label WireTypeMarkerRecord Label WireTypeMarkerDesc Label WireTypeMarkerError Label WireTypeMarkerPath Label WireTypeMarkerUnion Label WireTypeMarkerExtensions Label )
func New ¶
New creates a new Label from the provided *big.Int. The caller should not modify `val` after passing it to New, especially if it's not a fresh *big.Int, to avoid unintended side effects on the Label. If `val` is nil, a Label with a *big.Int value of 0 is created.
func NewFromInt64 ¶
NewFromInt64 creates a new Label from an int64 value. This is a convenience constructor for creating labels from standard integer types.
func Read ¶
Read decodes a label from a buffer `b` that implements the `buf.Read` interface. It reads a ZigZag ULEB128 encoded number from the buffer at its current position, advances the buffer's position by the number of bytes read, and returns the decoded Label. Any errors encountered during varint decoding are propagated.
func (Label) Encode ¶
Encode converts the Label into its ZigZag ULEB128 encoded byte representation. For common marker labels (Null, Absent, Error), it returns their pre-encoded global byte slices. Otherwise, it performs ZigZag encoding on the label's *big.Int value.
func (Label) Is ¶
Is checks if this label (l) has the same numerical value as another label (other). It compares their underlying *big.Int values. Handles cases where one or both labels might be uninitialized (value is nil), although constructors aim to prevent l.value from being nil.
func (Label) IsAbsent ¶
IsAbsent checks if the label represents an Absent value (i.e., its value is -2).
func (Label) IsBackref ¶
IsBackref checks if the label represents a backreference. A backreference label has a value numerically less than `lowestReservedBigInt` (i.e., < -3).
func (Label) IsError ¶
IsError checks if the label represents an Error marker (i.e., its value is -3).
func (Label) IsLength ¶
IsLength checks if the label represents a length or a non-negative marker (i.e., its value >= 0). This includes actual lengths, TrueMarker (1), FalseMarker (0), and NonNullMarker (0).
func (Label) Kind ¶
Kind determines and returns the semantic LabelKind of the Label (e.g., Null, Length, Backreference). The kind is derived from the label's numerical value according to Argo rules.
func (Label) String ¶
String returns the decimal string representation of the Label's underlying *big.Int value.
func (Label) ToOffset ¶
ToOffset converts a backreference Label into a 0-indexed array/slice offset. The Label must represent a valid backreference (i.e., its Kind must be LabelKindBackreference). An error is returned if the Label is not a valid backreference (e.g., it's non-negative or one of the special markers like Null, Absent, Error), or if its value is too large to be represented as an int64 after transformation (highly unlikely for practical offsets). The formula used is: offset = -NumericValue(label) + labelToOffsetFactor. For example, if labelToOffsetFactor is -4:
- A label of -4 (smallest valid backref value) gives offset: -(-4) + (-4) = 4 - 4 = 0.
- A label of -5 gives offset: -(-5) + (-4) = 5 - 4 = 1.
func (Label) Value ¶
Value returns the underlying *big.Int of the Label. Callers must not modify the returned *big.Int, as it may be shared by predefined Label constants (e.g., NullMarker, TrueMarker) or other Label instances. To perform arithmetic, create a new *big.Int (e.g., `new(big.Int).Set(l.Value())`).
type LabelKind ¶
type LabelKind int
LabelKind categorizes a Label based on its numerical value and Argo semantics. Different kinds determine how the label (and potentially associated data) is interpreted.
const ( // LabelKindNull (-1) indicates a null or missing value where the field itself is present. LabelKindNull LabelKind = iota // LabelKindAbsent (-2) indicates a field or array entry that is entirely absent or omitted. LabelKindAbsent // LabelKindError (-3) indicates that an error occurred at this position in the data structure. // The error details may follow or be found in a separate error list. LabelKindError // LabelKindBackreference (negative, < -3) indicates a reference to a previously encountered value. // The specific negative value is used to calculate an offset to the original value. LabelKindBackreference // LabelKindLength (non-negative, >= 0) indicates the length of a subsequent data value (e.g., string bytes, array elements). // It can also represent boolean true (1) or false/non-null marker (0) in specific contexts. LabelKindLength )
Source Files