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:

   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;

   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;

   type Buffer_Type (Max_Characters : Text_Buffer_Count)
      is new Root_Buffer_Type with private
      with Default_Initial_Condition => not Text_Truncated (Buffer_Type);

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

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.

A.4.12 Universal Text Buffers

Static Semantics

Implementation Advice