Ada Conformity Assessment Authority      Home Conformity Assessment   Test Suite ARGAda Standard
 
Annotated Ada Reference Manual (Ada 202x Draft 25)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} package Ada.Strings.Text_Buffers
   with Pure, Nonblocking, Global => null 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;
7/5
   function Character_Count (Buffer : Root_Buffer_Type)
      return Text_Buffer_Count is abstract;
8/5
   procedure Clear (Buffer : Root_Buffer_Type) is abstract
      with Post'Class => Character_Count (Buffer) = 0;
9/5
   procedure Get (
      Buffer : in out Root_Buffer_Type;
      Item   : out String;
      Last   : out Natural) is abstract
      with Post'Class =>
         (declare
            Num_Read : constant Text_Buffer_Count :=
               Text_Buffer_Count'Min
                  (Character_Count(Buffer)'Old, Item'Length);
          begin
             Last = Num_Read + Item'First - 1 and then
             Character_Count (Buffer) =
             Character_Count (Buffer)'Old - Num_Read);
10/5
   procedure Wide_Get (
      Buffer : in out Root_Buffer_Type;
      Item   : out Wide_String;
      Last   : out Natural) is abstract
      with Post'Class =>
         (declare
            Num_Read : constant Text_Buffer_Count :=
               Text_Buffer_Count'Min
                  (Character_Count(Buffer)'Old, Item'Length);
          begin
             Last = Num_Read + Item'First - 1 and then
             Character_Count (Buffer) =
             Character_Count (Buffer)'Old - Num_Read);
11/5
   procedure Wide_Wide_Get (
      Buffer : in out Root_Buffer_Type;
      Item   : out Wide_Wide_String;
      Last   : out Natural) is abstract
      with Post'Class =>
         (declare
            Num_Read : constant Text_Buffer_Count :=
               Text_Buffer_Count'Min
                  (Character_Count(Buffer)'Old, Item'Length);
          begin
             Last = Num_Read + Item'First - 1 and then
             Character_Count (Buffer) =
             Character_Count (Buffer)'Old - Num_Read);
12/5
   function End_of_Line (Buffer : in Root_Buffer_Type)
      return Boolean is abstract;
13/5
   procedure Put (
      Buffer : in out Root_Buffer_Type;
      Item   : in     String) is abstract
      with Post'Class =>
         Character_Count (Buffer) =
         Character_Count (Buffer)'Old + Item'Length;
14/5
   procedure Wide_Put (
      Buffer : in out Root_Buffer_Type;
      Item   : in     Wide_String) is abstract
      with Post'Class =>
         Character_Count (Buffer) =
         Character_Count (Buffer)'Old + Item'Length;
15/5
   procedure Wide_Wide_Put (
      Buffer : in out Root_Buffer_Type;
      Item   : in     Wide_Wide_String) is abstract
      with Post'Class =>
         Character_Count (Buffer) =
         Character_Count (Buffer)'Old + Item'Length;
16/5
   procedure New_Line (Buffer : in out Root_Buffer_Type)
      is abstract
      with Post'Class =>
         Character_Count (Buffer) =
         Character_Count (Buffer)'Old + New_Line_Count;
17/5
private
   ... -- not specified by the language
end Ada.Strings.Text_Buffers;
18/5
{AI12-0340-1} package Ada.Strings.Text_Buffers.Unbounded
   with Preelaborate, Nonblocking, Global => null is
19/5
   type Buffer_Type is new Root_Buffer_Type with private
      with Default_Initial_Condition =>
         Character_Count (Buffer_Type) = 0;
20/5
   -- Nonabstract overridings of each inherited operation are declared here.
21/5
private
   ... -- not specified by the language
end Ada.Strings.Text_Buffers.Unbounded;
22/5
{AI12-0340-1} package Ada.Strings.Text_Buffers.Bounded
   with Pure, Nonblocking, Global => null is
23/5
   type Buffer_Type (Max_Characters : Text_Buffer_Count)
      is new Root_Buffer_Type with private
      with Default_Initial_Condition =>
         Character_Count (Buffer_Type) = 0;
24/5
   -- Nonabstract overridings of each inherited operation are declared here.
   -- For each of Put, Wide_Put, and Wide_Wide_Put,
   -- Pre => (if Character_Count (Buffer) + Item'Length > Buffer.Max_Characters
   --         then raise Constraint_Error),
   -- is added to the declaration. For New_Line,
   -- Pre => (if Character_Count (Buffer) + New_Line_Count > Buffer.Max_Characters
   --         then raise Constraint_Error),
   -- is added to the declaration.
25/5
private
   ... -- not specified by the language
end Ada.Strings.Text_Buffers.Bounded;
26/5
{AI12-0340-1} Character_Count returns the number of characters currently stored in a text buffer.
26.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.
27/5
{AI12-0340-1} New_Line stores New_Line_Count characters that represent a new line into a text buffer. End_of_Line returns True if the next characters to be retrieved from the text buffer represent a new line.
28/5
{AI12-0340-1} A call to Put, Wide_Put, or Wide_Wide_Put stores a sequence of characters into the text buffer.
29/5
{AI12-0340-1} A call to Get, Wide_Get, or Wide_Wide_Get returns the same sequence of characters as was present in the calls that stored the characters into the buffer. 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.
29.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.
29.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.
29.c/5
Ramification: {AI12-0340-1} Even when the result is implementation defined, the postconditions on the various Get routines require the length of the returned string to match that of the number of characters removed from the buffer. 

Implementation Advice

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

Extensions to Ada 2012

30.a/5
{AI12-0340-1} 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