A.4.12 Universal Text Buffers
{
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
{
AI12-0340-1}
The text buffer library packages have the following declarations:
{
AI12-0340-1}
package Ada.Strings.Text_Buffers
with Pure, Nonblocking, Global =>
null is
type Text_Buffer_Count
is range 0 ..
implementation-defined;
New_Line_Count :
constant Text_Buffer_Count :=
implementation-defined;
type Root_Buffer_Type
is abstract tagged private;
function Character_Count (Buffer : Root_Buffer_Type)
return Text_Buffer_Count
is abstract;
procedure Clear (Buffer : Root_Buffer_Type)
is abstract
with Post'Class => Character_Count (Buffer) = 0;
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);
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);
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);
function End_of_Line (Buffer :
in Root_Buffer_Type)
return Boolean
is abstract;
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;
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;
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;
procedure New_Line (Buffer :
in out Root_Buffer_Type)
is abstract
with Post'Class =>
Character_Count (Buffer) =
Character_Count (Buffer)'Old + New_Line_Count;
private
... -- not specified by the language
end Ada.Strings.Text_Buffers;
{
AI12-0340-1}
package Ada.Strings.Text_Buffers.Unbounded
with Preelaborate, Nonblocking, Global =>
null is
type Buffer_Type
is new Root_Buffer_Type
with private
with Default_Initial_Condition =>
Character_Count (Buffer_Type) = 0;
-- Nonabstract overridings of each inherited operation are declared here.
private
... -- not specified by the language
end Ada.Strings.Text_Buffers.Unbounded;
{
AI12-0340-1}
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 =>
Character_Count (Buffer_Type) = 0;
-- 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.
private
... -- not specified by the language
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}
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.
{
AI12-0340-1}
A call to Put, Wide_Put, or Wide_Wide_Put stores a sequence of characters
into the text buffer.
{
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.
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.
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
{
AI12-0340-1}
Bounded buffer objects should be implemented without dynamic allocation.
Implementation Advice: Bounded buffer
objects should be implemented without dynamic allocation.
Extensions to Ada 2012
{
AI12-0340-1}
The packages Strings.Text_Buffers, Strings.Text_Buffers.Unbounded,
and Strings.Text_Buffers.Bounded are new.
Ada 2005 and 2012 Editions sponsored in part by Ada-Europe