Description
Collects one selected decoded string, decoded name, or exact number lexeme into bounded caller storage and publishes only a completed prefix.
Abort_Token
procedure Abort_Token (Self : in out Collector)
Discard staged or published token state and return Self to Empty. The operation is nonraising and idempotent in every state. Retained storage octets become unspecified.
Parameters
- Self
Collector to clear.
Append
procedure Append
(Self : in out Collector; Value : Ada.Streams.Stream_Element_Array; Status : out Collector_Status)
Append succeeds only in Collecting. It copies all Value octets or none, accepts arbitrary array bounds, and treats an empty Value as a no-op. Value must not overlap Storage. Capacity denial enters Failed and publishes no completed length.
Parameters
- Self
Collector that owns the unpublished staged prefix.
- Value
Complete fragment to copy atomically; it may have arbitrary bounds.
- Status
Operation_Accepted,Invalid_Order, orStorage_Exhausted.
Begin_Token
procedure Begin_Token (Self : in out Collector; Kind : Token_Kind; Status : out Collector_Status)
Begin_Token succeeds only in Empty. It enters Collecting with no published token. Every other state returns Invalid_Order unchanged.
Parameters
- Self
Collector whose lifecycle state is updated.
- Kind
Semantic kind assigned to the new token.
- Status
Operation_AcceptedorInvalid_Order.
Collected_Length
function Collected_Length (Self : Collector) return Ada.Streams.Stream_Element_Count
Report the length of the completed published prefix.
Parameters
- Self
Completed collector to inspect.
Return value
Number of readable components beginning at
Storage'First.
Collector
type Collector (Storage : not null access Token_Storage) is limited private;
Storage is caller-owned, may have arbitrary bounds, and outlives Self. Self performs no allocation and retains no input passed to Append.
Record fields
- Storage
Nonnull caller-owned array that stages and publishes the selected token.
Collector_State
type Collector_State is (Empty, Collecting, Complete, Failed);
Lifecycle state of one bounded collector.
Enumeration literals
- Empty
No token is active or published.
- Collecting
A token is active, but its staged bytes are unpublished.
- Complete
One complete token prefix is published in caller storage.
- Failed
Storage denial ended collection without publishing a token.
Collector_Status
type Collector_Status is (Operation_Accepted, Token_Completed, Invalid_Order, Storage_Exhausted);
Outcome of a state-changing collector operation.
Enumeration literals
- Operation_Accepted
The requested begin or append operation completed.
- Token_Completed
The staged token became the published completed prefix.
- Invalid_Order
The operation is not legal in the current collector state.
- Storage_Exhausted
The complete append would exceed caller storage.
Complete_Token
procedure Complete_Token (Self : in out Collector; Status : out Collector_Status)
Complete_Token succeeds only in Collecting and atomically publishes the staged prefix length, including zero. Other states return Invalid_Order without changing state or publication.
Parameters
- Self
Collector whose staged prefix is published on success.
- Status
Token_CompletedorInvalid_Order.
Kind
function Kind (Self : Collector) return Token_Kind
Report the semantic kind selected by Begin_Token.
Parameters
- Self
Active or completed collector to inspect.
Return value
Selected token kind.
Reset
procedure Reset (Self : in out Collector)
Prepare the collector for reuse. This has the same lifecycle and storage effects as Abort_Token and is nonraising and idempotent.
Parameters
- Self
Collector to reset to
Empty.
State
function State (Self : Collector) return Collector_State
Report the current collector lifecycle state.
Parameters
- Self
Collector to inspect.
Return value
Current state without changing storage or publication.
Token_Kind
type Token_Kind is (Decoded_Name, Decoded_String, Exact_Number);
Semantic token category selected when collection begins.
Enumeration literals
- Decoded_Name
UTF-8 octets of a decoded object member name.
- Decoded_String
UTF-8 octets of a decoded JSON string value.
- Exact_Number
Exact source octets of a validated JSON number lexeme.
Token_Storage
subtype Token_Storage is Ada.Streams.Stream_Element_Array;
This is the exact stream-element array type, not a derived array type. A completed prefix can therefore be passed directly to another octet API without a conversion, hidden copy, or unchecked overlay.