Ada Reference Manual (Ada 2022) — Legal Information

# A.4.12 Universal Text Buffers

1/5
A universal text buffer can be used to save and retrieve text of any language-defined string type. The types used to save and retrieve the text can be different.

#### Static Semantics

2/5
The text buffer library packages have the following declarations:
3/5
with Ada.Strings.UTF_Encoding.Wide_Wide_Strings;
package Ada.Strings.Text_Buffers
with Pure is
4/5
type Text_Buffer_Count is range 0 .. implementation-defined;
5/5
New_Line_Count : constant Text_Buffer_Count := implementation-defined;
6/5
type Root_Buffer_Type is abstract tagged private
with Default_Initial_Condition =>
Current_Indent (Root_Buffer_Type) = 0;
7/5
procedure Put (
Buffer : in out Root_Buffer_Type;
Item : in String) is abstract;
8/5
procedure Wide_Put (
Buffer : in out Root_Buffer_Type;
Item : in Wide_String) is abstract;
9/5
procedure Wide_Wide_Put (
Buffer : in out Root_Buffer_Type;
Item : in Wide_Wide_String) is abstract;
10/5
procedure Put_UTF_8 (
Buffer : in out Root_Buffer_Type;
Item : in UTF_Encoding.UTF_8_String) is abstract;
11/5
procedure Wide_Put_UTF_16 (
Buffer : in out Root_Buffer_Type;
Item : in UTF_Encoding.UTF_16_Wide_String) is abstract;
12/5
procedure New_Line (Buffer : in out Root_Buffer_Type) is abstract;
13/5
Standard_Indent : constant Text_Buffer_Count := 3;
14/5
function Current_Indent (
Buffer : Root_Buffer_Type) return Text_Buffer_Count;
15/5
procedure Increase_Indent (
Buffer : in out Root_Buffer_Type;
Amount : in Text_Buffer_Count := Standard_Indent)
with Post'Class =>
Current_Indent (Buffer) = Current_Indent (Buffer)'Old + Amount;
16/5
procedure Decrease_Indent (
Buffer : in out Root_Buffer_Type;
Amount : in Text_Buffer_Count := Standard_Indent)
with Pre'Class =>
Current_Indent (Buffer) >= Amount
or else raise Constraint_Error,
Post'Class =>
Current_Indent (Buffer) =
Current_Indent (Buffer)'Old - Amount;
17/5
private
... -- not specified by the language
end Ada.Strings.Text_Buffers;
18/5
package Ada.Strings.Text_Buffers.Unbounded
with Preelaborate, Nonblocking, Global => null is
19/5
type Buffer_Type is new Root_Buffer_Type with private;
20/5
function Get (
Buffer : in out Buffer_Type)
return String
with Post'Class =>
Get'Result'First = 1 and then Current_Indent (Buffer) = 0;
21/5
function Wide_Get (
Buffer : in out Buffer_Type)
return Wide_String
with Post'Class =>
Wide_Get'Result'First = 1 and then Current_Indent (Buffer) = 0;
22/5
function Wide_Wide_Get (
Buffer : in out Buffer_Type)
return Wide_Wide_String
with Post'Class =>
Wide_Wide_Get'Result'First = 1
and then Current_Indent (Buffer) = 0;
23/5
function Get_UTF_8 (
Buffer : in out Buffer_Type)
return UTF_Encoding.UTF_8_String
with Post'Class =>
Get_UTF_8'Result'First = 1 and then Current_Indent (Buffer) = 0;
24/5
function Wide_Get_UTF_16 (
Buffer : in out Buffer_Type)
return UTF_Encoding.UTF_16_Wide_String
with Post'Class =>
Wide_Get_UTF_16'Result'First = 1
and then Current_Indent (Buffer) = 0;
25/5
private
... -- not specified by the language, but will include nonabstract
-- overridings of all inherited subprograms that require overriding.
end Ada.Strings.Text_Buffers.Unbounded;
26/5
package Ada.Strings.Text_Buffers.Bounded
with Pure, Nonblocking, Global => null is
27/5
type Buffer_Type (Max_Characters : Text_Buffer_Count)
is new Root_Buffer_Type with private
with Default_Initial_Condition => not Text_Truncated (Buffer_Type);
28/5
function Text_Truncated (Buffer : in Buffer_Type) return Boolean;
29/5
-- Get, Wide_Get, Wide_Wide_Get, Get_UTF_8, and Wide_Get_UTF_16
-- are declared here just as in the Unbounded child.
30/5
private
... -- not specified by the language, but will include nonabstract
-- overridings of all inherited subprograms that require overriding.
end Ada.Strings.Text_Buffers.Bounded;
31/5
Character_Count returns the number of characters currently stored in a text buffer.
32/5
New_Line stores New_Line_Count characters that represent a new line into a text buffer. Current_Indent returns the current indentation associated with the buffer, with zero meaning there is no indentation in effect; Increase_Indent and Decrease_Indent increase or decrease the indentation associated with the buffer.
33/5
A call to Put, Wide_Put, Wide_Wide_Put, Put_UTF_8, or Wide_Put_UTF_16 stores a sequence of characters into the text buffer, preceded by Current_Indent(Buffer) spaces (Wide_Wide_Characters with position 32) if there is at least one character in Item and it would have been the first character on the current line.
34/5
A call to function Get, Wide_Get, Wide_Wide_Get, Get_UTF_8, or Wide_Get_UTF_16 returns the same sequence of characters as was present in the calls that stored the characters into the buffer, if representable. For a call to Get, if any character in the sequence is not defined in Character, the result is implementation defined. Similarly, for a call to Wide_Get, if any character in the sequence is not defined in Wide_Character, the result is implementation defined. As part of a call on any of the Get functions, the buffer is reset to an empty state, with no stored characters.
35/5
In the case of a Buf of type Text_Buffers.Bounded.Buffer_Type, Text_Truncated (Buf) returns True if the various Put procedures together have attempted to store more than Buf.Max_Characters into Buf. If this function returns True, then the various Get functions return a representation of only the first Buf.Max_Characters characters that were stored in Buf.

#### Implementation Advice

36/5
Bounded buffer objects should be implemented without dynamic allocation.

Ada 2005 and 2012 Editions sponsored in part by Ada-Europe