Strings

package Ada.Strings
   with Pure is

   Space          : constant Character           := ' ';
   Wide_Space     : constant Wide_Character      := ' ';
   Wide_Wide_Space: constant Wide_Wide_Character := ' ';

   Length_Error     : exception;
   Pattern_Error    : exception;
   Index_Error      : exception;
   Translation_Error: exception;

   type Alignment  is (Left, Right, Center);
   type Truncation is (Left, Right, Error);
   type Membership is (Inside, Outside);
   type Direction  is (Forward, Backward);
   type Trim_End   is (Left, Right, Both);
end Ada.Strings;

Maps

The package Strings.Maps defines the types, operations, and other entities necessary for character sets and character-to-character mappings.

package Ada.Strings.Maps
   with Pure is

   -- Representation for a set of character values:
   type Character_Set is private
      with Preelaborable_Initialization;

   Null_Set: constant Character_Set;

   -- Represents Character range Low..High
   type Character_Range is record
      Low : Character;
      High: Character;
   end record;

   type Character_Ranges is array(Positive range <>) of Character_Range;

   function To_Set   (Ranges: Character_Ranges) return Character_Set;
   function To_Set   (Span  : Character_Range)  return Character_Set;
   function To_Ranges(Set   : Character_Set)    return Character_Ranges;

   function "="  (Left, Right: Character_Set) return Boolean;
   function "-"  (Left, Right: Character_Set) return Character_Set;
   function "and"(Left, Right: Character_Set) return Character_Set;
   function "or" (Left, Right: Character_Set) return Character_Set;
   function "xor"(Left, Right: Character_Set) return Character_Set;
   function "not"(Right: Character_Set)       return Character_Set;

   function Is_In    (Element : Character    ; Set: Character_Set) return Boolean;
   function Is_Subset(Elements: Character_Set; Set: Character_Set) return Boolean;

   function "<="(Left: Character_Set; Right: Character_Set) return Boolean renames Is_Subset;

   -- Alternative representation for a set of character values:
   subtype Character_Sequence is String;

   function To_Set     (Sequence: Character_Sequence) return Character_Set;
   function To_Set     (Singleton: Character)         return Character_Set;
   function To_Sequence(Set: Character_Set)           return Character_Sequence;

   -- Representation for a character to character mapping:
   type Character_Mapping is private
      with Preelaborable_Initialization;

   function Value(Map: Character_Mapping; Element: Character) return Character;

   Identity: constant Character_Mapping;
   function To_Mapping(From, To: Character_Sequence) return Character_Mapping;
   function To_Domain (Map: Character_Mapping)       return Character_Sequence;
   function To_Range  (Map: Character_Mapping)       return Character_Sequence;

   type Character_Mapping_Function is access function(From: Character) return Character;
end Ada.Strings.Maps;

Example of use of Strings.Maps.To_Mapping

To_Mapping("ABCD", "ZZAB") returns a Character_Mapping that maps 'A' and 'B' to 'Z', 'C' to 'A', 'D' to 'B', and each other Character to itself.

String Map Constants

The language-defined package Strings.Maps.Constants declares Character_Set and Character_Mapping constants corresponding to classification and conversion functions in package Characters.Handling.

package Ada.Strings.Maps.Constants
   with Pure is

   Control_Set          : constant Character_Set;
   Graphic_Set          : constant Character_Set;
   Letter_Set           : constant Character_Set;
   Lower_Set            : constant Character_Set;
   Upper_Set            : constant Character_Set;
   Basic_Set            : constant Character_Set;
   Decimal_Digit_Set    : constant Character_Set;
   Hexadecimal_Digit_Set: constant Character_Set;
   Alphanumeric_Set     : constant Character_Set;
   Special_Set          : constant Character_Set;
   ISO_646_Set          : constant Character_Set;

   Lower_Case_Map: constant Character_Mapping; -- Maps to lower case for letters, else identity
   Upper_Case_Map: constant Character_Mapping; -- Maps to upper case for letters, else identity
   Basic_Map     : constant Character_Mapping; -- Maps to basic letter for letters, else identity
end Ada.Strings.Maps.Constants;

Wide Maps

Facilities for handling strings of Wide_Character elements are found in the packages Strings.Wide_Maps, Strings.Wide_Fixed, Strings.Wide_Bounded, Strings.Wide_Unbounded, and Strings.Wide_Maps.Wide_Constants, and in the library functions Strings.Wide_Hash, Strings.Wide_Fixed.Wide_Hash, Strings.Wide_Bounded.Wide_Hash, Strings.Wide_Unbounded.Wide_Hash, Strings.Wide_Hash_Case_Insensitive, Strings.Wide_Fixed.Wide_Hash_Case_Insensitive, Strings.Wide_Bounded.Wide_Hash_Case_Insensitive, Strings.Wide_Unbounded.Wide_Hash_Case_Insensitive, Strings.Wide_Equal_Case_Insensitive, Strings.Wide_Fixed.Wide_Equal_Case_Insensitive, Strings.Wide_Bounded.Wide_Equal_Case_Insensitive, and Strings.Wide_Unbounded.Wide_Equal_Case_Insensitive. They provide the same string-handling operations as the corresponding packages and functions for strings of Character elements.

package Ada.Strings.Wide_Maps
   with Preelaborate, Nonblocking, Global => in out synchronized is

   -- Representation for a set of Wide_Character values:
   type Wide_Character_Set is private
      with Preelaborable_Initialization;

   Null_Set: constant Wide_Character_Set;

   type Wide_Character_Range is record
      Low : Wide_Character;
      High: Wide_Character;
   end record; -- Represents Wide_Character range Low..High

   type Wide_Character_Ranges is array(Positive range <>) of Wide_Character_Range;

   function To_Set(Ranges: Wide_Character_Ranges) return Wide_Character_Set;
   function To_Set(Span  : Wide_Character_Range)  return Wide_Character_Set;

   function To_Ranges(Set: Wide_Character_Set) return Wide_Character_Ranges;

   function "="(Left, Right: Wide_Character_Set) return Boolean;

   function "not"(Right: Wide_Character_Set)       return Wide_Character_Set;
   function "and"(Left, Right: Wide_Character_Set) return Wide_Character_Set;
   function "or" (Left, Right: Wide_Character_Set) return Wide_Character_Set;
   function "xor"(Left, Right: Wide_Character_Set) return Wide_Character_Set;
   function "-"  (Left, Right: Wide_Character_Set) return Wide_Character_Set;

   function Is_In    (Element : Wide_Character    ; Set: Wide_Character_Set) return Boolean;
   function Is_Subset(Elements: Wide_Character_Set; Set: Wide_Character_Set) return Boolean;
   function "<="(Left: Wide_Character_Set; Right: Wide_Character_Set) return Boolean renames Is_Subset;

   -- Alternative representation for a set of Wide_Character values:
   subtype Wide_Character_Sequence is Wide_String;

   function To_Set(Sequence : Wide_Character_Sequence) return Wide_Character_Set;
   function To_Set(Singleton: Wide_Character)          return Wide_Character_Set;
   function To_Sequence(Set: Wide_Character_Set) return Wide_Character_Sequence;

   -- Representation for a Wide_Character to Wide_Character mapping:
   type Wide_Character_Mapping is private
      with Preelaborable_Initialization;

   function Value(Map: Wide_Character_Mapping; Element: Wide_Character) return Wide_Character;

   Identity: constant Wide_Character_Mapping;

   function To_Mapping(From, To: Wide_Character_Sequence) return Wide_Character_Mapping;
   function To_Domain(Map: Wide_Character_Mapping)        return Wide_Character_Sequence;
   function To_Range (Map: Wide_Character_Mapping)        return Wide_Character_Sequence;

   type Wide_Character_Mapping_Function is access function(From: Wide_Character) return Wide_Character;
end Ada.Strings.Wide_Maps;

Wide Wide Maps

Facilities for handling strings of Wide_Wide_Character elements are found in the packages Strings.Wide_Wide_Maps, Strings.Wide_Wide_Fixed, Strings.Wide_Wide_Bounded, Strings.Wide_Wide_Unbounded, and Strings.Wide_Wide_Maps.Wide_Wide_Constants, and in the library functions Strings.Wide_Wide_Hash, Strings.Wide_Wide_Fixed.Wide_Wide_Hash, Strings.Wide_Wide_Bounded.Wide_Wide_Hash, Strings.Wide_Wide_Unbounded.Wide_Wide_Hash, Strings.Wide_Wide_Hash_Case_Insensitive, Strings.Wide_Wide_Fixed.Wide_Wide_Hash_Case_Insensitive, Strings.Wide_Wide_Bounded.Wide_Wide_Hash_Case_Insensitive, Strings.Wide_Wide_Unbounded.Wide_Wide_Hash_Case_Insensitive, Strings.Wide_Wide_Equal_Case_Insensitive, Strings.Wide_Wide_Fixed.Wide_Wide_Equal_Case_Insensitive, Strings.Wide_Wide_Bounded.Wide_Wide_Equal_Case_Insensitive, and Strings.Wide_Wide_Unbounded.Wide_Wide_Equal_Case_Insensitive. They provide the same string-handling operations as the corresponding packages and functions for strings of Character elements.

package Ada.Strings.Wide_Wide_Maps
   with Preelaborate, Nonblocking, Global => in out synchronized is

   -- Representation for a set of Wide_Wide_Character values:
   type Wide_Wide_Character_Set is private
      with Preelaborable_Initialization;

   Null_Set: constant Wide_Wide_Character_Set;

   type Wide_Wide_Character_Range is record
      Low : Wide_Wide_Character;
      High: Wide_Wide_Character;
   end record; -- Represents Wide_Wide_Character range Low..High

   type Wide_Wide_Character_Ranges is array(Positive range <>) of Wide_Wide_Character_Range;

   function To_Set(Ranges: Wide_Wide_Character_Ranges) return Wide_Wide_Character_Set;
   function To_Set(Span  : Wide_Wide_Character_Range)  return Wide_Wide_Character_Set;
   function To_Ranges(Set: Wide_Wide_Character_Set) return Wide_Wide_Character_Ranges;

   function "="(Left, Right: Wide_Wide_Character_Set) return Boolean;

   function "not"(Right: Wide_Wide_Character_Set)       return Wide_Wide_Character_Set;
   function "and"(Left, Right: Wide_Wide_Character_Set) return Wide_Wide_Character_Set;
   function "or" (Left, Right: Wide_Wide_Character_Set) return Wide_Wide_Character_Set;
   function "xor"(Left, Right: Wide_Wide_Character_Set) return Wide_Wide_Character_Set;
   function "-"  (Left, Right: Wide_Wide_Character_Set) return Wide_Wide_Character_Set;

   function Is_In    (Element : Wide_Wide_Character    ; Set: Wide_Wide_Character_Set) return Boolean;
   function Is_Subset(Elements: Wide_Wide_Character_Set; Set: Wide_Wide_Character_Set) return Boolean;
   function "<="(Left: Wide_Wide_Character_Set; Right: Wide_Wide_Character_Set) return Boolean renames Is_Subset;

   -- Alternative representation for a set of Wide_Wide_Character values:
   subtype Wide_Wide_Character_Sequence is Wide_Wide_String;

   function To_Set(Sequence : Wide_Wide_Character_Sequence) return Wide_Wide_Character_Set;
   function To_Set(Singleton: Wide_Wide_Character)          return Wide_Wide_Character_Set;
   function To_Sequence(Set: Wide_Wide_Character_Set)       return Wide_Wide_Character_Sequence;

   -- Representation for a Wide_Wide_Character to Wide_Wide_Character mapping:
   type Wide_Wide_Character_Mapping is private
      with Preelaborable_Initialization;

   function Value(Map: Wide_Wide_Character_Mapping; Element: Wide_Wide_Character) return Wide_Wide_Character;

   Identity: constant Wide_Wide_Character_Mapping;

   function To_Mapping(From, To: Wide_Wide_Character_Sequence) return Wide_Wide_Character_Mapping;
   function To_Domain (Map: Wide_Wide_Character_Mapping)       return Wide_Wide_Character_Sequence;
   function To_Range  (Map: Wide_Wide_Character_Mapping)       return Wide_Wide_Character_Sequence;

   type Wide_Wide_Character_Mapping_Function is access
      function(From: Wide_Wide_Character) return Wide_Wide_Character;
end Ada.Strings.Wide_Wide_Maps;

Fixed-Length Strings

The language-defined package Strings.Fixed provides string-handling subprograms for fixed-length strings; that is, for values of type Standard.String. Several of these subprograms are procedures that modify the contents of a String that is passed as an out or an in out parameter; each has additional parameters to control the effect when the logical length of the result differs from the parameter’s length.

For each function that returns a String, the lower bound of the returned value is 1.

The basic model embodied in the package is that a fixed-length string comprises significant characters and possibly padding (with space characters) on either or both ends. When a shorter string is copied to a longer string, padding is inserted, and when a longer string is copied to a shorter one, padding is stripped. The Move procedure in Strings.Fixed, which takes a String as an out parameter, allows the programmer to control these effects. Similar control is provided by the string transformation procedures.

with Ada.Strings.Maps;

package Ada.Strings.Fixed
   with Preelaborate, Nonblocking, Global => in out synchronized is

   -- "Copy" procedure for strings of possibly different lengths
   procedure Move(Source : String;
                  Target : out String;
                  Drop   : Truncation := Error;
                  Justify: Alignment  := Left;
                  Pad    : Character  := Space);

   -- Search subprograms
   function Index(Source : String;
                  Pattern: String;
                  From   : Positive;
                  Going  : Direction              := Forward;
                  Mapping: Maps.Character_Mapping := Maps.Identity) return Natural;
   function Index(Source : String;
                  Pattern: String;
                  From   : Positive;
                  Going  : Direction := Forward;
                  Mapping: Maps.Character_Mapping_Function) return Natural;
   function Index(Source : String;
                  Pattern: String;
                  Going  : Direction              := Forward;
                  Mapping: Maps.Character_Mapping := Maps.Identity) return Natural;
   function Index(Source : String;
                  Pattern: String;
                  Going  : Direction := Forward;
                  Mapping: Maps.Character_Mapping_Function) return Natural;
   function Index(Source: String;
                  Set   : Maps.Character_Set;
                  From  : Positive;
                  Test  : Membership := Inside;
                  Going : Direction  := Forward) return Natural;
   function Index(Source: String;
                  Set   : Maps.Character_Set;
                  Test  : Membership := Inside;
                  Going : Direction  := Forward) return Natural;
   function Index_Non_Blank(Source: String;
                            From  : Positive;
                            Going : Direction := Forward) return Natural;
   function Index_Non_Blank(Source: String; Going: Direction := Forward) return Natural;

   function Count(Source : String;
                  Pattern: String;
                  Mapping: Maps.Character_Mapping := Maps.Identity) return Natural;
   function Count(Source : String;
                  Pattern: String;
                  Mapping: Maps.Character_Mapping_Function) return Natural;
   function Count(Source: String; Set: Maps.Character_Set) return Natural;

   procedure Find_Token(Source: String;
                        Set   : Maps.Character_Set;
                        From  : Positive;
                        Test  : Membership;
                        First : out Positive;
                        Last  : out Natural);
   procedure Find_Token(Source: String;
                        Set   : Maps.Character_Set;
                        Test  : Membership;
                        First : out Positive;
                        Last  : out Natural);

   -- String translation subprograms
   function Translate(Source: String; Mapping: Maps.Character_Mapping)          return String;
   function Translate(Source: String; Mapping: Maps.Character_Mapping_Function) return String;

   procedure Translate(Source: in out String; Mapping: Maps.Character_Mapping);
   procedure Translate(Source: in out String; Mapping: Maps.Character_Mapping_Function);

   -- String transformation subprograms
   function Replace_Slice(Source: String; Low     : Positive; High: Natural; By: String) return String;
   function Insert       (Source: String; Before  : Positive; New_Item: String)          return String;
   function Overwrite    (Source: String; Position: Positive; New_Item: String)          return String;
   function Delete       (Source: String; From    : Positive; Through: Natural)          return String;
   procedure Replace_Slice(Source : in out String;
                           Low    : Positive;
                           High   : Natural;
                           By     : String;
                           Drop   : Truncation := Error;
                           Justify: Alignment  := Left;
                           Pad    : Character  := Space);
   procedure Insert(Source  : in out String;
                    Before  : Positive;
                    New_Item: String;
                    Drop    : Truncation := Error);
   procedure Overwrite(Source : in out String;
                      Position: Positive;
                      New_Item: String;
                      Drop    : Truncation := Right);
   procedure Delete(Source : in out String;
                    From   : Positive;
                    Through: Natural;
                    Justify: Alignment := Left;
                    Pad    : Character := Space);

   -- String selector subprograms
   function Trim(Source: String; Side: Trim_End)                                      return String;
   function Trim(Source: String; Left: Maps.Character_Set; Right: Maps.Character_Set) return String;
   function Head(Source: String; Count: Natural; Pad: Character := Space)             return String;
   function Tail(Source: String; Count: Natural; Pad: Character := Space)             return String;
   procedure Trim(Source : in out String;
                  Side   : Trim_End;
                  Justify: Alignment := Left;
                  Pad    : Character := Space);
   procedure Trim(Source : in out String;
                  Left   : Maps.Character_Set;
                  Right  : Maps.Character_Set;
                  Justify: Alignment := Strings.Left;
                  Pad    : Character := Space);
   procedure Head(Source : in out String;
                  Count  : Natural;
                  Justify: Alignment := Left;
                  Pad    : Character := Space);
   procedure Tail(Source : in out String;
                  Count  : Natural;
                  Justify: Alignment := Left;
                  Pad    : Character := Space);

   -- String constructor functions
   function "*"(Left: Natural; Right: Character) return String;
   function "*"(Left: Natural; Right: String)    return String;
end Ada.Strings.Fixed;

Bounded-Length Strings

The language-defined package Strings.Bounded provides a generic package each of whose instances yields a private type Bounded_String and a set of operations. An object of a particular Bounded_String type represents a String whose low bound is 1 and whose length can vary conceptually between 0 and a maximum size established at the generic instantiation. The subprograms for fixed-length string handling are either overloaded directly for Bounded_String, or are modified as necessary to reflect the variability in length. Additionally, since the Bounded_String type is private, appropriate constructor and selector operations are provided.

with Ada.Strings.Maps;

package Ada.Strings.Bounded
   with Preelaborate, Nonblocking, Global => in out synchronized is

   generic
      Max: Positive; -- Maximum length of a Bounded_String
   package Generic_Bounded_Length is
      Max_Length: constant Positive := Max;

      type Bounded_String is private;

      Null_Bounded_String: constant Bounded_String;

      subtype Length_Range is Natural range 0 .. Max_Length;

      function Length(Source: Bounded_String) return Length_Range;

      -- Conversion, Concatenation, and Selection functions
      function To_Bounded_String(Source: String; Drop: Truncation := Error) return Bounded_String;
      function To_String        (Source: Bounded_String)                    return String;

      procedure Set_Bounded_String(Target: out Bounded_String; Source: String; Drop: Truncation := Error);
      procedure Append(Source: in out Bounded_String; New_Item: Bounded_String; Drop: Truncation := Error);
      procedure Append(Source: in out Bounded_String; New_Item: String        ; Drop: Truncation := Error);
      procedure Append(Source: in out Bounded_String; New_Item: Character     ; Drop: Truncation := Error);
      function Append(Left, Right: Bounded_String; Drop: Truncation := Error) return Bounded_String;
      function Append(Left: Bounded_String; Right: String        ; Drop: Truncation := Error) return Bounded_String;
      function Append(Left: String        ; Right: Bounded_String; Drop: Truncation := Error) return Bounded_String;
      function Append(Left: Bounded_String; Right: Character     ; Drop: Truncation := Error) return Bounded_String;
      function Append(Left: Character     ; Right: Bounded_String; Drop: Truncation := Error) return Bounded_String;

      function "&"(Left, Right: Bounded_String)                 return Bounded_String;
      function "&"(Left: Bounded_String; Right: String)         return Bounded_String;
      function "&"(Left: String        ; Right: Bounded_String) return Bounded_String;
      function "&"(Left: Bounded_String; Right: Character)      return Bounded_String;
      function "&"(Left: Character     ; Right: Bounded_String) return Bounded_String;

      function          Element(Source:        Bounded_String; Index: Positive) return Character;
      procedure Replace_Element(Source: in out Bounded_String; Index: Positive; By: Character);

      function Slice(Source: Bounded_String; Low: Positive; High: Natural) return String;
      procedure Bounded_Slice(Source: Bounded_String;
                              Target: out Bounded_String;
                              Low   : Positive;
                              High  : Natural);
      function Bounded_Slice(Source: Bounded_String;
                             Low   : Positive;
                             High  : Natural)
         return Bounded_String;

      function "="(Left, Right: Bounded_String)                 return Boolean;
      function "="(Left: Bounded_String; Right: String)         return Boolean;
      function "="(Left: String        ; Right: Bounded_String) return Boolean;

      function "<"(Left, Right: Bounded_String)                 return Boolean;
      function "<"(Left: Bounded_String; Right: String)         return Boolean;
      function "<"(Left: String        ; Right: Bounded_String) return Boolean;

      function "<="(Left, Right: Bounded_String)                 return Boolean;
      function "<="(Left: Bounded_String; Right: String)         return Boolean;
      function "<="(Left: String        ; Right: Bounded_String) return Boolean;

      function ">"(Left, Right: Bounded_String)                 return Boolean;
      function ">"(Left: Bounded_String; Right: String)         return Boolean;
      function ">"(Left: String        ; Right: Bounded_String) return Boolean;

      function ">="(Left, Right: Bounded_String)                 return Boolean;
      function ">="(Left: Bounded_String; Right: String)         return Boolean;
      function ">="(Left: String        ; Right: Bounded_String) return Boolean;

      -- Search subprograms
      function Index(Source : Bounded_String;
                     Pattern: String;
                     From   : Positive;
                     Going  : Direction              := Forward;
                     Mapping: Maps.Character_Mapping := Maps.Identity)
         return Natural;
      function Index(Source : Bounded_String;
                     Pattern: String;
                     From   : Positive;
                     Going  : Direction := Forward;
                     Mapping: Maps.Character_Mapping_Function)
         return Natural;
      function Index(Source : Bounded_String;
                     Pattern: String;
                     Going  : Direction              := Forward;
                     Mapping: Maps.Character_Mapping := Maps.Identity)
         return Natural;
      function Index(Source : Bounded_String;
                     Pattern: String;
                     Going  : Direction := Forward;
                     Mapping: Maps.Character_Mapping_Function)
         return Natural;
      function Index(Source: Bounded_String;
                     Set   : Maps.Character_Set;
                     From  : Positive;
                     Test  : Membership := Inside;
                     Going : Direction  := Forward)
         return Natural;
      function Index(Source: Bounded_String;
                     Set   : Maps.Character_Set;
                     Test  : Membership := Inside;
                     Going : Direction  := Forward)
         return Natural;
      function Index_Non_Blank(Source: Bounded_String;
                               From  : Positive;
                               Going : Direction := Forward)
         return Natural;
      function Index_Non_Blank(Source: Bounded_String;
                               Going : Direction := Forward)
         return Natural;

      function Count(Source : Bounded_String;
                     Pattern: String;
                     Mapping: Maps.Character_Mapping := Maps.Identity)
         return Natural;
      function Count(Source : Bounded_String;
                     Pattern: String;
                     Mapping: Maps.Character_Mapping_Function)
         return Natural;
      function Count(Source: Bounded_String; Set: Maps.Character_Set) return Natural;

      procedure Find_Token(Source: Bounded_String;
                           Set   : Maps.Character_Set;
                           From  : Positive;
                           Test  : Membership;
                           First : out Positive;
                           Last  : out Natural);
      procedure Find_Token(Source: Bounded_String;
                           Set   : Maps.Character_Set;
                           Test  : Membership;
                           First : out Positive;
                           Last  : out Natural);

      -- String translation subprograms
      procedure Translate(Source: in out Bounded_String; Mapping: Maps.Character_Mapping);
      procedure Translate(Source: in out Bounded_String; Mapping: Maps.Character_Mapping_Function);
      function Translate(Source: Bounded_String; Mapping: Maps.Character_Mapping)
         return Bounded_String;
      function Translate(Source: Bounded_String; Mapping: Maps.Character_Mapping_Function)
         return Bounded_String;

      -- String transformation subprograms
      procedure Replace_Slice(Source: in out Bounded_String;
                              Low   : Positive;
                              High  : Natural;
                              By    : String;
                              Drop  : Truncation := Error);
      function Replace_Slice(Source: Bounded_String;
                             Low   : Positive;
                             High  : Natural;
                             By    : String;
                             Drop  : Truncation := Error)
         return Bounded_String;

      procedure Insert(Source  : in out Bounded_String;
                       Before  : Positive;
                       New_Item: String;
                       Drop    : Truncation := Error);
      function Insert(Source  : Bounded_String;
                      Before  : Positive;
                      New_Item: String;
                      Drop    : Truncation := Error)
         return Bounded_String;

      procedure Overwrite(Source  : in out Bounded_String;
                          Position: Positive;
                          New_Item: String;
                          Drop    : Truncation := Error);
      function Overwrite(Source  : Bounded_String;
                         Position: Positive;
                         New_Item: String;
                         Drop    : Truncation := Error)
         return Bounded_String;

      procedure Delete(Source: in out Bounded_String; From: Positive; Through: Natural);
      function  Delete(Source:        Bounded_String; From: Positive; Through: Natural)
         return Bounded_String;

      -- String selector subprograms
      function Trim(Source: Bounded_String; Side: Trim_End) return Bounded_String;
      procedure Trim(Source: in out Bounded_String; Side: Trim_End);
      function Trim(Source: Bounded_String;
                    Left  : Maps.Character_Set;
                    Right : Maps.Character_Set)
         return Bounded_String;
      procedure Trim(Source: in out Bounded_String;
                     Left  : Maps.Character_Set;
                     Right : Maps.Character_Set);
      function Head(Source: Bounded_String;
                    Count : Natural;
                    Pad   : Character  := Space;
                    Drop  : Truncation := Error)
         return Bounded_String;
      procedure Head(Source: in out Bounded_String;
                     Count : Natural;
                     Pad   : Character  := Space;
                     Drop  : Truncation := Error);
      function Tail(Source: Bounded_String;
                    Count : Natural;
                    Pad   : Character  := Space;
                    Drop  : Truncation := Error)
         return Bounded_String;
      procedure Tail(Source: in out Bounded_String;
                     Count : Natural;
                     Pad   : Character  := Space;
                     Drop  : Truncation := Error);

      -- String constructor subprograms
      function "*"(Left: Natural; Right: Character)      return Bounded_String;
      function "*"(Left: Natural; Right: String)         return Bounded_String;
      function "*"(Left: Natural; Right: Bounded_String) return Bounded_String;

      function Replicate(Count: Natural;
                         Item : Character;
                         Drop : Truncation := Error)
         return Bounded_String;
      function Replicate(Count: Natural;
                         Item : String;
                         Drop : Truncation := Error)
         return Bounded_String;
      function Replicate(Count: Natural;
                         Item : Bounded_String;
                         Drop : Truncation := Error)
         return Bounded_String;
   end Generic_Bounded_Length;
end Ada.Strings.Bounded;

Unbounded-Length Strings

The language-defined package Strings.Unbounded provides a private type Unbounded_String and a set of operations. An object of type Unbounded_String represents a String whose low bound is 1 and whose length can vary conceptually between 0 and Natural'Last. The subprograms for fixed-length string handling are either overloaded directly for Unbounded_String, or are modified as necessary to reflect the flexibility in length. Since the Unbounded_String type is private, relevant constructor and selector operations are provided.

with Ada.Strings.Maps;

package Ada.Strings.Unbounded
   with Preelaborate, Nonblocking, Global => in out synchronized is

   type Unbounded_String is private
      with Preelaborable_Initialization;

   Null_Unbounded_String: constant Unbounded_String;

   function Length(Source: Unbounded_String) return Natural;

   type String_Access is access all String;
   procedure Free(X: in out String_Access);

   -- Conversion, Concatenation, and Selection functions
   function To_Unbounded_String(Source: String) return Unbounded_String;
   function To_Unbounded_String(Length: Natural) return Unbounded_String;
   function To_String(Source: Unbounded_String) return String;

   procedure Set_Unbounded_String(Target: out Unbounded_String; Source: String);
   procedure Append(Source: in out Unbounded_String; New_Item: Unbounded_String);
   procedure Append(Source: in out Unbounded_String; New_Item: String);
   procedure Append(Source: in out Unbounded_String; New_Item: Character);

   function "&"(Left, Right: Unbounded_String)                   return Unbounded_String;
   function "&"(Left: Unbounded_String; Right: String)           return Unbounded_String;
   function "&"(Left: String          ; Right: Unbounded_String) return Unbounded_String;
   function "&"(Left: Unbounded_String; Right: Character)        return Unbounded_String;
   function "&"(Left: Character       ; Right: Unbounded_String) return Unbounded_String;

   function Element(Source: Unbounded_String; Index: Positive) return Character;
   procedure Replace_Element(Source: in out Unbounded_String; Index: Positive; By: Character);
   function Slice(Source: Unbounded_String; Low: Positive; High: Natural) return String;

   procedure Unbounded_Slice(Source: Unbounded_String;
                             Target: out Unbounded_String;
                             Low   : Positive;
                             High  : Natural);
   function Unbounded_Slice(Source: Unbounded_String;
                            Low   : Positive;
                            High  : Natural)
          return Unbounded_String;

   function "="(Left, Right: Unbounded_String)                   return Boolean;
   function "="(Left: Unbounded_String; Right: String)           return Boolean;
   function "="(Left: String          ; Right: Unbounded_String) return Boolean;

   function "<"(Left, Right: Unbounded_String)                   return Boolean;
   function "<"(Left: Unbounded_String; Right: String)           return Boolean;
   function "<"(Left: String          ; Right: Unbounded_String) return Boolean;

   function "<="(Left, Right: Unbounded_String)                   return Boolean;
   function "<="(Left: Unbounded_String; Right: String)           return Boolean;
   function "<="(Left: String          ; Right: Unbounded_String) return Boolean;

   function ">"(Left, Right: Unbounded_String)                   return Boolean;
   function ">"(Left: Unbounded_String; Right: String)           return Boolean;
   function ">"(Left: String          ; Right: Unbounded_String) return Boolean;

   function ">="(Left, Right: Unbounded_String)                   return Boolean;
   function ">="(Left: Unbounded_String; Right: String)           return Boolean;
   function ">="(Left: String          ; Right: Unbounded_String) return Boolean;

   -- Search subprograms
   function Index(Source : Unbounded_String;
                  Pattern: String;
                  From   : Positive;
                  Going  : Direction              := Forward;
                  Mapping: Maps.Character_Mapping := Maps.Identity)
      return Natural;
   function Index(Source : Unbounded_String;
                  Pattern: String;
                  From   : Positive;
                  Going  : Direction := Forward;
                  Mapping: Maps.Character_Mapping_Function)
      return Natural;
   function Index(Source : Unbounded_String;
                  Pattern: String;
                  Going  : Direction              := Forward;
                  Mapping: Maps.Character_Mapping := Maps.Identity)
      return Natural;
   function Index(Source : Unbounded_String;
                  Pattern: String;
                  Going  : Direction := Forward;
                  Mapping: Maps.Character_Mapping_Function)
      return Natural;
   function Index(Source: Unbounded_String;
                  Set   : Maps.Character_Set;
                  From  : Positive;
                  Test  : Membership := Inside;
                  Going : Direction  := Forward)
      return Natural;
   function Index(Source: Unbounded_String;
                  Set   : Maps.Character_Set;
                  Test  : Membership := Inside;
                  Going : Direction  := Forward)
      return Natural;
   function Index_Non_Blank(Source: Unbounded_String;
                            From  : Positive;
                            Going : Direction := Forward)
      return Natural;
   function Index_Non_Blank(Source: Unbounded_String;
                            Going : Direction := Forward)
      return Natural;

   function Count(Source : Unbounded_String;
                  Pattern: String;
                  Mapping: Maps.Character_Mapping := Maps.Identity)
      return Natural;
   function Count(Source : Unbounded_String;
                  Pattern: String;
                  Mapping: Maps.Character_Mapping_Function)
      return Natural;
   function Count(Source: Unbounded_String; Set: Maps.Character_Set) return Natural;

   procedure Find_Token(Source: Unbounded_String;
                        Set   : Maps.Character_Set;
                        From  : Positive;
                        Test  : Membership;
                        First : out Positive;
                        Last  : out Natural);
   procedure Find_Token(Source: Unbounded_String;
                        Set   : Maps.Character_Set;
                        Test  : Membership;
                        First : out Positive;
                        Last  : out Natural);

   -- String translation subprograms
   procedure Translate(Source: in out Unbounded_String; Mapping: Maps.Character_Mapping);
   procedure Translate(Source: in out Unbounded_String; Mapping: Maps.Character_Mapping_Function);
   function Translate(Source : Unbounded_String;
                      Mapping: Maps.Character_Mapping)
      return Unbounded_String;
   function Translate(Source : Unbounded_String;
                      Mapping: Maps.Character_Mapping_Function)
      return Unbounded_String;

   -- String transformation subprograms
   procedure Replace_Slice(Source: in out Unbounded_String;
                           Low   : Positive;
                           High  : Natural;
                           By    : String);
   function Replace_Slice(Source: Unbounded_String;
                          Low   : Positive;
                          High  : Natural;
                          By    : String)
      return Unbounded_String;

   procedure Insert(Source  : in out Unbounded_String;
                    Before  : Positive;
                    New_Item: String);
   function Insert(Source  : Unbounded_String;
                   Before  : Positive;
                   New_Item: String)
      return Unbounded_String;

   procedure Overwrite(Source  : in out Unbounded_String;
                       Position: Positive;
                       New_Item: String);
   function Overwrite(Source  : Unbounded_String;
                      Position: Positive;
                      New_Item: String)
      return Unbounded_String;

   procedure Delete(Source : in out Unbounded_String;
                    From   : Positive;
                    Through: Natural);
   function Delete(Source : Unbounded_String;
                   From   : Positive;
                   Through: Natural)
      return Unbounded_String;

   procedure Trim(Source: in out Unbounded_String; Side: Trim_End);
   function  Trim(Source:        Unbounded_String; Side: Trim_End)
      return Unbounded_String;

   procedure Trim(Source: in out Unbounded_String;
                  Left  : Maps.Character_Set;
                  Right : Maps.Character_Set);
   function Trim(Source: Unbounded_String;
                 Left  : Maps.Character_Set;
                 Right : Maps.Character_Set)
      return Unbounded_String;

   procedure Head(Source: in out Unbounded_String;
                  Count : Natural;
                  Pad   : Character := Space);
   function Head(Source: Unbounded_String;
                 Count : Natural;
                 Pad   : Character := Space)
      return Unbounded_String;

   procedure Tail(Source: in out Unbounded_String;
                  Count : Natural;
                  Pad   : Character := Space);
   function Tail(Source: Unbounded_String;
                 Count : Natural;
                 Pad   : Character := Space)
      return Unbounded_String;

   function "*"(Left: Natural; Right: Character)        return Unbounded_String;
   function "*"(Left: Natural; Right: String)           return Unbounded_String;
   function "*"(Left: Natural; Right: Unbounded_String) return Unbounded_String;
end Ada.Strings.Unbounded;

String Hashing

StringFixed StringBounded StringUnbounded String

with Ada.Containers;

function Ada.Strings.Hash(Key: String) return Containers.Hash_Type;
   with Pure;

with Ada.Containers, Ada.Strings.Hash;

function Ada.Strings.Fixed.Hash(Key: String) return Containers.Hash_Type
   renames Ada.Strings.Hash;

with Ada.Containers;

generic
   with package Bounded is new Ada.Strings.Bounded.Generic_Bounded_Length(<>);
function Ada.Strings.Bounded.Hash(Key: Bounded.Bounded_String) return Containers.Hash_Type;
   with Preelaborate, Nonblocking, Global => in out synchronized;

with Ada.Containers;

function Ada.Strings.Unbounded.Hash(Key: Unbounded_String) return Containers.Hash_Type;
   with Preelaborate, Nonblocking, Global => in out synchronized;

Case-Sensitive StringCase-Insensitive, Fixed StringCase-Insensitive, Bounded StringCase-Insensitive, Unbounded String

with Ada.Containers;

function Ada.Strings.Hash_Case_Insensitive(Key: String) return Containers.Hash_Type;
   with Pure;

with Ada.Containers, Ada.Strings.Hash_Case_Insensitive;

function Ada.Strings.Fixed.Hash_Case_Insensitive(Key: String) return Containers.Hash_Type
   renames Ada.Strings.Hash_Case_Insensitive;

with Ada.Containers;

generic
   with package Bounded is new Ada.Strings.Bounded.Generic_Bounded_Length(<>);
function Ada.Strings.Bounded.Hash_Case_Insensitive(Key: Bounded.Bounded_String) return Containers.Hash_Type;
   with Preelaborate, Nonblocking, Global => in out synchronized;

with Ada.Containers;

function Ada.Strings.Unbounded.Hash_Case_Insensitive(Key: Unbounded_String) return Containers.Hash_Type;
   with Preelaborate, Nonblocking, Global => in out synchronized;

String Comparison

Case-insensitive string equality

StringsFixed StringsBounded StringsUnbounded Strings

function Ada.Strings.Equal_Case_Insensitive(Left, Right: String) return Boolean with;
   Pure;

with Ada.Strings.Equal_Case_Insensitive;

function Ada.Strings.Fixed.Equal_Case_Insensitive(Left, Right: String) return Boolean
   renames Ada.Strings.Equal_Case_Insensitive;

generic
   with package Bounded is new Ada.Strings.Bounded.Generic_Bounded_Length(<>);
function Ada.Strings.Bounded.Equal_Case_Insensitive(Left, Right: Bounded.Bounded_String) return Boolean;
   with Preelaborate, Nonblocking, Global => in out synchronized;

function Ada.Strings.Unbounded.Equal_Case_Insensitive(Left, Right: Unbounded_String) return Boolean;
   with Preelaborate, Nonblocking, Global => in out synchronized;

Case-insensitive, lexicographic string comparison:

StringsFixed StringsBounded StringsUnbounded Strings

function Ada.Strings.Less_Case_Insensitive(Left, Right: String) return Boolean with;
   Pure;

with Ada.Strings.Less_Case_Insensitive;

function Ada.Strings.Fixed.Less_Case_Insensitive(Left, Right: String) return Boolean
   renames Ada.Strings.Less_Case_Insensitive;

generic
   with package Bounded is new Ada.Strings.Bounded.Generic_Bounded_Length(<>);
function Ada.Strings.Bounded.Less_Case_Insensitive(Left, Right: Bounded.Bounded_String) return Boolean;
   with Preelaborate, Nonblocking, Global => in out synchronized;

function Ada.Strings.Unbounded.Less_Case_Insensitive(Left, Right: Unbounded_String) return Boolean;
   with Preelaborate, Nonblocking, Global => in out synchronized;

String Encoding

Facilities for encoding, decoding, and converting strings in various character encoding schemes are provided by packages Strings.UTF_Encoding, Strings.UTF_Encoding.Conversions, Strings.UTF_Encoding.Strings, Strings.UTF_Encoding.Wide_Strings, and Strings.UTF_Encoding.Wide_Wide_Strings.

package Ada.Strings.UTF_Encoding
   with Pure is

   -- Declarations common to the string encoding packages
   type Encoding_Scheme is (UTF_8, UTF_16BE, UTF_16LE);

   subtype UTF_String         is String;
   subtype UTF_8_String       is String;
   subtype UTF_16_Wide_String is Wide_String;

   Encoding_Error: exception;

   BOM_8: constant UTF_8_String := Character'Val(16#EF#) &
                                   Character'Val(16#BB#) &
                                   Character'Val(16#BF#);
   BOM_16BE: constant UTF_String := Character'Val(16#FE#) &
                                    Character'Val(16#FF#);
   BOM_16LE: constant UTF_String := Character'Val(16#FF#) &
                                    Character'Val(16#FE#);
   BOM_16: constant UTF_16_Wide_String := (1 => Wide_Character'Val(16#FEFF#));

   function Encoding(Item: UTF_String; Default: Encoding_Scheme := UTF_8) return Encoding_Scheme;
end Ada.Strings.UTF_Encoding;

Conversions

package Ada.Strings.UTF_Encoding.Conversions
   with Pure is

   -- Conversions between various encoding schemes
   function Convert(Item         : UTF_String;
                    Input_Scheme : Encoding_Scheme;
                    Output_Scheme: Encoding_Scheme;
                    Output_BOM   : Boolean := False)
      return UTF_String;
   function Convert(Item        : UTF_String;
                    Input_Scheme: Encoding_Scheme;
                    Output_BOM  : Boolean := False)
      return UTF_16_Wide_String;
   function Convert(Item      : UTF_8_String;
                    Output_BOM: Boolean := False)
      return UTF_16_Wide_String;
   function Convert(Item         : UTF_16_Wide_String;
                    Output_Scheme: Encoding_Scheme;
                    Output_BOM   : Boolean := False)
      return UTF_String;
   function Convert(Item      : UTF_16_Wide_String;
                    Output_BOM: Boolean := False)
      return UTF_8_String;
end Ada.Strings.UTF_Encoding.Conversions;

Strings

package Ada.Strings.UTF_Encoding.Strings
   with Pure is

   -- Encoding / decoding between String and various encoding schemes
   function Encode(Item         : String;
                   Output_Scheme: Encoding_Scheme;
                   Output_BOM   : Boolean := False)
      return UTF_String;
   function Encode(Item      : String;
                   Output_BOM: Boolean := False)
      return UTF_8_String;
   function Encode(Item     : String;
                  Output_BOM: Boolean := False)
      return UTF_16_Wide_String;
   function Decode(Item        : UTF_String;
                   Input_Scheme: Encoding_Scheme)
      return String;
   function Decode(Item: UTF_8_String)       return String;
   function Decode(Item: UTF_16_Wide_String) return String;
end Ada.Strings.UTF_Encoding.Strings;

Wide Strings

package Ada.Strings.UTF_Encoding.Wide_Strings
   with Pure is

   -- Encoding / decoding between Wide_String and various encoding schemes
   function Encode(Item         : Wide_String;
                   Output_Scheme: Encoding_Scheme;
                   Output_BOM   : Boolean := False)
      return UTF_String;
   function Encode(Item      : Wide_String;
                   Output_BOM: Boolean := False)
      return UTF_8_String;
   function Encode(Item      : Wide_String;
                   Output_BOM: Boolean := False)
      return UTF_16_Wide_String;
   function Decode(Item        : UTF_String;
                   Input_Scheme: Encoding_Scheme)
      return Wide_String;
   function Decode(Item: UTF_8_String)       return Wide_String;
   function Decode(Item: UTF_16_Wide_String) return Wide_String;
end Ada.Strings.UTF_Encoding.Wide_Strings;

Wide Wide Strings

package Ada.Strings.UTF_Encoding.Wide_Wide_Strings
   with Pure is

   -- Encoding / decoding between Wide_Wide_String and various encoding schemes
   function Encode(Item         : Wide_Wide_String;
                   Output_Scheme: Encoding_Scheme;
                   Output_BOM   : Boolean := False)
      return UTF_String;
   function Encode(Item      : Wide_Wide_String;
                   Output_BOM: Boolean := False)
      return UTF_8_String;
   function Encode(Item      : Wide_Wide_String;
                   Output_BOM: Boolean := False)
      return UTF_16_Wide_String;
   function Decode(Item        : UTF_String;
                   Input_Scheme: Encoding_Scheme)
      return Wide_Wide_String;
   function Decode(Item: UTF_8_String)       return Wide_Wide_String;
   function Decode(Item: UTF_16_Wide_String) return Wide_Wide_String;
end Ada.Strings.UTF_Encoding.Wide_Wide_Strings;

Universal Text Buffers

A universal text buffer can be used to save and retrieve text of any language-defined string type. The types used to save and retrieve the text can be different.

with Ada.Strings.UTF_Encoding.Wide_Wide_Strings;

package Ada.Strings.Text_Buffers
   with Pure is

   type Text_Buffer_Count is range 0 .. <implementation-defined>;

   New_Line_Count: constant Text_Buffer_Count := <implementation-defined>;

   type Root_Buffer_Type is abstract tagged private
      with Default_Initial_Condition => Current_Indent(Root_Buffer_Type) = 0;

   procedure           Put(Buffer: in out Root_Buffer_Type; Item:           String) is abstract;
   procedure      Wide_Put(Buffer: in out Root_Buffer_Type; Item:      Wide_String) is abstract;
   procedure Wide_Wide_Put(Buffer: in out Root_Buffer_Type; Item: Wide_Wide_String) is abstract;

   procedure      Put_UTF_8 (Buffer: in out Root_Buffer_Type; Item: UTF_Encoding.UTF_8_String)       is abstract;
   procedure Wide_Put_UTF_16(Buffer: in out Root_Buffer_Type; Item: UTF_Encoding.UTF_16_Wide_String) is abstract;

   procedure New_Line(Buffer: in out Root_Buffer_Type) is abstract;

   Standard_Indent: constant Text_Buffer_Count := 3;

   function Current_Indent(Buffer: Root_Buffer_Type) return Text_Buffer_Count;

   procedure Increase_Indent(Buffer: in out Root_Buffer_Type;
                             Amount: Text_Buffer_Count := Standard_Indent)
      with Post'Class => Current_Indent(Buffer) = Current_Indent(Buffer)'Old + Amount;
   procedure Decrease_Indent(Buffer: in out Root_Buffer_Type;
                             Amount: Text_Buffer_Count := Standard_Indent)
      with Pre'Class  => Current_Indent(Buffer) >= Amount or else raise Constraint_Error,
           Post'Class => Current_Indent(Buffer) = Current_Indent(Buffer)'Old - Amount;
end Ada.Strings.Text_Buffers;

Unbounded-String Text Buffers

package Ada.Strings.Text_Buffers.Unbounded
   with Preelaborate, Nonblocking, Global => null is

   type Buffer_Type is new Root_Buffer_Type with private;

   function Get(Buffer: in out Buffer_Type) return String
      with Post'Class => Get'Result'First = 1 and then Current_Indent(Buffer) = 0;
   function Wide_Get(Buffer: in out Buffer_Type) return Wide_String
      with Post'Class => Wide_Get'Result'First = 1 and then Current_Indent(Buffer) = 0;
   function Wide_Wide_Get(Buffer: in out Buffer_Type) return Wide_Wide_String
      with Post'Class => Wide_Wide_Get'Result'First = 1 and then Current_Indent(Buffer) = 0;

   function Get_UTF_8(Buffer: in out Buffer_Type) return UTF_Encoding.UTF_8_String
      with Post'Class => Get_UTF_8'Result'First = 1 and then Current_Indent(Buffer) = 0;
   function Wide_Get_UTF_16(Buffer: in out Buffer_Type) return UTF_Encoding.UTF_16_Wide_String
      with Post'Class => Wide_Get_UTF_16'Result'First = 1 and then Current_Indent(Buffer) = 0;
end Ada.Strings.Text_Buffers.Unbounded;

Bounded-String Text Buffers

package Ada.Strings.Text_Buffers.Bounded
   with Pure, Nonblocking, Global => null is

   type Buffer_Type(Max_Characters: Text_Buffer_Count) is new Root_Buffer_Type with private
      with Default_Initial_Condition => not Text_Truncated(Buffer_Type);

   function Text_Truncated(Buffer: Buffer_Type) return Boolean;

   -- Get, Wide_Get, Wide_Wide_Get, Get_UTF_8, and Wide_Get_UTF_16
   -- are declared here just as in the Unbounded child.
end Ada.Strings.Text_Buffers.Bounded;