Ada Reference Manual (Ada 202x Draft 25)Legal Information
Contents   Index   References   Search   Previous   Next 

A.4.12 Universal Text Buffers

1/5
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
The text buffer library packages have the following declarations:
3/5
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
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
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
Character_Count returns the number of characters currently stored in a text buffer.
27/5
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
A call to Put, Wide_Put, or Wide_Wide_Put stores a sequence of characters into the text buffer.
29/5
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.

Implementation Advice

30/5
Bounded buffer objects should be implemented without dynamic allocation.

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