DataMuseum.dk

Presents historical artifacts from the history of:

Rational R1000/400 Tapes

This is an automatic "excavation" of a thematic subset of
artifacts from Datamuseum.dk's BitArchive.

See our Wiki for more about Rational R1000/400 Tapes

Excavated with: AutoArchaeologist - Free & Open Source Software.


top - download
Index: ┃ S T

⟦f4dcf6c6c⟧ TextFile

    Length: 49427 (0xc113)
    Types: TextFile
    Names: »ST_HELP«

Derivation

└─⟦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⟧ 

TextFile


  @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.