rabosh-variant/app.oreshkov.rabosh.variant/Variant

Variant

class Variant(val metadata: VariantMetadata, segment: MemorySegment, val offset: Long = 0)

A view over one encoded Variant value.

Nothing is decoded on construction and nothing is copied: a Variant is a metadata reference, a MemorySegment and an offset into it. Navigating into a field or an element produces another view over the same bytes, which is what makes reading a single path out of a large document cost the path, not the document.

The segment may be a heap array during ingest or a mapped file region once segments are on disk; the reader does not care which, and that is the point — the same code reads a memtable entry and a page of an SSTable.

A view is immutable and cheap to create. It is safe to share between threads as long as the underlying segment is not being written, which for an immutable segment is always.

Every accessor validates before it reads. Bytes that do not decode raise VariantFormatException — the engine never fabricates a default for data it cannot read.

Constructors

Variant

constructor(metadata: VariantMetadata, segment: MemorySegment, offset: Long = 0)

constructor(metadata: VariantMetadata, value: ByteArray)

Reads a value out of a heap array.

Types

Companion

object Companion

Properties

basicType

val basicType: VariantBasicType

The two-bit basic type opening this value.

byteSize

val byteSize: Long

Total encoded length of this value in bytes, including its header.

childCount

val childCount: Int

Number of top-level children: fields for an object, elements for an array, 0 for a scalar.

elementCount

val elementCount: Int

Number of elements. @throws VariantTypeException unless this value is an array.

fieldCount

val fieldCount: Int

Number of fields. @throws VariantTypeException unless this value is an object.

isNull

val isNull: Boolean

true for the Variant null primitive. Note that a missing field is absent, not null.

kind

val kind: VariantKind

What this value means, independent of the width it was stored in.

metadata

val metadata: VariantMetadata

Dictionary resolving this value's field ids. Usually shared by a whole segment.

offset

val offset: Long

Offset of this value's header byte within segment.

primitiveType

val primitiveType: VariantPrimitiveType?

The exact on-disk primitive type, or null when this value is not a primitive — a short string, an object or an array.

Functions

appendJsonSummaryTo

fun Variant.appendJsonSummaryTo(out: StringBuilder, limit: Int = DEFAULT_SUMMARY_LIMIT)

Appends toJsonSummaryString to out, avoiding an intermediate String.

appendJsonTo

fun Variant.appendJsonTo(out: StringBuilder)

Appends Variant.toJsonString to out, avoiding an intermediate String.

binaryValue

fun binaryValue(): ByteArray

booleanValue

fun booleanValue(): Boolean

decimalValue

fun decimalValue(): BigDecimal

doubleValue

fun doubleValue(): Double

The value of a float or double, widened to Double.

element

fun element(index: Int): Variant

The element at index. @throws VariantTypeException unless this value is an array.

elements

fun elements(): List<Variant>

The elements, in order. @throws VariantTypeException unless this value is an array.

epochDay

fun epochDay(): Int

Days since 1970-01-01 for a date.

field

fun field(name: String): Variant?

The field called name, or null if the object does not have one.

fieldId

fun fieldId(index: Int): Int

Dictionary id of the field at index; fields are ordered by name, not by id.

fieldName

fun fieldName(index: Int): String

Name of the field at index.

fields

fun fields(): List<Pair<String, Variant>>

The fields, in the encoded (lexicographic) order.

fieldValue

fun fieldValue(index: Int): Variant

Value of the field at index.

longValue

fun longValue(): Long

The value of an int8/int16/int32/int64, widened to Long.

select

fun select(path: VariantPath): Variant?

Follows path from this value, or returns null if any step does not exist.

fun select(path: String): Variant?

Follows a path expression such as $.items[0].name. See VariantPath.parse.

stringValue

fun stringValue(): String

The text of a short string or a long string.

temporalValue

fun temporalValue(): Long

The raw counter behind a time or timestamp: microseconds for VariantPrimitiveType.TIME_NTZ, VariantPrimitiveType.TIMESTAMP_TZ and VariantPrimitiveType.TIMESTAMP_NTZ, nanoseconds for the two NANOS types.

toByteArray

fun toByteArray(): ByteArray

Copies this value's bytes out of the segment. Pair with VariantMetadata.toByteArray.

toJsonString

fun Variant.toJsonString(): String

Renders this value as JSON text.

toJsonSummaryString

fun Variant.toJsonSummaryString(limit: Int = DEFAULT_SUMMARY_LIMIT): String

The first limit top-level children, with everything below them elided.

toString

open override fun toString(): String

Renders as JSON when it can, which is what a failing assertion or a debugger wants to show. Values JSON cannot express fall back to a structural description rather than throwing — toString failing is never helpful.

toSummaryString

fun Variant.toSummaryString(): String

One line describing this value's shape and size, whatever it holds and however large it is.

uuidValue

fun uuidValue(): Uuid