LazyString class

Wraps a UTF-8 byte slice and decodes it to a String only on demand.

Intended for protocol consumers that hold large result sets where most text cells are never read back as String (e.g. only a handful of columns are inspected, the rest are aggregated or piped). Building a String for every cell is wasteful in those workloads.

Identity & equality

LazyString equals another LazyString iff their underlying bytes are identical. It also equals a String whose UTF-8 encoding matches — so cells stored as LazyString interoperate with comparisons against literal strings (cell == 'expected') the same way as eagerly decoded values would.

Decoding policy

Uses utf8.decode(allowMalformed: true) to mirror the BinaryProtocolParser._decodeText contract: invalid bytes become U+FFFD instead of throwing. This keeps the byte stream survivable across malformed driver payloads.

When NOT to use

  • For columns that are always read back: pay the decode once, eager String is simpler.
  • For columns sorted/grouped Dart-side: comparison is byte-wise and may not match locale-aware sort.

This class is intentionally not produced by the default parser — it is an opt-in primitive that callers can drop into their own decode paths.

The class carries the @immutable marker because its observable identity (equality, hashing, byte length, value) is defined entirely over the final _bytes field. The private _decoded field is a memoization cache that does not change the value the class represents; we suppress must_be_immutable for that reason only.

Annotations
  • @immutable

Constructors

LazyString(Uint8List _bytes)
Wraps bytes without taking a defensive copy. The caller is responsible for not mutating the slice after wrapping.

Properties

byteLength → int
Number of UTF-8 bytes backing this string. O(1).
no setter
bytes → Uint8List
Read-only view over the underlying UTF-8 bytes. Mutating the slice is undefined behaviour and will produce inconsistent results from value.
no setter
hashCode → int
The hash code for this object.
no setteroverride
isDecoded → bool
Whether value has been computed yet. Useful in tests and metrics to confirm the decode actually happens lazily.
no setter
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
value → String
Triggers decoding (or returns the cached result on repeat access).
no setter

Methods

noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toString() → String
A string representation of this object.
override

Operators

operator ==(Object other) → bool
The equality operator.
override