A.4.12 Universal Text Buffers
{
AI12-0340-1}
{
AI12-0439-1}
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
{
AI12-0340-1}
The text buffer library packages have the following declarations:
{
AI12-0340-1}
{
AI12-0384-2}
with Ada.Strings.UTF_Encoding.Wide_Wide_Strings;
package Ada.Strings.Text_Buffers
with Pure
is type Text_Buffer_Count
is range 0 ..
implementation-defined;
New_Line_Count :
constant Text_Buffer_Count :=
implementation-defined;
type Root_Buffer_Type
is abstract tagged private
with Default_Initial_Condition =>
Current_Indent (Root_Buffer_Type) = 0;
procedure Put (
Buffer :
in out Root_Buffer_Type;
Item :
in String)
is abstract;
procedure Wide_Put (
Buffer :
in out Root_Buffer_Type;
Item :
in Wide_String)
is abstract;
procedure Wide_Wide_Put (
Buffer :
in out Root_Buffer_Type;
Item :
in Wide_Wide_String)
is abstract;
procedure Put_UTF_8 (
Buffer :
in out Root_Buffer_Type;
Item :
in UTF_Encoding.UTF_8_String)
is abstract;
procedure Wide_Put_UTF_16 (
Buffer :
in out Root_Buffer_Type;
Item :
in UTF_Encoding.UTF_16_Wide_String)
is abstract;
procedure New_Line (Buffer :
in out Root_Buffer_Type)
is abstract;
Standard_Indent :
constant Text_Buffer_Count := 3;
function Current_Indent (
Buffer : Root_Buffer_Type)
return Text_Buffer_Count;
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;
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;
private
... -- not specified by the language
end Ada.Strings.Text_Buffers;
{
AI12-0340-1}
{
AI12-0384-2}
package Ada.Strings.Text_Buffers.Unbounded
with Preelaborate, Nonblocking, Global =>
null is type Buffer_Type
is new Root_Buffer_Type
with private;
function Get (
Buffer :
in out Buffer_Type)
return String
with Post'Class =>
Get'Result'First = 1
and then Current_Indent (Buffer) = 0;
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;
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;
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;
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;
private
... -- not specified by the language, but will include nonabstract
-- overridings of all inherited subprograms that require overriding.
end Ada.Strings.Text_Buffers.Unbounded;
{
AI12-0340-1}
{
AI12-0384-2}
package Ada.Strings.Text_Buffers.Bounded
with Pure, Nonblocking, Global =>
null is type Buffer_Type (Max_Characters : Text_Buffer_Count)
is new Root_Buffer_Type
with private
with Default_Initial_Condition =>
not Text_Truncated (Buffer_Type);
function Text_Truncated (Buffer :
in Buffer_Type)
return Boolean;
-- Get, Wide_Get, Wide_Wide_Get, Get_UTF_8, and Wide_Get_UTF_16
-- are declared here just as in the Unbounded child.
private
... -- not specified by the language, but will include nonabstract
-- overridings of all inherited subprograms that require overriding.
end Ada.Strings.Text_Buffers.Bounded;
{
AI12-0340-1}
{
AI22-0087-1}
If an object of a text buffer type is not otherwise
initialized, it is initialized to the empty state, with no stored characters Character_Count
returns the number of characters currently stored in a text buffer.
Ramification: {
AI12-0340-1}
This is lower-case "characters". The
representation isn't considered, so it is irrelevant what type of character
(Character, Wide_Character, or Wide_Wide_Character) was stored.
{
AI12-0340-1}
{
AI12-0384-2}
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.
{
AI12-0340-1}
{
AI12-0384-2}
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.
{
AI12-0340-1}
{
AI12-0384-2}
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.
Implementation defined: The value returned
by a call to a Text_Buffer Get procedure if any character in the returned
sequence is not defined in Character.
Implementation defined: The value returned
by a call to a Text_Buffer Wide_Get procedure if any character in the
returned sequence is not defined in Wide_Character.
{
AI12-0384-2}
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
{
AI12-0340-1}
Bounded buffer objects should be implemented without dynamic allocation.
Implementation Advice: Bounded buffer
objects should be implemented without dynamic allocation.
Extensions to Ada 2012
{
AI12-0340-1}
{
AI12-0384-2}
The packages Strings.Text_Buffers, Strings.Text_Buffers.Unbounded,
and Strings.Text_Buffers.Bounded are new.
Wording Changes from Ada 2022
{
AI22-0087-1}
Corrigendum: Added a description of the
initial state of a text buffer, and removed the description of a function
not defined in the text buffer package. The initial state has to be empty
in order to properly implement the semantics of attribute Image (see
4.10), so we don't consider this to change
any behavior.
Ada 2005 and 2012 Editions sponsored in part by Ada-Europe
