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 Root_Buffer_Type is abstract tagged private
      with Default_Initial_Condition =>
             Current_Indent (Root_Buffer_Type) = 0;

   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 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;

{AI12-0340-1} {AI12-0384-2} package Ada.Strings.Text_Buffers.Unbounded
with Preelaborate, Nonblocking, Global => null is

   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);

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} 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.

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.

A.4.12 Universal Text Buffers

Static Semantics

Implementation Advice

Extensions to Ada 2012