1. Overview
  2. Guide
  3. Writing

Stage before publication

The bounded writer validates CBOR call grammar and UTF-8 while staging bytes. Only a successful Finish_Document makes its complete output eligible.

Choose ownership and allocation

PackageStorage contract
Bounded_WritingOwns a fixed unpublished byte buffer. It performs no heap allocation.
Allocating_WritingOwns a vector and returns completed output as a separate array.
WritingGeneric facade over a caller destination transaction. The caller passes the same exclusive target throughout one active transaction.

Use a self-owned facade when it meets the storage requirement. It avoids retained target references and finalization hazards.

Set ordinary compact output explicitly

Ordinary_Compact uses shortest integer, length, tag, and simple-value heads. It preserves caller order and requested float width. It is not canonical CBOR and does not sort map keys.

Describe exactly one balanced item

Definite string lengths count payload octets. Array lengths count child items, while map lengths count pairs. Indefinite strings contain explicit definite chunks. Tags use matching begin and end calls around one item.

The bounded example starts the document and container with Begin_Document and Begin_Map. Each text field uses Begin_Text_String, Put_Text_String_Fragment, and End_Text_String. It writes the number with Put_Unsigned, then calls End_Map and Finish_Document in grammar order.

   Writing.Begin_Document (Writer, Diagnostic);
   Check (Diagnostic, "Begin_Document");
   Writing.Begin_Map (Writer, Pair_Count => 2, Diagnostic => Diagnostic);
   Check (Diagnostic, "Begin_Map");

   Writing.Begin_Text_String (Writer, Name'Length, Diagnostic);
   Writing.Put_Text_String_Fragment (Writer, Name, Diagnostic);
   Writing.End_Text_String (Writer, Diagnostic);

   Writing.Begin_Text_String (Writer, Ada_Text'Length, Diagnostic);
   Writing.Put_Text_String_Fragment (Writer, Ada_Text, Diagnostic);
   Writing.End_Text_String (Writer, Diagnostic);

   Writing.Begin_Text_String (Writer, N_Key'Length, Diagnostic);
   Writing.Put_Text_String_Fragment (Writer, N_Key, Diagnostic);
   Writing.End_Text_String (Writer, Diagnostic);
   Writing.Put_Unsigned (Writer, 1_000, Diagnostic);

   Writing.End_Map (Writer, Diagnostic);
   Check (Diagnostic, "End_Map");
   Writing.Finish_Document (Writer, Diagnostic);
   Check (Diagnostic, "Finish_Document");

Separate staged length from committed output

The bounded writer exposes Staged_Length in every lifecycle state. That value describes an unpublished retained prefix and may remain nonzero after failure or abort. Only a completed writer has eligible committed output.

A grammar, UTF-8, capacity, destination, or commit failure publishes nothing. Cleanup never replaces the primary diagnostic.

ValuesWrite exact scalar formsErrorsInterpret diagnostics