Ada Conformity Assessment Authority      Home Conformity Assessment   Test Suite ARGAda Standard
 
Annotated Ada Reference Manual (Ada 202x Draft 32)Legal Information
Contents   Index   References   Search   Previous   Next 

A.4.12 Universal Text Buffers

1/5
{AI12-0340-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 need not be the same. 

Static Semantics

2/5
{AI12-0340-1} The text buffer library packages have the following declarations:
3/5
{AI12-0340-1} {AI12-0384-2} 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
{AI12-0340-1} {AI12-0384-2} 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
{AI12-0340-1} {AI12-0384-2} 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
{AI12-0340-1} Character_Count returns the number of characters currently stored in a text buffer.
31.a/5
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.
32/5
{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.
33/5
{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.
34/5
{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.
34.a/5
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.
34.b/5
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.
35/5
{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

36/5
{AI12-0340-1} Bounded buffer objects should be implemented without dynamic allocation.
36.a.1/5
Implementation Advice: Bounded buffer objects should be implemented without dynamic allocation.

Extensions to Ada 2012

36.a/5
{AI12-0340-1} {AI12-0384-2} The packages Strings.Text_Buffers, Strings.Text_Buffers.Unbounded, and Strings.Text_Buffers.Bounded are new. 

Contents   Index   References   Search   Previous   Next 
Ada-Europe Ada 2005 and 2012 Editions sponsored in part by Ada-Europe