Struct RawJson

The bytes a node actually sent for one member of a response, as they arrived.

Namespace: Xrpl.Client.Json

Assembly: Xrpl.dll

Syntax

public readonly struct RawJson

Remarks

A window onto the frame rather than a copy of it: the frame is the exact-sized array the receive loop already allocated, so holding this costs nothing beyond keeping that array alive. UTF-16 is never stored — ToString() builds it on demand, which for a large response is twice the byte length and worth paying only when something needs text. The window keeps the whole frame alive, not just the bytes it spans: for the result member that is the frame anyway, but a small window onto a large frame pins all of it. Anything outliving the response — a stored page, an entry cached across a paged crawl — should keep ToArray() instead and let the frame go.

Constructors

RawJson(byte[]?, int, int)

Records the window; does not copy the frame.

Declaration

public RawJson(byte[]? frame, int offset, int length)

Parameters

Type	Name	Description
byte[]	frame
int	offset
int	length

Remarks

The window is checked to hold exactly one JSON value, because WriteTo(Utf8JsonWriter) writes it through without validating - a partial or malformed window would silently corrupt the document it is written into. The check happens here, once, rather than on every write: WriteTo(Utf8JsonWriter) runs per response on a paged crawl, and validating there costs about 10x (measured 3.26 -> 29.45 us on a 36 KB window).

Note the frame is aliased, not copied. Mutating the array after construction changes what this window reads, and no check can catch that - use ToArray() to detach if the buffer is not yours alone.

Exceptions

Type	Condition
ArgumentOutOfRangeException	The window does not lie inside frame.
JsonException	The window is not exactly one well-formed JSON value.

Properties

IsEmpty

True when nothing was captured.

Declaration

public bool IsEmpty { get; }

Property Value

Type	Description
bool

Length

Length of the captured JSON in bytes.

Declaration

public int Length { get; }

Property Value

Type	Description
int

Span

The captured JSON, as UTF-8, without copying.

Declaration

public ReadOnlySpan<byte> Span { get; }

Property Value

Type	Description
ReadOnlySpan<byte>

Methods

Deserialize<T>()

Deserializes the captured JSON into T using the library's serializer options.

Declaration

public T? Deserialize<T>()

Returns

Type	Description
T

Type Parameters

Name	Description
T

Remarks

Here so that a consumer does not reach for JsonSerializer.Deserialize with options of their own: the XRPL models depend on the converters in Default, and bare options silently produce a different object. Returns default for an empty window rather than throwing — an absent member is not a malformed one. That default is ambiguous for a value type, where it coincides with a legitimately-parsed zero; IsEmpty is what tells the two apart.

Equals(object?)

Indicates whether this instance and a specified object are equal.

Declaration

public override bool Equals(object? obj)

Parameters

Type	Name	Description
object	obj	The object to compare with the current instance.

Returns

Type	Description
bool	true if obj and this instance are the same type and represent the same value; otherwise, false.

Overrides

System.ValueType.Equals(object)

Equals(RawJson)

Identity, not content: two windows are equal when they address the same bytes of the same frame. Comparing the bytes themselves is what Span is for. Without this the default struct equality reflects over the fields to reach the same answer, boxing both operands, and hashes on the frame reference alone - so two different windows onto one frame land in the same bucket.

Declaration

public bool Equals(RawJson other)

Parameters

Type	Name	Description
RawJson	other

Returns

Type	Description
bool

GetHashCode()

Returns the hash code for this instance.

Declaration

public override int GetHashCode()

Returns

Type	Description
int	A 32-bit signed integer that is the hash code for this instance.

Overrides

System.ValueType.GetHashCode()

HasTopLevelProperty(ReadOnlySpan<byte>)

True when the captured JSON is an object carrying name at its top level.

Declaration

public bool HasTopLevelProperty(ReadOnlySpan<byte> name)

Parameters

Type	Name	Description
ReadOnlySpan<byte>	name

Returns

Type	Description
bool

Remarks

Each non-matching member's value is skipped whole, so a nested occurrence of the name cannot be mistaken for a top-level one. Names are matched by Xrpl.Client.Json.JsonSlice.NameMatches(ref System.Text.Json.Utf8JsonReader, System.ReadOnlySpan<byte>): case-insensitively, mirroring Default's System.Text.Json.JsonSerializerOptions.PropertyNameCaseInsensitive = true, and without allocating for anything but an escaped name - this runs on every paged response through HasNextPage. Presence does not depend on which occurrence is meant, unlike a value lookup, so unlike Xrpl.Client.Json.JsonSlice.FindTopLevelMember(byte[], System.ReadOnlySpan<byte>, bool) this still returns as soon as a match is found instead of scanning to the end for the last one.

Exceptions

Type	Condition
JsonException	The window does not hold well-formed JSON. Unreachable for a RawJson the SDK produced - those windows come from a document it already parsed - but this type is public and constructible over arbitrary bytes.

ToArray()

Copies the captured JSON into a new array, detaching it from the frame. This is how a consumer keeps the bytes past the response without pinning the whole frame with them.

Declaration

public byte[] ToArray()

Returns

Type	Description
byte[]

ToJsonElement()

Parses the captured JSON into a self-contained System.Text.Json.JsonElement.

Declaration

public JsonElement ToJsonElement()

Returns

Type	Description
JsonElement

Remarks

The element copies out of the frame, so it stays readable after the frame is gone — unlike Span, which aliases it. An empty window yields System.Text.Json.JsonValueKind.Undefined. Parses over System.ReadOnlyMemory<T> directly rather than through ToArray(): JsonDocument.Parse does not copy a memory argument, so going through ToArray first would pay for a copy this call does not need — System.Text.Json.JsonElement.Clone() is what makes the result self-contained, and that is the only copy that has to happen.

ToString()

Decodes the captured JSON as UTF-16 text. Allocates; call only when text is needed. This is a decode of the bytes, not the byte-exact source — invalid UTF-8 is replaced with U+FFFD. For the bytes as the node sent them, use Span.

Declaration

public override string ToString()

Returns

Type	Description
string

Overrides

System.ValueType.ToString()

WriteTo(Utf8JsonWriter)

Writes the captured JSON into writer verbatim.

Declaration

public void WriteTo(Utf8JsonWriter writer)

Parameters

Type	Name	Description
Utf8JsonWriter	writer

Operators

operator ==(RawJson, RawJson)

Identity comparison; see Equals(RawJson).

Declaration

public static bool operator ==(RawJson left, RawJson right)

Parameters

Type	Name	Description
RawJson	left
RawJson	right

Returns

Type	Description
bool

operator !=(RawJson, RawJson)

Identity comparison; see Equals(RawJson).

Declaration

public static bool operator !=(RawJson left, RawJson right)

Parameters

Type	Name	Description
RawJson	left
RawJson	right

Returns

Type	Description
bool