Class VariantValueWriter

Namespace

Apache.Arrow.Scalars.Variant

Assembly

Apache.Arrow.Scalars.dll

Streams variant value bytes directly from primitive calls, without requiring an intermediate VariantValue. Use this to implement encoders from arbitrary input formats (JSON, CBOR, etc.).

public sealed class VariantValueWriter : IDisposable

Inheritance

object

VariantValueWriter

Implements

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

Usage pattern:

1. Create a VariantMetadataBuilder and Add(string) every field name that will appear.
2. Call Build(out int[]) to produce the metadata bytes and the ID remap.
3. Create a VariantValueWriter with the metadata builder and remap, emit the value via the Write* / Begin* / End* methods, then call ToArray().
4. Dispose() the writer to return its cached backing arrays to Shared. Skipping Dispose leaks those arrays to the GC.

Constructors

VariantValueWriter(VariantMetadataBuilder, int[])

Creates a writer that produces value bytes referencing the given metadata.

public VariantValueWriter(VariantMetadataBuilder metadata, int[] idRemap)

Parameters

metadata VariantMetadataBuilder

The metadata builder used to resolve field names to IDs.

idRemap int[]

The remap returned by Build(out int[]).

Methods

BeginArray()

Begins writing an array. Pair with EndArray().

public void BeginArray()

BeginObject()

Begins writing an object. Pair with EndObject().

public void BeginObject()

CopyValue(VariantReader)

Copies the variant value pointed to by source into this writer. Useful when copying between metadata dictionaries: field IDs in the source are re-looked-up against this writer's VariantMetadataBuilder on the fly, via WriteFieldName(string).

public void CopyValue(VariantReader source)

Parameters

source VariantReader

Remarks

All field names referenced anywhere in source must already exist in the metadata builder used to construct this writer. Use CollectFieldNames(VariantReader) during the metadata-collection phase of a two-pass encode to accumulate them.

Dispose()

Returns all cached backing arrays (the root buffer, any still-open frame buffers, and the per-writer array pools) to Shared. The writer must not be used after Dispose(); calls to ToArray() or any Write* / Begin* method will throw ObjectDisposedException. Idempotent.

public void Dispose()

EndArray()

Ends the current array scope.

public void EndArray()

EndObject()

Ends the current object scope.

public void EndObject()

ToArray()

Returns the encoded value bytes. All opened objects and arrays must be closed.

public byte[] ToArray()

Returns

byte[]

WriteBinary(ReadOnlySpan<byte>)

Writes a binary blob.

public void WriteBinary(ReadOnlySpan<byte> data)

Parameters

data ReadOnlySpan<byte>

WriteBoolean(bool)

Writes a boolean value.

public void WriteBoolean(bool value)

Parameters

value bool

WriteDateDays(int)

Writes a date as days since the Unix epoch.

public void WriteDateDays(int days)

Parameters

days int

WriteDecimal16(SqlDecimal)

Writes a Decimal16 (precision ≤ 38) value stored as SqlDecimal.

public void WriteDecimal16(SqlDecimal value)

Parameters

value SqlDecimal

WriteDecimal4(decimal)

Writes a Decimal4 (precision ≤ 9) value.

public void WriteDecimal4(decimal value)

Parameters

value decimal

WriteDecimal8(decimal)

Writes a Decimal8 (precision ≤ 18) value.

public void WriteDecimal8(decimal value)

Parameters

value decimal

WriteDouble(double)

Writes a 64-bit IEEE 754 double.

public void WriteDouble(double value)

Parameters

value double

WriteFieldName(string)

Writes the name of the next field in the current object. Must be called before every field value (a primitive, nested object, or nested array). The name must already exist in the VariantMetadataBuilder.

public void WriteFieldName(string name)

Parameters

name string

WriteFloat(float)

Writes a 32-bit IEEE 754 float.

public void WriteFloat(float value)

Parameters

value float

WriteInt16(short)

Writes a 16-bit signed integer.

public void WriteInt16(short value)

Parameters

value short

WriteInt32(int)

Writes a 32-bit signed integer.

public void WriteInt32(int value)

Parameters

value int

WriteInt64(long)

Writes a 64-bit signed integer.

public void WriteInt64(long value)

Parameters

value long

WriteInt8(sbyte)

Writes an 8-bit signed integer.

public void WriteInt8(sbyte value)

Parameters

value sbyte

WriteIntegerCompact(long)

Writes an integer using the narrowest of Int8/Int16/Int32/Int64 that fits. Useful for size-minimising encoders such as JSON.

public void WriteIntegerCompact(long value)

Parameters

value long

WriteNull()

Writes a null value.

public void WriteNull()

WriteString(string)

Writes a string. Uses the short-string encoding when the UTF-8 byte length is ≤ 63.

public void WriteString(string value)

Parameters

value string

WriteTimeNtzMicros(long)

Writes a time-without-timezone value (microseconds since midnight).

public void WriteTimeNtzMicros(long micros)

Parameters

micros long

WriteTimestampMicros(long)

Writes a timestamp (tz-adjusted microseconds since the Unix epoch).

public void WriteTimestampMicros(long micros)

Parameters

micros long

WriteTimestampNtzMicros(long)

Writes a timestamp-without-timezone (microseconds since the Unix epoch).

public void WriteTimestampNtzMicros(long micros)

Parameters

micros long

WriteTimestampNtzNanos(long)

Writes a timestamp without timezone (nanoseconds since the Unix epoch).

public void WriteTimestampNtzNanos(long nanos)

Parameters

nanos long

WriteTimestampTzNanos(long)

Writes a timestamp with timezone (nanoseconds since the Unix epoch).

public void WriteTimestampTzNanos(long nanos)

Parameters

nanos long

WriteUuid(Guid)

Writes a UUID.

public void WriteUuid(Guid value)

Parameters

value Guid