|
DataMuseum.dkPresents historical artifacts from the history of: Rational R1000/400 Tapes |
This is an automatic "excavation" of a thematic subset of
See our Wiki for more about Rational R1000/400 Tapes Excavated with: AutoArchaeologist - Free & Open Source Software. |
top - downloadIndex: ┃ S T ┃
Length: 49427 (0xc113)
Types: TextFile
Names: »ST_HELP«
└─⟦5f3412b64⟧ Bits:30000745 8mm tape, Rational 1000, ENVIRONMENT 12_6_5 TOOLS
└─ ⟦91c658230⟧ »DATA«
└─⟦f6fec0485⟧
└─⟦this⟧
└─⟦d10a02448⟧ Bits:30000409 8mm tape, Rational 1000, ENVIRONMENT, D_12_7_3
└─ ⟦fc9b38f02⟧ »DATA«
└─⟦f95d63c89⟧
└─⟦this⟧
@node !Tools.Bounded_String
Package Bounded_String provides a set of operations on objects
of the Variable_String type. This type defines a dynamic string
with a fixed maximum length. The length of the string is contained
in the string itself. Note that the implementation of Variable-
_String type is not based on pointers or tasks; thus, objects of
Variable_String type can be written into files.
The package contains several operations on the type that can raise
the predefined Constraint_Error exception. Some operations can
also raise the predefined Numeric_Error exception if invalid or
uninitialized characters are passed to these operations. These
two exceptions are the only exceptions or error conditions that
operations in these packages can produce. The "Errors" section
in the reference entry for each procedure or function specifies
whether the operation can produce the exceptions and under what
conditions.
@node !Tools.Bounded_String.Append
procedure Append (Target : in out Variable_String;
Source : Variable_String);
procedure Append (Target : in out Variable_String;
Source : String);
procedure Append (Target : in out Variable_String;
Source : Character);
procedure Append (Target : in out Variable_String;
Source : Character;
Count : Natural);
Appends the source character or characters to the target string.
This procedure appends characters to the end of an existing
variable string. The length of the target variable string is
increased by the number of the characters in the source variable
string. The source can be another variable string, an Ada string,
a single character, or a single character appended the number of
times specified by the Count parameter.
@node !Tools.Bounded_String.Char_At
function Char_At (Source : Variable_String;
At_Pos : Positive) return Character;
Returns the character at the specified position in the source
string.
@node !Tools.Bounded_String.Copy
procedure Copy (Target : in out Variable_String;
Source : Variable_String);
procedure Copy (Target : in out Variable_String;
Source : String);
procedure Copy (Target : in out Variable_String;
Source : Character);
Copies the character(s) in the source variable string into the
target variable string. The previous contents of the string are
lost.
After execution of this procedure, the current length of the target
variable string will be the length of the source.
@node !Tools.Bounded_String.Delete
procedure Delete (Target : in out Variable_String;
At_Pos : Positive;
Count : Natural := 1);
Deletes the character(s) from the specified position in the target
variable string.
This procedure deletes characters from the At_Pos position in the
variable string. The length of the target is decreased by the
value of the Count parameter.
@node !Tools.Bounded_String.Extract
function Extract (Source : Variable_String;
Start_Pos : Positive;
End_Pos : Natural) return String;
Extracts a string from the starting position to the ending position
from the source variable string.
This function returns the portion of the variable string that
begins with the character at the Start_Pos position and ends with
the character at the End_Pos position. The returned string has
an index of (Start_Pos .. End_Pos). When the value of End_Pos is
less than the value of Start_Pos, the returned string is null.
@node !Tools.Bounded_String.Free
procedure Free (V : in out Variable_String);
Frees the specified variable string, setting its length to 0.
This procedure frees the specified object by setting its length to
0. The previous contents of the object are lost.
@node !Tools.Bounded_String.Image
function Image (V : Variable_String) return String;
Converts the variable string into an Ada predefined string.
This function converts an object of the Variable_String type to the
String type. If the input has a length of 0, then the result is the
null string. The result has the same length as the current length
of the input. The result has an index of 1 to the current length of
the input.
@node !Tools.Bounded_String.Insert
procedure Insert (Target : in out Variable_String;
At_Pos : Positive;
Source : Variable_String);
procedure Insert (Target : in out Variable_String;
At_Pos : Positive;
Source : String);
procedure Insert (Target : in out Variable_String;
At_Pos : Positive;
Source : Character);
procedure Insert (Target : in out Variable_String;
At_Pos : Positive;
Source : Character;
Count : Natural);
Inserts the specified character(s) from the source variable string
into the specified position in the target variable string.
This procedure inserts characters into the target, increasing the
length of the target by the number of characters in the source.
The characters are inserted between the character at the At_Pos
position and the character immediately before that position. The
source can be another variable string, an Ada string, a single
character, or a single character inserted the number of times
specified in the Count parameter.
@node !Tools.Bounded_String.Length
function Length (Source : Variable_String) return Natural;
Returns the current length of the source variable string.
@node !Tools.Bounded_String.Max_Length
function Max_Length (Source : Variable_String) return Natural;
Returns the maximum length of the source variable string.
@node !Tools.Bounded_String.Move
procedure Move (Target : in out Variable_String;
Source : in out Variable_String);
Moves the contents of the source variable string into the target
variable string, destroying the current contents of the source.
This procedure is equivalent to copying the source into the target
and then calling the Free procedure on the target.
@node !Tools.Bounded_String.Replace
procedure Replace (Target : in out Variable_String;
At_Pos : Positive;
Source : Character);
procedure Replace (Target : in out Variable_String;
At_Pos : Positive;
Source : Character;
Count : Natural);
procedure Replace (Target : in out Variable_String;
At_Pos : Positive;
Source : String);
procedure Replace (Target : in out Variable_String;
At_Pos : Positive;
Source : Variable_String);
Replaces character(s) in the target variable string with
character(s) from the source variable string.
The number of characters replaced is the number of characters in
the source. The length of the target remains the same. The source
can be another variable string, an Ada string, a single character,
or a single character the repeated number of times specified by the
Count parameter.
@node !Tools.Bounded_String.Set_Length
procedure Set_Length (Target : in out Variable_String;
New_Length : Natural;
Fill_With : Character := ' ');
Truncates or fills the variable string to the specified length.
This procedure sets the length of the target variable string to the
value specified in the New_Length parameter. When the new length
is less than the old length, the variable string is truncated.
When the new length is the same as the old length, the procedure
has no effect. When the new length is greater than the old length,
the variable string is extended with the new character positions
filled with the Fill_With parameter.
@node !Tools.Bounded_String.String_Length
subtype String_Length is Natural;
Defines the allowed values of the length of the variable string.
The length of the variable string can be between 0 and
Integer'Last, inclusive.
@node !Tools.Bounded_String.Value
function Value (S : String) return Variable_String;
function Value (S : String;
Max_Length : Natural) return Variable_String;
Converts the string into a variable string.
This function converts an object of the String type to the
Variable_String type. The current length of the result is the
same length as the length of the input string. The result has a
maximum length the same as the length of the string or as specified
in the Max_Length parameter.
@node !Tools.Bounded_String.Variable_String
type Variable_String (Maximum_Length : String_Length) is private;
Defines the abstract type.
The string's maximum length is determined by the discriminant.
Upon elaboration, an object of this type has a current length of
zero characters.
Implementation of the Variable_String type is not based on pointers
or tasks. This means that objects of the Variable_String type can
be written into files.
@node !Tools.String_Map_Generic
Generic package String_Map_Generic provides a means of mapping
string values to values of another type. This translation from
strings (called the domain type) to another type (called the range
type) is a one-to-one mapping.
Some operations can perform optional checks for domain values that
are already defined. For these operations a parameter selects the
action that should be taken when a supplied domain value is already
defined. The operation can complete or it can be aborted, raising
the Multiply_Defined exception (in this package). Also, if any
operation is passed illegal input, the Constraint_Error exception
is raised.
The implementation of this generic package uses a hash table.
The size of the hash table (the number of buckets) is one of the
formal parameters of the generic. The hash function is built into
the generic for dividing the string values of the domain into the
buckets.
The formal parameters to the generic are:
generic
Size : in Integer;
type Range_Type is private;
Ignore_Case : Boolean := True;
package String_Map_Generic is
...
end String_Map_Generic;
@node !Tools.String_Map_Generic.Cardinality
function Cardinality (The_Map : Map) return Natural;
Returns the number of mappings defined in The_Map parameter.
@node !Tools.String_Map_Generic.Copy
procedure Copy (Target : in out Map;
Source : Map);
Copies the contents of the source map into the target map.
This procedure first deletes all entries from the target and then
adds an entry in the target for each entry in the source.
@node !Tools.String_Map_Generic.Define
procedure Define (The_Map : in out Map;
D : String;
R : Range_Type;
Trap_Multiples : Boolean := False);
Defines a correspondence between a string value and a range value.
This procedure creates entries in the map. The procedure traps
multiple definitions of string values when the Trap_Multiples
parameter is true. When the parameter is false, the string value
is redefined to the new range value.
@node !Tools.String_Map_Generic.Done
function Done (Iter : Iterator) return Boolean;
Determines whether the iteration over the map is complete.
@node !Tools.String_Map_Generic.Eval
function Eval (The_Map : Map;
D : String) return Range_Type;
Finds the corresponding value of the range given a map and a string
value.
This function returns a value of the range that corresponds to the
string value in the map. When the given value of the string does
not exist, the Undefined exception is raised.
@node !Tools.String_Map_Generic.Find
procedure Find (The_Map : Map;
D : String;
R : in out Range_Type;
Success : out Boolean);
Finds the range value corresponding to the specified domain value
(D) in the specified map.
This procedure finds the value of the range that corresponds to the
string value in the map. When the given value of the string exists
in the map, the Range parameter is updated with the range value,
and the Success parameter is returned true. When the given string
value does not exist, the Range parameter is not changed, and the
Success parameter is returned false.
@node !Tools.String_Map_Generic.Ignore_Case
Ignore_Case : Boolean := True;
Specifies whether comparisons on domain string values are case-
sensitive.
By default, all domain value comparisons are not case-sensitive.
@node !Tools.String_Map_Generic.Init
procedure Init (Iter : out Iterator;
The_Map : Map);
Initializes the iterator to iterate through all the entries in the
specified map.
This procedure initializes the iterator for the specified map.
When one or more entries exist in the map, the Value function
returns the first entry in the map using this value of the
iterator. When no entries exist in the map, the Done function
returns the value true using this value of the iterator.
@node !Tools.String_Map_Generic.Initialize
procedure Initialize (The_Map : out Map);
Creates an initialized and empty map.
This procedure creates a map; the map does not have to be created
by the Nil function. The map contains no entries.
@node !Tools.String_Map_Generic.Is_Empty
function Is_Empty (The_Map : Map) return Boolean;
Checks whether the specified map is empty.
This function checks whether the map contains no entries. When a
map is initialized or after the Make_Empty procedure is executed on
the map, this condition is true.
@node !Tools.String_Map_Generic.Is_Nil
function Is_Nil (The_Map : Map) return Boolean;
Checks whether the map is initialized.
This function checks the specified map to determine whether it has
been initialized. The map must be initialized before being used
with other procedures and functions in this package.
@node !Tools.String_Map_Generic.Iterator
type Iterator is private;
Defines a type that allows iterating over all entries in a map.
Objects of the Iterator type contain all of the information
necessary to step over all of the entries in a map. The type is
used with the Init and Next procedures and the Value and Done
functions.
@node !Tools.String_Map_Generic.Make_Empty
procedure Make_Empty (The_Map : in out Map);
Clears the map of all entries.
@node !Tools.String_Map_Generic.Map
type Map is private;
Defines the representation of the map.
Several important properties of the Map type are visible through
the implicit operations of assignment and equality. Assignment
for this type has the property that the contents of the map are
not copied but a new alias (a new name) for the map is created.
Equality for this type has the property that the values of the
maps are not compared but the names are compared. In other words,
the operation of equality checks to determine whether any two map
values designate the same map.
@node !Tools.String_Map_Generic.Multiply_Defined
Multiply_Defined : exception;
Defines the exception raised by the Define procedure when the
Domain parameter is already defined in the specified map and the
value of the Trap_Multiples parameter is true.
@node !Tools.String_Map_Generic.Next
procedure Next (Iter : in out Iterator);
Steps the iterator to point to the next entry in the map.
This procedure changes the iterator to point to the next entry in
the map. When the iterator steps past the last entry, the Done
function returns the value true.
@node !Tools.String_Map_Generic.Nil
function Nil return Map;
Returns an uninitialized map.
This function creates a new map. The map is uninitialized, and it
must be initialized before it can be used.
@node !Tools.String_Map_Generic.Range_Type
type Range_Type is private;
Defines the type for the range of the map.
The type must be a pure value type, and it must be constrained.
The implicit operations of assignment and equality must work with
values of this type.
@node !Tools.String_Map_Generic.Size
Size : Integer;
Defines the size of the hash table in the map.
The value provided for this generic parameter depends on the number
of expected or allowed values of the string domain. Preferred
values are prime numbers.
@node !Tools.String_Map_Generic.Undefine
procedure Undefine (The_Map : in out Map;
D : String);
Removes a map entry or entries for the string value.
This procedure removes all entries for the specified string value
from the map. When the string value does not exist in the map, the
procedure raises the Undefined exception.
@node !Tools.String_Map_Generic.Undefined
Undefined : exception;
Defines the exception raised by the Eval function or the Undefine
procedure when the Domain parameter does not exist in the specified
map.
@node !Tools.String_Map_Generic.Value
function Value (Iter : Iterator) return String;
Returns the string value of the current entry pointed to by the
iterator.
@node !Tools.String_Table
Package String_Table provides a set of operations on tables of
unique strings. The string table can be of any size, although the
size of the hash table for the strings is specified when the string
table is created. The operations of this package assure that the
table does not contain duplicate strings.
The Numeric_Error exception can be raised if invalid or
uninitialized characters are passed to these operations. If
other illegal parameters are passed to any of the operations in
this package, the Constraint_Error exception is raised. If any
of the operations that add entries to the table are attempted when
the table is full, the Table_Full exception (in this package) is
raised.
@node !Tools.String_Table.Allocate
function Allocate (Source : String;
In_Table : Table) return Item;
Creates an item for the specified string in the specified table.
This function returns an item that represents the specified string.
The string is not inserted into the table.
@node !Tools.String_Table.Char_At
function Char_At (Source : Item;
At_Pos : Natural) return Character;
Returns the specified character from the unique string.
This function provides access to individual characters in the
corresponding string of the item.
@node !Tools.String_Table.Done
function Done (Iter : Iterator) return Boolean;
Checks whether the iteration over the table is complete.
This function checks whether the iterator has stepped through all
of the entries in the table.
@node !Tools.String_Table.Equal
function Equal (L : Item;
R : Item) return Boolean;
Determines whether the two unique strings are equal.
@node !Tools.String_Table.Find
function Find (Source : String;
In_Table : Table;
Ignore_Case : Boolean := True) return Item;
Searches the table for the unique string.
This function searches the table for the string. When the string
is in the table, its corresponding item is returned. When the
string is not in the table, the nil item is returned.
@node !Tools.String_Table.Image
function Image (Source : Item) return String;
Returns the corresponding string of the item.
@node !Tools.String_Table.Init
procedure Init (Iter : out Iterator;
The_Table : Table);
Initializes the iterator to iterate through all the items in the
specified table.
When one or more entries exist in the table, the Value function
returns the first entry in the table using this value of the
iterator. When no entries exist in the table, the Done function
returns the value true using this value of the iterator.
@node !Tools.String_Table.Is_Nil
function Is_Nil (Source : Item) return Boolean;
Determines whether the specified item is equal to nil.
@node !Tools.String_Table.Item
type Item is private;
Defines the type used to represent strings in the table.
The Item type provides a handle for manipulating strings.
Typically, strings are added to the table and item values are
returned. The strings can then be manipulated by passing these
values to operations in this package.
@node !Tools.String_Table.Iterator
type Iterator is private;
Defines a type that allows iterating over all entries in a table.
Objects of this type contain all of the information necessary to
step over all of the entries in a table. The type is used with the
Init and Next procedures and the Value and Done functions.
@node !Tools.String_Table.Length
function Length (Source : Item) return Natural;
Returns the length of the corresponding string of the item.
@node !Tools.String_Table.New_Table
function New_Table (Minimum_Table_Size : Natural := 127) return Table;
Creates an empty table of the specified size.
This function creates a string table of the specified minimum size.
The table initially has no strings in it. The parameter specifies
the hash table size for the new table.
@node !Tools.String_Table.Next
procedure Next (Iter : in out Iterator);
Steps the iterator to point to the next entry in the table.
This procedure changes the iterator to point to the next entry in
the table. Although the table is unordered, the iterator steps
through all entries one by one. When the iterator steps past the
last entry, the Done function returns the value true.
@node !Tools.String_Table.Nil
function Nil return Item;
Returns a nil item.
This function returns an item that does not represent any possible
string. When the Find function determines that the specified
string is not in the table, this value of the Item type is
returned.
@node !Tools.String_Table.Table
type Table is private;
Defines the representation of the table.
Several important properties of the Table type are visible through
the implicit operations of assignment and equality. Assignment
for this type has the property that the contents of the table are
not copied but a new alias (a new name) for the table is created.
Equality for this type has the property that the values of the
tables are not compared but the names are compared. In other
words, the operation of equality checks to determine whether any
two table values designate the same table.
@node !Tools.String_Table.Table_Full
Table_Full : exception;
Defines an error condition that results when an operation
attempting to add an entry to a table finds the table full.
@node !Tools.String_Table.Unique
function Unique (Source : String;
In_Table : Table;
Ignore_Case : Boolean := True) return Item;
Inserts, if necessary, the specified unique string in the specified
table and returns the corresponding item.
This function checks whether the source string is in the table.
When the source string is in the table, the corresponding item is
returned. When the string is not in the table, the string is added
to the table and the corresponding item of the inserted string is
returned.
@node !Tools.String_Table.Unique_Index
function Unique_Index (U : Item) return Integer;
Returns a unique index for each item.
This function provides a mechanism for hashing the entries in the
table. It translates the item of a string into a unique index.
@node !Tools.String_Table.Value
function Value (Iter : Iterator) return Item;
Returns the item representing the string of the current entry
pointed to by the iterator.
@node !Tools.String_Utilities
Package String_Utilities provides a series of utilities that
operate on the Ada predefined String type. These utilities
include:
o A hash function
o Case conversions
o Numeric conversions
o Cleaning and stripping utilities
o Searches
o Comparisons
The Numeric_Error exception can be raised if invalid or
uninitialized characters are passed to these operations.
@node !Tools.String_Utilities.Capitalize
function Capitalize (S : String) return String;
Returns the source string with the first letter of each word
capitalized.
@node !Tools.String_Utilities.Capitalize
procedure Capitalize (S : in out String);
Capitalizes the first letter of each word in the input string.
@node !Tools.String_Utilities.Equal
function Equal (Str1 : String;
Str2 : String;
Ignore_Case : Boolean := True) return Boolean;
Compares two strings for equality.
This function compares two strings in either a case-sensitive
or case-insensitive way. When the two strings are equal, the
function returns true. This function is the same as the Ada
predefined equality operation on strings, except that it can be
case-insensitive.
@node !Tools.String_Utilities.Greater_Than
function Greater_Than (Str1 : String;
Str2 : String;
Ignore_Case : Boolean := True) return Boolean;
Checks whether one string is greater than another string.
This function does an ASCII comparison of two strings. The strings
are compared from left to right, one character at a time. When a
character from the first string has an ASCII character code that is
greater than the corresponding character from the second string,
the function returns the value true. Otherwise, the function
returns the value false.
@node !Tools.String_Utilities.Hash_String
function Hash_String (S : String) return Integer;
Hashes the specified string into an integer.
@node !Tools.String_Utilities.Less_Than
function Less_Than (Str1 : String;
Str2 : String;
Ignore_Case : Boolean := True) return Boolean;
Checks whether one string is less than another string.
This function does an ASCII comparison of two strings. The strings
are compared from left to right, one character at a time. When a
character from the first string has an ASCII character code that is
less than the corresponding character from the second string, the
function returns the value true. Otherwise, the function returns
the value false.
@node !Tools.String_Utilities.Locate
function Locate (Fragment : String;
Within : String;
Ignore_Case : Boolean := True) return Natural;
function Locate (Fragment : Character;
Within : String;
Ignore_Case : Boolean := True) return Natural;
Finds the character or string fragment in the string from left to
right.
This function searches the specified string for the character or
string fragment. The search begins with the first character in
the string and proceeds from left to right. When the character or
string fragment is found, the function returns the index (not the
location) in the string of the character or the first character of
the string fragment. When the character or string fragment is not
found, the function returns the value of 0.
@node !Tools.String_Utilities.Lower_Case
function Lower_Case (C : Character) return Character;
function Lower_Case (S : String) return String;
Returns the specified character or string in all lowercase
characters.
@node !Tools.String_Utilities.Lower_Case
procedure Lower_Case (C : in out Character);
procedure Lower_Case (S : in out String);
Changes the specified character or string to all lowercase
characters.
@node !Tools.String_Utilities.Number_To_String
function Number_To_String (Value : Integer;
Base : Natural := 10;
Width : Natural := 0;
Leading : Character := ' ') return String;
function Number_To_String (Value : Long_Integer;
Base : Natural := 10;
Width : Natural := 0;
Leading : Character := ' ') return String;
Converts the specified value to a string of the specified base
padded to the specified width.
This function converts a value to a string. The string is
created in the specified base. The resulting string is padded
to the specified width with the specified leading character,
if necessary. Even if the string resulting from the conversion
without padding is more than the specified width, the entire string
will be returned.
@node !Tools.String_Utilities.Reverse_Locate
function Reverse_Locate (Fragment : String;
Within : String;
Ignore_Case : Boolean := True) return Natural;
function Reverse_Locate (Fragment : Character;
Within : String;
Ignore_Case : Boolean := True) return Natural;
Finds the character or string fragment in the string from right to
left.
This function searches the specified string for the character or
string fragment. The search begins with the last character in
the string and proceeds from right to left. When the character or
string fragment is found, the function returns the index (not the
location) in the string of the character or the last character of
the string fragment. When the character or string fragment is not
found, the function returns the value of 0.
@node !Tools.String_Utilities.String_To_Number
procedure String_To_Number (Source : String;
Target : out Integer;
Worked : out Boolean;
Base : Natural := 10);
procedure String_To_Number (Source : String;
Target : out Long_Integer;
Worked : out Boolean;
Base : Natural := 10);
Converts the specified string with the specified base to an integer
value.
This procedure converts a string to a value. The string is
evaluated in the specified base. When the conversion is completed
correctly, the Worked parameter is returned true and the resulting
integer is returned in the Target parameter.
@node !Tools.String_Utilities.Strip
function Strip (From : String;
Filler : Character := ' ') return String;
Removes zero or more characters from both the beginning and the end
of the specified string.
This function strips leading and trailing characters from a string.
Zero or more of the specified characters are stripped from the
beginning and from the end of the string. When the first and last
characters of the string are not the specified characters, the
string is returned unchanged.
@node !Tools.String_Utilities.Strip_Leading
function Strip_Leading (From : String;
Filler : Character := ' ') return String;
Removes zero or more characters from the beginning of the specified
string.
This function strips leading characters from a string. Zero or
more of the specified characters are stripped from the beginning
of the string. When the first character of the string is not the
specified character, the string is returned unchanged.
@node !Tools.String_Utilities.Strip_Trailing
function Strip_Trailing (From : String;
Filler : Character := ' ') return String;
Removes zero or more characters from the end of the specified
string.
This function strips trailing characters from a string. Zero or
more of the specified characters are stripped from the end of the
string. When the last character of the string is not the specified
character, the string is returned unchanged.
@node !Tools.String_Utilities.Upper_Case
function Upper_Case (C : Character) return Character;
function Upper_Case (S : String) return String;
Returns the specified character or string in all uppercase
characters.
@node !Tools.String_Utilities.Upper_Case
procedure Upper_Case (C : in out Character);
procedure Upper_Case (S : in out String);
Changes the specified character or string to all uppercase
characters.
@node !Tools.Table_Formatter
This package is used to produce neatly formatted tables with
centered headers and even amounts of white space between the
columns. Columns consist of a title and a series of entries that
can be justified left or right or centered. Each entry can be a
single item or multiple subitems (see the example below). This
package also allows the rows in the table to be sorted on a field
or a set of fields.
A table is created through the following sequence of steps:
1. Create a table formatter for the number of columns needed
by instantiating the package with the appropriate number of
columns.
2. Define the headers for each column and the kind of justification
desired for that column by calling the Header procedure once for
each column.
3. Enter the items for each column a row at a time. If the entry
consists of a single item, call the Item procedure. If the
entry comprises multiple subitems, call the Subitem procedure
once for each subitem in the item and terminate the entry with a
call to the Last_Subitem procedure.
4. Sort the table if desired on a single field or on a set of
fields.
5. Print the table that has been defined by calling the Display
procedure.
Each instantiation of this package internally allocates enough
memory to save a copy of the entire table. Thus it is a good idea
to instantiate this package in a local frame so that all the memory
it allocates is reclaimed when the frame is discarded.
The formal parameters to the generic are:
generic
Number_Of_Columns : Positive;
Subitem_Separator : String := " ";
package Table_Formatter is
...
end Table_Formatter;
The Number_Of_Columns parameter defines the number of
columns that the table should have. The Subitem_Separator
parameter defines the string that should be used to separate the
subitems in entries composed of multiple subitems.
@node !Tools.Table_Formatter.Adjust
type Adjust is (Left, Right, Centered);
Defines the types of justification available for column entries.
Centered
Causes items to be centered in a column.
Left
Causes items to be aligned along the left margin of a column.
Right
Causes items to be aligned along the right margin of a column.
@node !Tools.Table_Formatter.Display
procedure Display (On_File : Io.File_Type);
Causes the table that has been created to be written into the
specified file.
@node !Tools.Table_Formatter.Field_List
type Field_List is array (Integer range <>) of Positive;
Defines an array of field numbers to be used in sorting a table.
Each entry in the array should contain the number of a column of
the table on which to be sorted. If multiple columns are supplied,
the comparison operation used in sorting compares the items in
the first field of the array, and then, if necessary, it continues
comparing as many successive fields as necessary to determine if
one row is less than another.
@node !Tools.Table_Formatter.Header
procedure Header (S : String;
Format : Adjust := Left);
Defines the header for the next column of the table being defined
to be the specified string and sets the justification for that
column.
The headers of a table are defined sequentially from left to right
before items are entered or the table is displayed.
@node !Tools.Table_Formatter.Item
procedure Item (S : String);
Adds the specified string as the next item in the table being
defined.
The entries in the table are entered a row at a time from left to
right once the headers have been defined and before the table is
displayed.
@node !Tools.Table_Formatter.Last_Subitem
procedure Last_Subitem;
Indicates that the definition of an item composed of multiple
subitems is complete.
The entries in the table are entered a row at a time from left to
right once the headers have been defined and before the table is
displayed. An entry can be a single item or it can be composed
of multiple subitems. The subitems for an item are entered from
left to right and are terminated by a call to the Last_Subitem
procedure. Note that if no subitems are entered, the call to
Last_Subitem will cause an empty entry in the table.
@node !Tools.Table_Formatter.Number_Of_Columns
Number_Of_Columns : Positive;
Defines the number of columns for the table.
@node !Tools.Table_Formatter.Sort
procedure Sort (On_Field : Positive := 1);
procedure Sort (On_Fields : Field_List);
Sorts the rows of a table that has been defined based on the sort
fields supplied.
The sort fields define the columns of the table that should be
used in the comparison of rows of the table. If multiple columns
are supplied, the comparison operation used in sorting compares
the items in the first field of the array, and then, if necessary,
it continues comparing as many successive fields as necessary to
determine if one row is less than another.
@node !Tools.Table_Formatter.Subitem
procedure Subitem (S : String);
Adds the specified string as the next subitem of an entry composed
of multiple subitems in the table being defined.
The entries in the table are entered a row at a time from left to
right once the headers have been defined and before the table is
displayed. An entry can be a single item or it can be composed
of multiple subitems. The subitems for an item are entered from
left to right and are terminated by a call to the Last_Subitem
procedure. Note that if no subitems are entered, the call to
Last_Subitem will cause an empty entry in the table.
@node !Tools.Table_Formatter.Subitem_Separator
Subitem_Separator : String := " ";
Defines the string to be used to separate the subitems for items
composed of multiple subitems.
@node !Tools.Unbounded_String
Package Unbounded_String provides a set of operations on objects of
the Variable_String type. This type defines a dynamic string with
no fixed maximum length. The length of the string is a property of
the string itself.
The package performs storage allocation to allow strings to grow
dynamically. If strings are no longer needed, their storage can
be reclaimed by calling the Free procedure. This package should
not be used in a multitasking program unless the user guarantees
sequential use of the operations provided.
The package contains several operations that can raise the
predefined Constraint_Error exception if improper or illegal input
parameter values are provided. Some operations can also raise the
predefined Numeric_Error exception if invalid or uninitialized
characters are passed to these operations.
The formal parameter to the generic is:
generic
Default_Maximum_Length : Natural := 20;
package Unbounded_String is
...
end Unbounded_String;
This parameter defines the number of characters in the default
storage allocated for new variable strings. This storage is always
greater than or equal to the current length of the string and will
grow dynamically as the length of the string is increased.
@node !Tools.Unbounded_String.Append
procedure Append (Target : in out Variable_String;
Source : Variable_String);
procedure Append (Target : in out Variable_String;
Source : String);
procedure Append (Target : in out Variable_String;
Source : Character);
procedure Append (Target : in out Variable_String;
Source : Character;
Count : String_Length);
Appends the source character or characters to the target string.
This procedure appends characters to the end of an existing
variable string. The length of the target variable string is
increased by the number of characters in the source variable
string. The source can be another variable string, an Ada string,
a single character, or a single character appended the number of
times specified by the Count parameter.
@node !Tools.Unbounded_String.Char_At
function Char_At (Source : Variable_String;
At_Pos : Positive) return Character;
Returns the character at the specified position in the source
string.
@node !Tools.Unbounded_String.Copy
procedure Copy (Target : in out Variable_String;
Source : Variable_String);
procedure Copy (Target : in out Variable_String;
Source : String);
procedure Copy (Target : in out Variable_String;
Source : Character);
Copies the character(s) in the source variable string into the
target variable string.
This procedure copies the source character(s) into the target
variable string. The target becomes the same length as the source.
@node !Tools.Unbounded_String.Default_Maximum_Length
Default_Maximum_Length : Natural := 20;
Defines the number of characters in the default storage allocated
for new variable strings.
This storage is always greater than or equal to the current length
of the string and will grow dynamically as the length of the string
is increased.
@node !Tools.Unbounded_String.Delete
procedure Delete (Target : in out Variable_String;
At_Pos : Positive;
Count : String_Length := 1);
Deletes a character or characters from the specified position in
the target variable string.
This procedure deletes characters at the At_Pos position from the
variable string. The length of the target is decreased by the
value of the Count parameter.
@node !Tools.Unbounded_String.Extract
function Extract (Source : Variable_String;
Start_Pos : Positive;
End_Pos : Natural) return String;
Extracts a string from the starting position to the ending position
from the source variable string.
This function returns the portion of the variable string that
begins with the character at the Start_Pos position and ends with
the character at the End_Pos position. When the value of End_Pos
is less than the value of Start_Pos, the returned string is null.
@node !Tools.Unbounded_String.Free
procedure Free (V : in out Variable_String);
Reclaims the storage associated with the specified variable string
and sets it to the null string.
@node !Tools.Unbounded_String.Image
function Image (V : Variable_String) return String;
Converts the variable string into an Ada predefined string.
This function converts an object of the Variable_String type to the
String type. If the input has a length of 0, the result is the null
string. The result has the same length as the current length of
the input and the index range is 1 .. length.
@node !Tools.Unbounded_String.Insert
procedure Insert (Target : in out Variable_String;
At_Pos : Positive;
Source : Variable_String);
procedure Insert (Target : in out Variable_String;
At_Pos : Positive;
Source : String);
procedure Insert (Target : in out Variable_String;
At_Pos : Positive;
Source : Character);
procedure Insert (Target : in out Variable_String;
At_Pos : Positive;
Source : Character;
Count : String_Length);
Inserts a character or characters from the source variable string
into the specified position in the target variable string.
This procedure inserts characters into the target, increasing the
length of the target by the number of characters in the source.
The characters are inserted between the character at the At_Pos
position and the character immediately before that position. The
source can be another variable string, an Ada string, a single
character, or a single character inserted the number of times
specified by the Count parameter.
@node !Tools.Unbounded_String.Is_Nil
function Is_Nil (V : Variable_String) return Boolean;
Returns true if the indicated string is a null variable string---
that is, the variable string returned by the Nil function.
Note that the null string is not the same as the string with the
value "".
@node !Tools.Unbounded_String.Length
function Length (Source : Variable_String) return String_Length;
Returns the current length of the source variable string.
@node !Tools.Unbounded_String.Move
procedure Move (Target : in out Variable_String;
Source : in out Variable_String);
Moves the contents of the source variable string to the target
variable string, destroying the contents of the source and freeing
the storage associated with the source.
This procedure is equivalent to copying the source to the target
and then calling the Free procedure on source to reclaim its
storage and set its value to the null string.
@node !Tools.Unbounded_String.Nil
function Nil return Variable_String;
Returns the null string.
Note that the null string is not the same as the string with the
value "".
@node !Tools.Unbounded_String.Replace
procedure Replace (Target : in out Variable_String;
At_Pos : Positive;
Source : Character);
procedure Replace (Target : in out Variable_String;
At_Pos : Positive;
Source : Character;
Count : String_Length);
procedure Replace (Target : in out Variable_String;
At_Pos : Positive;
Source : String);
procedure Replace (Target : in out Variable_String;
At_Pos : Positive;
Source : Variable_String);
Replaces character(s) in the target variable string with
character(s) from the source variable string.
This procedure replaces characters in the target with characters
from the source. The length of the target remains the same. The
number of characters replaced is the number of characters in the
source. The source can be another variable string, an Ada string,
a single character, or a single character repeated the number of
times specified by the Count parameter.
@node !Tools.Unbounded_String.Set_Length
procedure Set_Length (Target : in out Variable_String;
New_Length : String_Length;
Fill_With : Character := ' ');
Truncates or fills the variable string to the specified length.
This procedure sets the length of the target variable string to
the value of the New_Length parameter. When the new length is
less than the old length, the variable string is truncated. When
the new length is the same as the old length, the procedure has no
effect. When the new length is greater than the old length, the
variable string is extended with the new character positions filled
with the Fill_With parameter.
@node !Tools.Unbounded_String.String_Length
subtype String_Length is Natural;
Defines the allowed values of the length of the variable string.
The length of the variable string can be between 0 and
Integer'Last, inclusive.
@node !Tools.Unbounded_String.Value
function Value (S : String) return Variable_String;
Converts the string into a variable string.
This function converts an object of the String type to the
Variable_String type. The result has the same length as the length
of the string.
@node !Tools.Unbounded_String.Variable_String
type Variable_String is private;
Defines the representation of a variable string.
Several important properties of the Variable_String type are
visible through the implicit operations of assignment and
equality. Assignment for this type has the property that the
contents of a variable string are not copied but a new alias (a
new name) for the string is created. Equality for this type has
the property that the values of the strings are not compared
but the names are compared. In other words, the operation of
equality checks to determine whether any two variable string values
designate the same variable string.