Ada Reference Manual (Ada 2022)
A.4.12 Universal Text Buffers
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
The text buffer library packages have the following declarations:
with Ada.Strings.UTF_Encoding.Wide_Wide_Strings;
package Ada.Strings.Text_Buffers
with Pure is
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;
with Default_Initial_Condition =>
Current_Indent (Root_Buffer_Type) = 0;
procedure Put (
Buffer : in out Root_Buffer_Type;
Item : in String) is abstract;
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;
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;
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;
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;
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;
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;
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;
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;
... -- not specified by the language
end Ada.Strings.Text_Buffers;
package Ada.Strings.Text_Buffers.Unbounded
with Preelaborate, Nonblocking, Global => null is
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;
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;
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;
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;
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;
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;
... -- not specified by the language, but will include nonabstract
-- overridings of all inherited subprograms that require overriding.
end Ada.Strings.Text_Buffers.Unbounded;
package Ada.Strings.Text_Buffers.Bounded
with Pure, Nonblocking, Global => null is
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);
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.
-- 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;
... -- not specified by the language, but will include nonabstract
-- overridings of all inherited subprograms that require overriding.
end Ada.Strings.Text_Buffers.Bounded;
Character_Count returns the number of characters currently stored in a text buffer.
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.
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.
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.
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
Bounded buffer objects should be implemented without dynamic allocation.
