8 Space : constant Character := ' '; -- Character'Val(32) Exclamation : constant Character := '!'; -- Character'Val(33) Quotation : constant Character := '"'; -- Character'Val(34) Number_Sign : constant Character := '#'; -- Character'Val(35) Dollar_Sign : constant Character := '$'; -- Character'Val(36) Percent_Sign : constant Character := '%'; -- Character'Val(37) Ampersand : constant Character := '&'; -- Character'Val(38) Apostrophe : constant Character := '''; -- Character'Val(39) Left_Parenthesis : constant Character := '('; -- Character'Val(40) Right_Parenthesis : constant Character := ')'; -- Character'Val(41) Asterisk : constant Character := '*'; -- Character'Val(42) Plus_Sign : constant Character := '+'; -- Character'Val(43) Comma : constant Character := ','; -- Character'Val(44) Hyphen : constant Character := '-'; -- Character'Val(45) Minus_Sign : Character renames Hyphen; Full_Stop : constant Character := '.'; -- Character'Val(46) Solidus : constant Character := '/'; -- Character'Val(47) 9 -- Decimal digits '0' though '9' are at positions 48 through 57 10 Colon : constant Character := ':'; -- Character'Val(58) Semicolon : constant Character := ';'; -- Character'Val(59) Less_Than_Sign : constant Character := '<'; -- Character'Val(60) Equals_Sign : constant Character := '='; -- Character'Val(61) Greater_Than_Sign : constant Character := '>'; -- Character'Val(62) Question : constant Character := '?'; -- Character'Val(63) Commercial_At : constant Character := '@'; -- Character'Val(64) 11 -- Letters 'A' through 'Z' are at positions 65 through 90 12 Left_Square_Bracket : constant Character := '['; -- Character'Val(91) Reverse_Solidus : constant Character := '\'; -- Character'Val(92) Right_Square_Bracket : constant Character := ']'; -- Character'Val(93) Circumflex : constant Character := '^'; -- Character'Val(94) Low_Line : constant Character := '_'; -- Character'Val(95) 13 Grave : constant Character := '`'; -- Character'Val(96) LC_A : constant Character := 'a'; -- Character'Val(97) LC_B : constant Character := 'b'; -- Character'Val(98) LC_C : constant Character := 'c'; -- Character'Val(99) LC_D : constant Character := 'd'; -- Character'Val(100) LC_E : constant Character := 'e'; -- Character'Val(101) LC_F : constant Character := 'f'; -- Character'Val(102) LC_G : constant Character := 'g'; -- Character'Val(103) LC_H : constant Character := 'h'; -- Character'Val(104) LC_I : constant Character := 'i'; -- Character'Val(105) LC_J : constant Character := 'j'; -- Character'Val(106) LC_K : constant Character := 'k'; -- Character'Val(107) LC_L : constant Character := 'l'; -- Character'Val(108) LC_M : constant Character := 'm'; -- Character'Val(109) LC_N : constant Character := 'n'; -- Character'Val(110) LC_O : constant Character := 'o'; -- Character'Val(111) 14 LC_P : constant Character := 'p'; -- Character'Val(112) LC_Q : constant Character := 'q'; -- Character'Val(113) LC_R : constant Character := 'r'; -- Character'Val(114) LC_S : constant Character := 's'; -- Character'Val(115) LC_T : constant Character := 't'; -- Character'Val(116) LC_U : constant Character := 'u'; -- Character'Val(117) LC_V : constant Character := 'v'; -- Character'Val(118) LC_W : constant Character := 'w'; -- Character'Val(119) LC_X : constant Character := 'x'; -- Character'Val(120) LC_Y : constant Character := 'y'; -- Character'Val(121) LC_Z : constant Character := 'z'; -- Character'Val(122) Left_Curly_Bracket : constant Character := '{'; -- Character'Val(123) Vertical_Line : constant Character := '|'; -- Character'Val(124) Right_Curly_Bracket : constant Character := '}'; -- Character'Val(125) Tilde : constant Character := '~'; -- Character'Val(126) DEL : constant Character := Character'Val(127); 15 -- ISO 6429 control characters: 16 IS4 : Character renames FS; IS3 : Character renames GS; IS2 : Character renames RS; IS1 : Character renames US; 17 Reserved_128 : constant Character := Character'Val(128); Reserved_129 : constant Character := Character'Val(129); BPH : constant Character := Character'Val(130); NBH : constant Character := Character'Val(131); Reserved_132 : constant Character := Character'Val(132); NEL : constant Character := Character'Val(133); SSA : constant Character := Character'Val(134); ESA : constant Character := Character'Val(135); HTS : constant Character := Character'Val(136); HTJ : constant Character := Character'Val(137); VTS : constant Character := Character'Val(138); PLD : constant Character := Character'Val(139); PLU : constant Character := Character'Val(140); RI : constant Character := Character'Val(141); SS2 : constant Character := Character'Val(142); SS3 : constant Character := Character'Val(143); 18 DCS : constant Character := Character'Val(144); PU1 : constant Character := Character'Val(145); PU2 : constant Character := Character'Val(146); STS : constant Character := Character'Val(147); CCH : constant Character := Character'Val(148); MW : constant Character := Character'Val(149); SPA : constant Character := Character'Val(150); EPA : constant Character := Character'Val(151); 19 SOS : constant Character := Character'Val(152); Reserved_153 : constant Character := Character'Val(153); SCI : constant Character := Character'Val(154); CSI : constant Character := Character'Val(155); ST : constant Character := Character'Val(156); OSC : constant Character := Character'Val(157); PM : constant Character := Character'Val(158); APC : constant Character := Character'Val(159); 20 -- Other graphic characters: 21 -- Character positions 160 (16#A0#) .. 175 (16#AF#): No_Break_Space : constant Character := ' '; --Character'V\ al(160) NBSP : Character renames No_Break_Space; Inverted_Exclamation : constant Character := Character'Val(161); Cent_Sign : constant Character := Character'Val(162); Pound_Sign : constant Character := Character'Val(163); Currency_Sign : constant Character := Character'Val(164); Yen_Sign : constant Character := Character'Val(165); Broken_Bar : constant Character := Character'Val(166); Section_Sign : constant Character := Character'Val(167); Diaeresis : constant Character := Character'Val(168); Copyright_Sign : constant Character := Character'Val(169); Feminine_Ordinal_Indicator : constant Character := Character'Val(170); Left_Angle_Quotation : constant Character := Character'Val(171); Not_Sign : constant Character := Character'Val(172); Soft_Hyphen : constant Character := Character'Val(173); Registered_Trade_Mark_Sign : constant Character := Character'Val(174); Macron : constant Character := Character'Val(175); 22 -- Character positions 176 (16#B0#) .. 191 (16#BF#): Degree_Sign : constant Character := Character'Val(176); Ring_Above : Character renames Degree_Sign; Plus_Minus_Sign : constant Character := Character'Val(177); Superscript_Two : constant Character := Character'Val(178); Superscript_Three : constant Character := Character'Val(179); Acute : constant Character := Character'Val(180); Micro_Sign : constant Character := Character'Val(181); Pilcrow_Sign : constant Character := Character'Val(182); Paragraph_Sign : Character renames Pilcrow_Sign; Middle_Dot : constant Character := Character'Val(183); Cedilla : constant Character := Character'Val(184); Superscript_One : constant Character := Character'Val(185); Masculine_Ordinal_Indicator : constant Character := Character'Val(186); Right_Angle_Quotation : constant Character := Character'Val(187); Fraction_One_Quarter : constant Character := Character'Val(188); Fraction_One_Half : constant Character := Character'Val(189); Fraction_Three_Quarters : constant Character := Character'Val(190); Inverted_Question : constant Character := Character'Val(191); 23 -- Character positions 192 (16#C0#) .. 207 (16#CF#): UC_A_Grave : constant Character := Character'Val(192); UC_A_Acute : constant Character := Character'Val(193); UC_A_Circumflex : constant Character := Character'Val(194); UC_A_Tilde : constant Character := Character'Val(195); UC_A_Diaeresis : constant Character := Character'Val(196); UC_A_Ring : constant Character := Character'Val(197); UC_AE_Diphthong : constant Character := Character'Val(198); UC_C_Cedilla : constant Character := Character'Val(199); UC_E_Grave : constant Character := Character'Val(200); UC_E_Acute : constant Character := Character'Val(201); UC_E_Circumflex : constant Character := Character'Val(202); UC_E_Diaeresis : constant Character := Character'Val(203); UC_I_Grave : constant Character := Character'Val(204); UC_I_Acute : constant Character := Character'Val(205); UC_I_Circumflex : constant Character := Character'Val(206); UC_I_Diaeresis : constant Character := Character'Val(207); 24 -- Character positions 208 (16#D0#) .. 223 (16#DF#): UC_Icelandic_Eth : constant Character := Character'Val(208); UC_N_Tilde : constant Character := Character'Val(209); UC_O_Grave : constant Character := Character'Val(210); UC_O_Acute : constant Character := Character'Val(211); UC_O_Circumflex : constant Character := Character'Val(212); UC_O_Tilde : constant Character := Character'Val(213); UC_O_Diaeresis : constant Character := Character'Val(214); Multiplication_Sign : constant Character := Character'Val(215); UC_O_Oblique_Stroke : constant Character := Character'Val(216); UC_U_Grave : constant Character := Character'Val(217); UC_U_Acute : constant Character := Character'Val(218); UC_U_Circumflex : constant Character := Character'Val(219); UC_U_Diaeresis : constant Character := Character'Val(220); UC_Y_Acute : constant Character := Character'Val(221); UC_Icelandic_Thorn : constant Character := Character'Val(222); LC_German_Sharp_S : constant Character := Character'Val(223); 25 -- Character positions 224 (16#E0#) .. 239 (16#EF#): LC_A_Grave : constant Character := Character'Val(224); LC_A_Acute : constant Character := Character'Val(225); LC_A_Circumflex : constant Character := Character'Val(226); LC_A_Tilde : constant Character := Character'Val(227); LC_A_Diaeresis : constant Character := Character'Val(228); LC_A_Ring : constant Character := Character'Val(229); LC_AE_Diphthong : constant Character := Character'Val(230); LC_C_Cedilla : constant Character := Character'Val(231); LC_E_Grave : constant Character := Character'Val(232); LC_E_Acute : constant Character := Character'Val(233); LC_E_Circumflex : constant Character := Character'Val(234); LC_E_Diaeresis : constant Character := Character'Val(235); LC_I_Grave : constant Character := Character'Val(236); LC_I_Acute : constant Character := Character'Val(237); LC_I_Circumflex : constant Character := Character'Val(238); LC_I_Diaeresis : constant Character := Character'Val(239); 26 -- Character positions 240 (16#F0#) .. 255 (16#FF#): LC_Icelandic_Eth : constant Character := Character'Val(240); LC_N_Tilde : constant Character := Character'Val(241); LC_O_Grave : constant Character := Character'Val(242); LC_O_Acute : constant Character := Character'Val(243); LC_O_Circumflex : constant Character := Character'Val(244); LC_O_Tilde : constant Character := Character'Val(245); LC_O_Diaeresis : constant Character := Character'Val(246); Division_Sign : constant Character := Character'Val(247); LC_O_Oblique_Stroke : constant Character := Character'Val(248); LC_U_Grave : constant Character := Character'Val(249); LC_U_Acute : constant Character := Character'Val(250); LC_U_Circumflex : constant Character := Character'Val(251); LC_U_Diaeresis : constant Character := Character'Val(252); LC_Y_Acute : constant Character := Character'Val(253); LC_Icelandic_Thorn : constant Character := Character'Val(254); LC_Y_Diaeresis : constant Character := Character'Val(255); end Ada.Characters.Latin_1; Implementation Permissions 27 An implementation may provide additional packages as children of Ada.Characters, to declare names for the symbols of the local character set or other character sets. A.4 String Handling 1 This clause presents the specifications of the package Strings and several child packages, which provide facilities for dealing with string data. Fixed-length, bounded-length, and unbounded-length strings are supported, for both String and Wide_String. The string-handling subprograms include searches for pattern strings and for characters in program-specified sets, translation (via a character-to-character mapping), and transformation (replacing, inserting, overwriting, and deleting of substrings). A.4.1 The Package Strings 1 The package Strings provides declarations common to the string handling packages. Static Semantics 2 The library package Strings has the following declaration: 3 package Ada.Strings is pragma Pure(Strings); 4 Space : constant Character := ' '; Wide_Space : constant Wide_Character := ' '; 5 Length_Error, Pattern_Error, Index_Error, Translation_Error : exception; 6 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; A.4.2 The Package Strings.Maps 1 The package Strings.Maps defines the types, operations, and other entities needed for character sets and character-to-character mappings. Static Semantics 2 The library package Strings.Maps has the following declaration: 3 package Ada.Strings.Maps is pragma Preelaborate(Maps); 4 -- Representation for a set of character values: type Character_Set is private; 5 Null_Set : constant Character_Set; 6 type Character_Range is record Low : Character; High : Character; end record; -- Represents Character range Low..High 7 type Character_Ranges is array (Positive range <>) of Character_Range; 8 function To_Set (Ranges : in Character_Ranges) return Character_Set; 9 function To_Set (Span : in Character_Range) return Character_Set; 10 function To_Ranges (Set : in Character_Set) return Character_Range\ s; 11 function "=" (Left, Right : in Character_Set) return Boolean; 12 function "not" (Right : in Character_Set) return Character_Set; function "and" (Left, Right : in Character_Set) return Character_Set; function "or" (Left, Right : in Character_Set) return Character_Set; function "xor" (Left, Right : in Character_Set) return Character_Set; function "-" (Left, Right : in Character_Set) return Character_Set; 13 function Is_In (Element : in Character; Set : in Character_Set) return Boolean; 14 function Is_Subset (Elements : in Character_Set; Set : in Character_Set) return Boolean; 15 function "<=" (Left : in Character_Set; Right : in Character_Set) return Boolean renames Is_Subset; 16 -- Alternative representation for a set of character values: subtype Character_Sequence is String; 17 function To_Set (Sequence : in Character_Sequence) return Character_Set; 18 function To_Set (Singleton : in Character) return Character_Set; 19 function To_Sequence (Set : in Character_Set) return Character_Seq\ uence; 20 -- Representation for a character to character mapping: type Character_Mapping is private; 21 function Value (Map : in Character_Mapping; Element : in Character) return Character; 22 Identity : constant Character_Mapping; 23 function To_Mapping (From, To : in Character_Sequence) return Character_\ Mapping; 24 function To_Domain (Map : in Character_Mapping) return Character_Sequenc\ e; function To_Range (Map : in Character_Mapping) return Character_Sequenc\ e; 25 type Character_Mapping_Function is access function (From : in Character) return Character; 26 private ... -- not specified by the language end Ada.Strings.Maps; 27 An object of type Character_Set represents a set of characters. 28 Null_Set represents the set containing no characters. 29 An object Obj of type Character_Range represents the set of characters in the range Obj.Low .. Obj.High. 30 An object Obj of type Character_Ranges represents the union of the sets corresponding to Obj(I) for I in Obj'Range. 31 function To_Set (Ranges : in Character_Ranges) return Character_Set; 32 If Ranges'Length=0 then Null_Set is returned; otherwise the returned value represents the set corresponding to Ranges. 33 function To_Set (Span : in Character_Range) return Character_Set; 34 The returned value represents the set containing each character in Span. 35 function To_Ranges (Set : in Character_Set) return Character_Ranges; 36 If Set = Null_Set then an empty Character_Ranges array is returned; otherwise the shortest array of contiguous ranges of Character values in Set, in increasing order of Low, is returned. 37 function "=" (Left, Right : in Character_Set) return Boolean; 38 The function "=" returns True if Left and Right represent identical sets, and False otherwise. 39 Each of the logical operators "not", "and", "or", and "xor" returns a Character_Set value that represents the set obtained by applying the corresponding operation to the set(s) represented by the parameter(s) of the operator. "-"(Left, Right) is equivalent to "and"(Left, "not"(Right)). 40 function Is_In (Element : in Character; Set : in Character_Set); return Boolean; 41 Is_In returns True if Element is in Set, and False otherwise. 42 function Is_Subset (Elements : in Character_Set; Set : in Character_Set) return Boolean; 43 Is_Subset returns True if Elements is a subset of Set, and False otherwise. 44 subtype Character_Sequence is String; 45 The Character_Sequence subtype is used to portray a set of character values and also to identify the domain and range of a character mapping. 46 function To_Set (Sequence : in Character_Sequence) return Character_Set; function To_Set (Singleton : in Character) return Character_Set; 47 Sequence portrays the set of character values that it explicitly contains (ignoring duplicates). Singleton portrays the set comprising a single Character. Each of the To_Set functions returns a Character_Set value that represents the set portrayed by Sequence or Singleton. 48 function To_Sequence (Set : in Character_Set) return Character_Sequence; 49 The function To_Sequence returns a Character_Sequence value containing each of the characters in the set represented by Set, in ascending order with no duplicates. 50 type Character_Mapping is private; 51 An object of type Character_Mapping represents a Character-to- Character mapping. 52 function Value (Map : in Character_Mapping; Element : in Character) return Character; 53 The function Value returns the Character value to which Element maps with respect to the mapping represented by Map. 54 A character C matches a pattern character P with respect to a given Character_Mapping value Map if Value(Map, C) = P. A string S matches a pattern string P with respect to a given Character_Mapping if their lengths are the same and if each character in S matches its corresponding character in the pattern string P. 55 String handling subprograms that deal with character mappings have parameters whose type is Character_Mapping. 56 Identity : constant Character_Mapping; 57 Identity maps each Character to itself. 58 function To_Mapping (From, To : in Character_Sequence) return Character_Map\ ping; 59 To_Mapping produces a Character_Mapping such that each element of From maps to the corresponding element of To, and each other character maps to itself. If From'Length /= To'Length, or if some character is repeated in From, then Translation_Error is propagated. 60 function To_Domain (Map : in Character_Mapping) return Character_Sequence; 61 To_Domain returns the shortest Character_Sequence value D such that each character not in D maps to itself, and such that the characters in D are in ascending order. The lower bound of D is 1. 62 function To_Range (Map : in Character_Mapping) return Character_Sequence; 63 To_Range returns the Character_Sequence value R, with lower bound 1 and upper bound Map'Length, such that if D = To_Domain(Map) then D(I) maps to R(I) for each I in D'Range. 64 An object F of type Character_Mapping_Function maps a Character value C to the Character value F.all(C), which is said to match C with respect to mapping function F. NOTES 65 (7) Character_Mapping and Character_Mapping_Function are used both for character equivalence mappings in the search subprograms (such as for case insensitivity) and as transformational mappings in the Translate subprograms. 66 (8) To_Domain(Identity) and To_Range(Identity) each returns the null string. Examples 67 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. A.4.3 Fixed-Length String Handling 1 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. 2 For each function that returns a String, the lower bound of the returned value is 1. 3 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. Static Semantics 4 The library package Strings.Fixed has the following declaration: 5 with Ada.Strings.Maps; package Ada.Strings.Fixed is pragma Preelaborate(Fixed); 6 -- "Copy" procedure for strings of possibly different lengths 7 procedure Move (Source : in String; Target : out String; Drop : in Truncation := Error; Justify : in Alignment := Left; Pad : in Character := Space); 8 -- Search subprograms 9 function Index (Source : in String; Pattern : in String; Going : in Direction := Forward; Mapping : in Maps.Character_Mapping := Maps.Identity) return Natural; 10 function Index (Source : in String; Pattern : in String; Going : in Direction := Forward; Mapping : in Maps.Character_Mapping_Function) return Natural; 11 function Index (Source : in String; Set : in Maps.Character_Set; Test : in Membership := Inside; Going : in Direction := Forward) return Natural; 12 function Index_Non_Blank (Source : in String; Going : in Direction := Forward) return Natural; 13 function Count (Source : in String; Pattern : in String; Mapping : in Maps.Character_Mapping := Maps.Identity) return Natural; 14 function Count (Source : in String; Pattern : in String; Mapping : in Maps.Character_Mapping_Function) return Natural; 15 function Count (Source : in String; Set : in Maps.Character_Set) return Natural; 16 procedure Find_Token (Source : in String; Set : in Maps.Character_Set; Test : in Membership; First : out Positive; Last : out Natural); 17 -- String translation subprograms 18 function Translate (Source : in String; Mapping : in Maps.Character_Mapping) return String; 19 procedure Translate (Source : in out String; Mapping : in Maps.Character_Mapping); 20 function Translate (Source : in String; Mapping : in Maps.Character_Mapping_Function) return String; 21 procedure Translate (Source : in out String; Mapping : in Maps.Character_Mapping_Function); 22 -- String transformation subprograms 23 function Replace_Slice (Source : in String; Low : in Positive; High : in Natural; By : in String) return String; 24 procedure Replace_Slice (Source : in out String; Low : in Positive; High : in Natural; By : in String; Drop : in Truncation := Error; Justify : in Alignment := Left; Pad : in Character := Space); 25 function Insert (Source : in String; Before : in Positive; New_Item : in String) return String; 26 procedure Insert (Source : in out String; Before : in Positive; New_Item : in String; Drop : in Truncation := Error); 27 function Overwrite (Source : in String; Position : in Positive; New_Item : in String) return String; 28 procedure Overwrite (Source : in out String; Position : in Positive; New_Item : in String; Drop : in Truncation := Right); 29 function Delete (Source : in String; From : in Positive; Through : in Natural) return String; 30 procedure Delete (Source : in out String; From : in Positive; Through : in Natural; Justify : in Alignment := Left; Pad : in Character := Space); 31 --String selector subprograms function Trim (Source : in String; Side : in Trim_End) return String; 32 procedure Trim (Source : in out String; Side : in Trim_End; Justify : in Alignment := Left; Pad : in Character := Space); 33 function Trim (Source : in String; Left : in Maps.Character_Set; Right : in Maps.Character_Set) return String; 34 procedure Trim (Source : in out String; Left : in Maps.Character_Set; Right : in Maps.Character_Set; Justify : in Alignment := Strings.Left; Pad : in Character := Space); 35 function Head (Source : in String; Count : in Natural; Pad : in Character := Space) return String; 36 procedure Head (Source : in out String; Count : in Natural; Justify : in Alignment := Left; Pad : in Character := Space); 37 function Tail (Source : in String; Count : in Natural; Pad : in Character := Space) return String; 38 procedure Tail (Source : in out String; Count : in Natural; Justify : in Alignment := Left; Pad : in Character := Space); 39 --String constructor functions 40 function "*" (Left : in Natural; Right : in Character) return String; 41 function "*" (Left : in Natural; Right : in String) return String; 42 end Ada.Strings.Fixed; 43 The effects of the above subprograms are as follows. 44 procedure Move (Source : in String; Target : out String; Drop : in Truncation := Error; Justify : in Alignment := Left; Pad : in Character := Space); 45 The Move procedure copies characters from Source to Target. If Source has the same length as Target, then the effect is to assign Source to Target. If Source is shorter than Target then: 46 If Justify=Left, then Source is copied into the first Source'Length characters of Target. 47 If Justify=Right, then Source is copied into the last Source'Length characters of Target. 48 If Justify=Center, then Source is copied into the middle Source'Length characters of Target. In this case, if the difference in length between Target and Source is odd, then the extra Pad character is on the right. 49 Pad is copied to each Target character not otherwise assigned. 50 If Source is longer than Target, then the effect is based on Drop. 51 If Drop=Left, then the rightmost Target'Length characters of Source are copied into Target. 52 If Drop=Right, then the leftmost Target'Length characters of Source are copied into Target. 53 If Drop=Error, then the effect depends on the value of the Justify parameter and also on whether any characters in Source other than Pad would fail to be copied: 54 If Justify=Left, and if each of the rightmost Source'Length-Target'Length characters in Source is Pad, then the leftmost Target'Length characters of Source are copied to Target. 55 If Justify=Right, and if each of the leftmost Source'Length-Target'Length characters in Source is Pad, then the rightmost Target'Length characters of Source are copied to Target. 56 Otherwise, Length_Error is propagated. 57 function Index (Source : in String; Pattern : in String; Going : in Direction := Forward; Mapping : in Maps.Character_Mapping := Maps.Identity) return Natural; function Index (Source : in String; Pattern : in String; Going : in Direction := Forward; Mapping : in Maps.Character_Mapping_Function) return Natural; 58 Each Index function searches for a slice of Source, with length Pattern'Length, that matches Pattern with respect to Mapping; the parameter Going indicates the direction of the lookup. If Going = Forward, then Index returns the smallest index I such that the slice of Source starting at I matches Pattern. If Going = Backward, then Index returns the largest index I such that the slice of Source starting at I matches Pattern. If there is no such slice, then 0 is returned. If Pattern is the null string then Pattern_Error is propagated. 59 function Index (Source : in String; Set : in Maps.Character_Set; Test : in Membership := Inside; Going : in Direction := Forward) return Natural; 60 Index searches for the first or last occurrence of any of a set of characters (when Test=Inside), or any of the complement of a set of characters (when Test=Outside). It returns the smallest index I (if Going=Forward) or the largest index I (if Going=Backward) such that Source(I) satisfies the Test condition with respect to Set; it returns 0 if there is no such Character in Source. 61 function Index_Non_Blank (Source : in String; Going : in Direction := Forward) return Natural; 62 Returns Index(Source, Maps.To_Set(Space), Outside, Going) 63 function Count (Source : in String; Pattern : in String; Mapping : in Maps.Character_Mapping := Maps.Identity) return Natural; function Count (Source : in String; Pattern : in String; Mapping : in Maps.Character_Mapping_Function) return Natural; 64 Returns the maximum number of nonoverlapping slices of Source that match Pattern with respect to Mapping. If Pattern is the null string then Pattern_Error is propagated. 65 function Count (Source : in String; Set : in Maps.Character_Set) return Natural; 66 Returns the number of occurrences in Source of characters that are in Set. 67 procedure Find_Token (Source : in String; Set : in Maps.Character_Set; Test : in Membership; First : out Positive; Last : out Natural); 68 Find_Token returns in First and Last the indices of the beginning and end of the first slice of Source all of whose elements satisfy the Test condition, and such that the elements (if any) immediately before and after the slice do not satisfy the Test condition. If no such slice exists, then the value returned for Last is zero, and the value returned for First is Source'First. 69 function Translate (Source : in String; Mapping : in Maps.Character_Mapping) return String; function Translate (Source : in String; Mapping : in Maps.Character_Mapping_Function) return String; 70 Returns the string S whose length is Source'Length and such that S(I) is the character to which Mapping maps the corresponding element of Source, for I in 1..Source'Length. 71 procedure Translate (Source : in out String; Mapping : in Maps.Character_Mapping); procedure Translate (Source : in out String; Mapping : in Maps.Character_Mapping_Function); 72 Equivalent to Source := Translate(Source, Mapping). 73 function Replace_Slice (Source : in String; Low : in Positive; High : in Natural; By : in String) return String; 74 If Low > Source'Last+1, or High < Source'First-1, then Index_ Error is propagated. Otherwise, if High >= Low then the returned string comprises Source(Source'First..Low-1) & By & Source(High+1..Source'Last), and if High < Low then the returned string is Insert(Source, Before=>Low, New_Item=>By). 75 procedure Replace_Slice (Source : in out String; Low : in Positive; High : in Natural; By : in String; Drop : in Truncation := Error; Justify : in Alignment := Left; Pad : in Character := Space); 76 Equivalent to Move(Replace_Slice(Source, Low, High, By), Source, Drop, Justify, Pad). 77 function Insert (Source : in String; Before : in Positive; New_Item : in String) return String; 78 Propagates Index_Error if Before is not in Source'First .. Source'Last+1; otherwise returns Source(Source'First..Before-1) & New_Item & Source(Before..Source'Last), but with lower bound 1. 79 procedure Insert (Source : in out String; Before : in Positive; New_Item : in String; Drop : in Truncation := Error); 80 Equivalent to Move(Insert(Source, Before, New_Item), Source, Drop). 81 function Overwrite (Source : in String; Position : in Positive; New_Item : in String) return String; 82 Propagates Index_Error if Position is not in Source'First .. Source'Last+1; otherwise returns the string obtained from Source by consecutively replacing characters starting at Position with corresponding characters from New_Item. If the end of Source is reached before the characters in New_Item are exhausted, the remaining characters from New_Item are appended to the string. 83 procedure Overwrite (Source : in out String; Position : in Positive; New_Item : in String; Drop : in Truncation := Right); 84 Equivalent to Move(Overwrite(Source, Position, New_Item), Source, Drop). 85 function Delete (Source : in String; From : in Positive; Through : in Natural) return String; 86 If From <= Through, the returned string is Replace_Slice(Source, From, Through, ""), otherwise it is Source. 87 procedure Delete (Source : in out String; From : in Positive; Through : in Natural; Justify : in Alignment := Left; Pad : in Character := Space); 88 Equivalent to Move(Delete(Source, From, Through), Source, Justify => Justify, Pad => Pad). 89 function Trim (Source : in String; Side : in Trim_End) return String; 90 Returns the string obtained by removing from Source all leading Space characters (if Side = Left), all trailing Space characters (if Side = Right), or all leading and trailing Space characters (if Side = Both). 91 procedure Trim (Source : in out String; Side : in Trim_End; Justify : in Alignment := Left; Pad : in Character := Space); 92 Equivalent to Move(Trim(Source, Side), Source, Justify=>Justify, Pad=>Pad). 93 function Trim (Source : in String; Left : in Maps.Character_Set; Right : in Maps.Character_Set) return String; 94 Returns the string obtained by removing from Source all leading characters in Left and all trailing characters in Right. 95 procedure Trim (Source : in out String; Left : in Maps.Character_Set; Right : in Maps.Character_Set; Justify : in Alignment := Strings.Left; Pad : in Character := Space); 96 Equivalent to Move(Trim(Source, Left, Right), Source, Justify => Justify, Pad=>Pad). 97 function Head (Source : in String; Count : in Natural; Pad : in Character := Space) return String; 98 Returns a string of length Count. If Count <= Source'Length, the string comprises the first Count characters of Source. Otherwise its contents are Source concatenated with Count-Source'Length Pad characters. 99 procedure Head (Source : in out String; Count : in Natural; Justify : in Alignment := Left; Pad : in Character := Space); 100 Equivalent to Move(Head(Source, Count, Pad), Source, Drop=>Error, Justify=>Justify, Pad=>Pad). 101 function Tail (Source : in String; Count : in Natural; Pad : in Character := Space) return String; 102 Returns a string of length Count. If Count <= Source'Length, the string comprises the last Count characters of Source. Otherwise its contents are Count-Source'Length Pad characters concatenated with Source. 103 procedure Tail (Source : in out String; Count : in Natural; Justify : in Alignment := Left; Pad : in Character := Space); 104 Equivalent to Move(Tail(Source, Count, Pad), Source, Drop=>Error, Justify=>Justify, Pad=>Pad). 105 function "*" (Left : in Natural; Right : in Character) return String; function "*" (Left : in Natural; Right : in String) return String; 106 These functions replicate a character or string a specified number of times. The first function returns a string whose length is Left and each of whose elements is Right. The second function returns a string whose length is Left*Right'Length and whose value is the null string if Left = 0 and is (Left-1)*Right & Right otherwise. NOTES 107 (9) In the Index and Count functions taking Pattern and Mapping parameters, the actual String parameter passed to Pattern should comprise characters occurring as target characters of the mapping. Otherwise the pattern will not match. 108 (10) In the Insert subprograms, inserting at the end of a string is obtained by passing Source'Last+1 as the Before parameter. 109 (11) If a null Character_Mapping_Function is passed to any of the string handling subprograms, Constraint_Error is propagated. A.4.4 Bounded-Length String Handling 1 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 needed to reflect the variability in length. Additionally, since the Bounded_String type is private, appropriate constructor and selector operations are provided. Static Semantics 2 The library package Strings.Bounded has the following declaration: 3 with Ada.Strings.Maps; package Ada.Strings.Bounded is pragma Preelaborate(Bounded); 4 generic Max : Positive; -- Maximum length of a Bounded_String package Generic_Bounded_Length is 5 Max_Length : constant Positive := Max; 6 type Bounded_String is private; 7 Null_Bounded_String : constant Bounded_String; 8 subtype Length_Range is Natural range 0 .. Max_Length; 9 function Length (Source : in Bounded_String) return Length_Range; 10 -- Conversion, Concatenation, and Selection functions 11 function To_Bounded_String (Source : in String; Drop : in Truncation := Error) return Bounded_String; 12 function To_String (Source : in Bounded_String) return String; 13 function Append (Left, Right : in Bounded_String; Drop : in Truncation := Error) return Bounded_String; 14 function Append (Left : in Bounded_String; Right : in String; Drop : in Truncation := Error) return Bounded_String; 15 function Append (Left : in String; Right : in Bounded_String; Drop : in Truncation := Error) return Bounded_String; 16 function Append (Left : in Bounded_String; Right : in Character; Drop : in Truncation := Error) return Bounded_String; 17 function Append (Left : in Character; Right : in Bounded_String; Drop : in Truncation := Error) return Bounded_String; 18 procedure Append (Source : in out Bounded_String; New_Item : in Bounded_String; Drop : in Truncation := Error); 19 procedure Append (Source : in out Bounded_String; New_Item : in String; Drop : in Truncation := Error); 20 procedure Append (Source : in out Bounded_String; New_Item : in Character; Drop : in Truncation := Error); 21 function "&" (Left, Right : in Bounded_String) return Bounded_String; 22 function "&" (Left : in Bounded_String; Right : in String) return Bounded_String; 23 function "&" (Left : in String; Right : in Bounded_String) return Bounded_String; 24 function "&" (Left : in Bounded_String; Right : in Character) return Bounded_String; 25 function "&" (Left : in Character; Right : in Bounded_String) return Bounded_String; 26 function Element (Source : in Bounded_String; Index : in Positive) return Character; 27 procedure Replace_Element (Source : in out Bounded_String; Index : in Positive; By : in Character); 28 function Slice (Source : in Bounded_String; Low : in Positive; High : in Natural) return String; 29 function "=" (Left, Right : in Bounded_String) return Boolean; function "=" (Left : in Bounded_String; Right : in String) return Boolean; 30 function "=" (Left : in String; Right : in Bounded_String) return Boolean; 31 function "<" (Left, Right : in Bounded_String) return Boolean; 32 function "<" (Left : in Bounded_String; Right : in String) return Boolean; 33 function "<" (Left : in String; Right : in Bounded_String) return Boolean; 34 function "<=" (Left, Right : in Bounded_String) return Boolean; 35 function "<=" (Left : in Bounded_String; Right : in String) return Boolean; 36 function "<=" (Left : in String; Right : in Bounded_String) return Boolean; 37 function ">" (Left, Right : in Bounded_String) return Boolean; 38 function ">" (Left : in Bounded_String; Right : in String) return Boolean; 39 function ">" (Left : in String; Right : in Bounded_String) return Boolean; 40 function ">=" (Left, Right : in Bounded_String) return Boolean; 41 function ">=" (Left : in Bounded_String; Right : in String) return Boolean; 42 function ">=" (Left : in String; Right : in Bounded_String) return Boolean; 43 -- Search functions 44 function Index (Source : in Bounded_String; Pattern : in String; Going : in Direction := Forward; Mapping : in Maps.Character_Mapping := Maps.Identity) return Natural; 45 function Index (Source : in Bounded_String; Pattern : in String; Going : in Direction := Forward; Mapping : in Maps.Character_Mapping_Function) return Natural; 46 function Index (Source : in Bounded_String; Set : in Maps.Character_Set; Test : in Membership := Inside; Going : in Direction := Forward) return Natural; 47 function Index_Non_Blank (Source : in Bounded_String; Going : in Direction := Forward) return Natural; 48 function Count (Source : in Bounded_String; Pattern : in String; Mapping : in Maps.Character_Mapping := Maps.Identity) return Natural; 49 function Count (Source : in Bounded_String; Pattern : in String; Mapping : in Maps.Character_Mapping_Function) return Natural; 50 function Count (Source : in Bounded_String; Set : in Maps.Character_Set) return Natural; 51 procedure Find_Token (Source : in Bounded_String; Set : in Maps.Character_Set; Test : in Membership; First : out Positive; Last : out Natural); 52 -- String translation subprograms 53 function Translate (Source : in Bounded_String; Mapping : in Maps.Character_Mapping) return Bounded_String; 54 procedure Translate (Source : in out Bounded_String; Mapping : in Maps.Character_Mapping); 55 function Translate (Source : in Bounded_String; Mapping : in Maps.Character_Mapping_Function) return Bounded_String; 56 procedure Translate (Source : in out Bounded_String; Mapping : in Maps.Character_Mapping_Function); 57 -- String transformation subprograms 58 function Replace_Slice (Source : in Bounded_String; Low : in Positive; High : in Natural; By : in String; Drop : in Truncation := Error) return Bounded_String; 59 procedure Replace_Slice (Source : in out Bounded_String; Low : in Positive; High : in Natural; By : in String; Drop : in Truncation := Error); 60 function Insert (Source : in Bounded_String; Before : in Positive; New_Item : in String; Drop : in Truncation := Error) return Bounded_String; 61 procedure Insert (Source : in out Bounded_String; Before : in Positive; New_Item : in String; Drop : in Truncation := Error); 62 function Overwrite (Source : in Bounded_String; Position : in Positive; New_Item : in String; Drop : in Truncation := Error) return Bounded_String; 63 procedure Overwrite (Source : in out Bounded_String; Position : in Positive; New_Item : in String; Drop : in Truncation := Error); 64 function Delete (Source : in Bounded_String; From : in Positive; Through : in Natural) return Bounded_String; 65 procedure Delete (Source : in out Bounded_String; From : in Positive; Through : in Natural); 66 --String selector subprograms 67 function Trim (Source : in Bounded_String; Side : in Trim_End) return Bounded_String; procedure Trim (Source : in out Bounded_String; Side : in Trim_End); 68 function Trim (Source : in Bounded_String; Left : in Maps.Character_Set; Right : in Maps.Character_Set) return Bounded_String; 69 procedure Trim (Source : in out Bounded_String; Left : in Maps.Character_Set; Right : in Maps.Character_Set); 70 function Head (Source : in Bounded_String; Count : in Natural; Pad : in Character := Space; Drop : in Truncation := Error) return Bounded_String; 71 procedure Head (Source : in out Bounded_String; Count : in Natural; Pad : in Character := Space; Drop : in Truncation := Error); 72 function Tail (Source : in Bounded_String; Count : in Natural; Pad : in Character := Space; Drop : in Truncation := Error) return Bounded_String; 73 procedure Tail (Source : in out Bounded_String; Count : in Natural; Pad : in Character := Space; Drop : in Truncation := Error); 74 --String constructor subprograms 75 function "*" (Left : in Natural; Right : in Character) return Bounded_String; 76 function "*" (Left : in Natural; Right : in String) return Bounded_String; 77 function "*" (Left : in Natural; Right : in Bounded_String) return Bounded_String; 78 function Replicate (Count : in Natural; Item : in Character; Drop : in Truncation := Error) return Bounded_String; 79 function Replicate (Count : in Natural; Item : in String; Drop : in Truncation := Error) return Bounded_String; 80 function Replicate (Count : in Natural; Item : in Bounded_String; Drop : in Truncation := Error) return Bounded_String; 81 private ... -- not specified by the language end Generic_Bounded_Length; 82 end Ada.Strings.Bounded; 83 Null_Bounded_String represents the null string. If an object of type Bounded_String is not otherwise initialized, it will be initialized to the same value as Null_Bounded_String. 84 function Length (Source : in Bounded_String) return Length_Range; 85 The Length function returns the length of the string represented by Source. 86 function To_Bounded_String (Source : in String; Drop : in Truncation := Error) return Bounded_String; 87 If Source'Length <= Max_Length then this function returns a Bounded_String that represents Source. Otherwise the effect depends on the value of Drop: 88 If Drop=Left, then the result is a Bounded_String that represents the string comprising the rightmost Max_Length characters of Source. 89 If Drop=Right, then the result is a Bounded_String that represents the string comprising the leftmost Max_Length characters of Source. 90 If Drop=Error, then Strings.Length_Error is propagated. 91 function To_String (Source : in Bounded_String) return String; 92 To_String returns the String value with lower bound 1 represented by Source. If B is a Bounded_String, then B = To_ Bounded_String(To_String(B)). 93 Each of the Append functions returns a Bounded_String obtained by concatenating the string or character given or represented by one of the parameters, with the string or character given or represented by the other parameter, and applying To_Bounded_String to the concatenation result string, with Drop as provided to the Append function. 94 Each of the procedures Append(Source, New_Item, Drop) has the same effect as the corresponding assignment Source := Append(Source, New_Item, Drop). 95 Each of the "&" functions has the same effect as the corresponding Append function, with Error as the Drop parameter. 96 function Element (Source : in Bounded_String; Index : in Positive) return Character; 97 Returns the character at position Index in the string represented by Source; propagates Index_Error if Index > Length(Source). 98 procedure Replace_Element (Source : in out Bounded_String; Index : in Positive; By : in Character); 99 Updates Source such that the character at position Index in the string represented by Source is By; propagates Index_Error if Index > Length(Source). 100 function Slice (Source : in Bounded_String; Low : in Positive; High : in Natural) return String; 101 Returns the slice at positions Low through High in the string represented by Source; propagates Index_Error if Low > Length(Source)+1. 102 Each of the functions "=", "<", ">","<=", and ">=" returns the same result as the corresponding String operation applied to the String values given or represented by the two parameters. 103 Each of the search subprograms (Index, Index_Non_Blank, Count, Find_ Token) has the same effect as the corresponding subprogram in Strings.Fixed applied to the string represented by the Bounded_String parameter. 104 Each of the Translate subprograms, when applied to a Bounded_String, has an analogous effect to the corresponding subprogram in Strings.Fixed. For the Translate function, the translation is applied to the string represented by the Bounded_String parameter, and the result is converted (via To_Bounded_String) to a Bounded_String. For the Translate procedure, the string represented by the Bounded_String parameter after the translation is given by the Translate function for fixed-length strings applied to the string represented by the original value of the parameter. 105 Each of the transformation subprograms (Replace_Slice, Insert, Overwrite, Delete), selector subprograms (Trim, Head, Tail), and constructor functions ("*") has an effect based on its corresponding subprogram in Strings.Fixed, and Replicate is based on Fixed."*". For each of these subprograms, the corresponding fixed-length string subprogram is applied to the string represented by the Bounded_String parameter. To_Bounded_String is applied the result string, with Drop (or Error in the case of Generic_ Bounded_Length."*") determining the effect when the string length exceeds Max_Length. Implementation Advice 106 Bounded string objects should not be implemented by implicit pointers and dynamic allocation. A.4.5 Unbounded-Length String Handling 1 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 needed to reflect the flexibility in length. Since the Unbounded_String type is private, relevant constructor and selector operations are provided. Static Semantics 2 The library package Strings.Unbounded has the following declaration: 3 with Ada.Strings.Maps; package Ada.Strings.Unbounded is pragma Preelaborate(Unbounded); 4 type Unbounded_String is private; 5 Null_Unbounded_String : constant Unbounded_String; 6 function Length (Source : in Unbounded_String) return Natural; 7 type String_Access is access all String; procedure Free (X : in out String_Access); 8 -- Conversion, Concatenation, and Selection functions 9 function To_Unbounded_String (Source : in String) return Unbounded_String; 10 function To_Unbounded_String (Length : in Natural) return Unbounded_String; 11 function To_String (Source : in Unbounded_String) return String; 12 procedure Append (Source : in out Unbounded_String; New_Item : in Unbounded_String); 13 procedure Append (Source : in out Unbounded_String; New_Item : in String); 14 procedure Append (Source : in out Unbounded_String; New_Item : in Character); 15 function "&" (Left, Right : in Unbounded_String) return Unbounded_String; 16 function "&" (Left : in Unbounded_String; Right : in String) return Unbounded_String; 17 function "&" (Left : in String; Right : in Unbounded_String) return Unbounded_String; 18 function "&" (Left : in Unbounded_String; Right : in Character) return Unbounded_String; 19 function "&" (Left : in Character; Right : in Unbounded_String) return Unbounded_String; 20 function Element (Source : in Unbounded_String; Index : in Positive) return Character; 21 procedure Replace_Element (Source : in out Unbounded_String; Index : in Positive; By : in Character); 22 function Slice (Source : in Unbounded_String; Low : in Positive; High : in Natural) return String; 23 function "=" (Left, Right : in Unbounded_String) return Boolean; 24 function "=" (Left : in Unbounded_String; Right : in String) return Boolean; 25 function "=" (Left : in String; Right : in Unbounded_String) return Boolean; 26 function "<" (Left, Right : in Unbounded_String) return Boolean; 27 function "<" (Left : in Unbounded_String; Right : in String) return Boolean; 28 function "<" (Left : in String; Right : in Unbounded_String) return Boolean; 29 function "<=" (Left, Right : in Unbounded_String) return Boolean; 30 function "<=" (Left : in Unbounded_String; Right : in String) return Boolean; 31 function "<=" (Left : in String; Right : in Unbounded_String) return Boolean; 32 function ">" (Left, Right : in Unbounded_String) return Boolean; 33 function ">" (Left : in Unbounded_String; Right : in String) return Boolean; 34 function ">" (Left : in String; Right : in Unbounded_String) return Boolean; 35 function ">=" (Left, Right : in Unbounded_String) return Boolean; 36 function ">=" (Left : in Unbounded_String; Right : in String) return Boolean; 37 function ">=" (Left : in String; Right : in Unbounded_String) return Boolean; 38 -- Search subprograms 39 function Index (Source : in Unbounded_String; Pattern : in String; Going : in Direction := Forward; Mapping : in Maps.Character_Mapping := Maps.Identity) return Natural; 40 function Index (Source : in Unbounded_String; Pattern : in String; Going : in Direction := Forward; Mapping : in Maps.Character_Mapping_Function) return Natural; 41 function Index (Source : in Unbounded_String; Set : in Maps.Character_Set; Test : in Membership := Inside; Going : in Direction := Forward) return Natural; 42 function Index_Non_Blank (Source : in Unbounded_String; Going : in Direction := Forward) return Natural; 43 function Count (Source : in Unbounded_String; Pattern : in String; Mapping : in Maps.Character_Mapping := Maps.Identity) return Natural; 44 function Count (Source : in Unbounded_String; Pattern : in String; Mapping : in Maps.Character_Mapping_Function) return Natural; 45 function Count (Source : in Unbounded_String; Set : in Maps.Character_Set) return Natural; 46 procedure Find_Token (Source : in Unbounded_String; Set : in Maps.Character_Set; Test : in Membership; First : out Positive; Last : out Natural); 47 -- String translation subprograms 48 function Translate (Source : in Unbounded_String; Mapping : in Maps.Character_Mapping) return Unbounded_String; 49 procedure Translate (Source : in out Unbounded_String; Mapping : in Maps.Character_Mapping); 50 function Translate (Source : in Unbounded_String; Mapping : in Maps.Character_Mapping_Function) return Unbounded_String; 51 procedure Translate (Source : in out Unbounded_String; Mapping : in Maps.Character_Mapping_Function); 52 -- String transformation subprograms 53 function Replace_Slice (Source : in Unbounded_String; Low : in Positive; High : in Natural; By : in String) return Unbounded_String; 54 procedure Replace_Slice (Source : in out Unbounded_String; Low : in Positive; High : in Natural; By : in String); 55 function Insert (Source : in Unbounded_String; Before : in Positive; New_Item : in String) return Unbounded_String; 56 procedure Insert (Source : in out Unbounded_String; Before : in Positive; New_Item : in String); 57 function Overwrite (Source : in Unbounded_String; Position : in Positive; New_Item : in String) return Unbounded_String; 58 procedure Overwrite (Source : in out Unbounded_String; Position : in Positive; New_Item : in String); 59 function Delete (Source : in Unbounded_String; From : in Positive; Through : in Natural) return Unbounded_String; 60 procedure Delete (Source : in out Unbounded_String; From : in Positive; Through : in Natural); 61 function Trim (Source : in Unbounded_String; Side : in Trim_End) return Unbounded_String; 62 procedure Trim (Source : in out Unbounded_String; Side : in Trim_End); 63 function Trim (Source : in Unbounded_String; Left : in Maps.Character_Set; Right : in Maps.Character_Set) return Unbounded_String; 64 procedure Trim (Source : in out Unbounded_String; Left : in Maps.Character_Set; Right : in Maps.Character_Set); 65 function Head (Source : in Unbounded_String; Count : in Natural; Pad : in Character := Space) return Unbounded_String; 66 procedure Head (Source : in out Unbounded_String; Count : in Natural; Pad : in Character := Space); 67 function Tail (Source : in Unbounded_String; Count : in Natural; Pad : in Character := Space) return Unbounded_String; 68 procedure Tail (Source : in out Unbounded_String; Count : in Natural; Pad : in Character := Space); 69 function "*" (Left : in Natural; Right : in Character) return Unbounded_String; 70 function "*" (Left : in Natural; Right : in String) return Unbounded_String; 71 function "*" (Left : in Natural; Right : in Unbounded_String) return Unbounded_String; 72 private ... -- not specified by the language end Ada.Strings.Unbounded; 73 Null_Unbounded_String represents the null String. If an object of type Unbounded_String is not otherwise initialized, it will be initialized to the same value as Null_Unbounded_String. 74 The function Length returns the length of the String represented by Source. 75 The type String_Access provides a (non-private) access type for explicit processing of unbounded-length strings. The procedure Free performs an unchecked deallocation of an object of type String_Access. 76 The function To_Unbounded_String(Source : in String) returns an Unbounded_String that represents Source. The function To_Unbounded_ String(Length : in Natural) returns an Unbounded_String that represents an uninitialized String whose length is Length. 77 The function To_String returns the String with lower bound 1 represented by Source. To_String and To_Unbounded_String are related as follows: 78 If S is a String, then To_String(To_Unbounded_String(S)) = S. 79 If U is an Unbounded_String, then To_Unbounded_String(To_ String(U)) = U. 80 For each of the Append procedures, the resulting string represented by the Source parameter is given by the concatenation of the original value of Source and the value of New_Item. 81 Each of the "&" functions returns an Unbounded_String obtained by concatenating the string or character given or represented by one of the parameters, with the string or character given or represented by the other parameter, and applying To_Unbounded_String to the concatenation result string. 82 The Element, Replace_Element, and Slice subprograms have the same effect as the corresponding bounded-length string subprograms. 83 Each of the functions "=", "<", ">","<=", and ">=" returns the same result as the corresponding String operation applied to the String values given or represented by Left and Right. 84 Each of the search subprograms (Index, Index_Non_Blank, Count, Find_ Token) has the same effect as the corresponding subprogram in Strings.Fixed applied to the string represented by the Unbounded_String parameter. 85 The Translate function has an analogous effect to the corresponding subprogram in Strings.Fixed. The translation is applied to the string represented by the Unbounded_String parameter, and the result is converted (via To_Unbounded_String) to an Unbounded_String. 86 Each of the transformation functions (Replace_Slice, Insert, Overwrite, Delete), selector functions (Trim, Head, Tail), and constructor functions ("*") is likewise analogous to its corresponding subprogram in Strings.Fixed. For each of the subprograms, the corresponding fixed-length string subprogram is applied to the string represented by the Unbounded_String parameter, and To_Unbounded_String is applied the result string. 87 For each of the procedures Translate, Replace_Slice, Insert, Overwrite, Delete, Trim, Head, and Tail, the resulting string represented by the Source parameter is given by the corresponding function for fixed-length strings applied to the string represented by Source's original value. Implementation Requirements 88 No storage associated with an Unbounded_String object shall be lost upon assignment or scope exit. A.4.6 String-Handling Sets and Mappings 1 The language-defined package Strings.Maps.Constants declares Character_ Set and Character_Mapping constants corresponding to classification and conversion functions in package Characters.Handling. Static Semantics 2 The library package Strings.Maps.Constants has the following declaration: 3 package Ada.Strings.Maps.Constants is pragma Preelaborate(Constants); 4 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; 5 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 6 private ... -- not specified by the language end Ada.Strings.Maps.Constants; 7 Each of these constants represents a correspondingly named set of characters or character mapping in Characters.Handling (see A.3.2). A.4.7 Wide_String Handling 1 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. They provide the same string-handling operations as the corresponding packages for strings of Character elements. Static Semantics 2 The package Strings.Wide_Maps has the following declaration. 3 package Ada.Strings.Wide_Maps is pragma Preelaborate(Wide_Maps); 4 -- Representation for a set of Wide_Character values: type Wide_Character_Set is private; 5 Null_Set : constant Wide_Character_Set; 6 type Wide_Character_Range is record Low : Wide_Character; High : Wide_Character; end record; -- Represents Wide_Character range Low..High 7 type Wide_Character_Ranges is array (Positive range <>) of Wide_Characte\ r_Range; 8 function To_Set (Ranges : in Wide_Character_Ranges) return Wide_Chara\ cter_Set; 9 function To_Set (Span : in Wide_Character_Range) return Wide_Chara\ cter_Set; 10 function To_Ranges (Set : in Wide_Character_Set) return Wide_Chara\ cter_Ranges; 11 function "=" (Left, Right : in Wide_Character_Set) return Boolean; 12 function "not" (Right : in Wide_Character_Set) return Wide_Charact\ er_Set; function "and" (Left, Right : in Wide_Character_Set) return Wide_Charact\ er_Set; function "or" (Left, Right : in Wide_Character_Set) return Wide_Charact\ er_Set; function "xor" (Left, Right : in Wide_Character_Set) return Wide_Charact\ er_Set; function "-" (Left, Right : in Wide_Character_Set) return Wide_Charact\ er_Set; 13 function Is_In (Element : in Wide_Character; Set : in Wide_Character_Set) return Boolean; 14 function Is_Subset (Elements : in Wide_Character_Set; Set : in Wide_Character_Set) return Boolean; 15 function "<=" (Left : in Wide_Character_Set; Right : in Wide_Character_Set) return Boolean renames Is_Subset; 16 -- Alternative representation for a set of Wide_Character values: subtype Wide_Character_Sequence is Wide_String; 17 function To_Set (Sequence : in Wide_Character_Sequence) return Wide_Cha\ racter_Set; 18 function To_Set (Singleton : in Wide_Character) return Wide_Character_Se\ t; 19 function To_Sequence (Set : in Wide_Character_Set) return Wide_Characte\ r_Sequence; 20 -- Representation for a Wide_Character to Wide_Character mapping: type Wide_Character_Mapping is private; 21 function Value (Map : in Wide_Character_Mapping; Element : in Wide_Character) return Wide_Character; 22 Identity : constant Wide_Character_Mapping; 23 function To_Mapping (From, To : in Wide_Character_Sequence) return Wide_Character_Mapping; 24 function To_Domain (Map : in Wide_Character_Mapping) return Wide_Character_Sequence; 25 function To_Range (Map : in Wide_Character_Mapping) return Wide_Character_Sequence; 26 type Wide_Character_Mapping_Function is access function (From : in Wide_Character) return Wide_Character; 27 private ... -- not specified by the language end Ada.Strings.Wide_Maps; 28 The context clause for each of the packages Strings.Wide_Fixed, Strings.Wide_Bounded, and Strings.Wide_Unbounded identifies Strings.Wide_Maps instead of Strings.Maps. 29 For each of the packages Strings.Fixed, Strings.Bounded, Strings.- Unbounded, and Strings.Maps.Constants the corresponding wide string package has the same contents except that 30 Wide_Space replaces Space 31 Wide_Character replaces Character 32 Wide_String replaces String 33 Wide_Character_Set replaces Character_Set 34 Wide_Character_Mapping replaces Character_Mapping 35 Wide_Character_Mapping_Function replaces Character_Mapping_Func- tion 36 Wide_Maps replaces Maps 37 Bounded_Wide_String replaces Bounded_String 38 Null_Bounded_Wide_String replaces Null_Bounded_String 39 To_Bounded_Wide_String replaces To_Bounded_String 40 To_Wide_String replaces To_String 41 Unbounded_Wide_String replaces Unbounded_String 42 Null_Unbounded_Wide_String replaces Null_Unbounded_String 43 Wide_String_Access replaces String_Access 44 To_Unbounded_Wide_String replaces To_Unbounded_String 45 The following additional declaration is present in Strings.Wide_ Maps.Wide_Constants: 46 Character_Set : constant Wide_Maps.Wide_Character_Set; --Contains each Wide_Character value WC such that Characters.Is_Character(W\ C) is True NOTES 47 (12) If a null Wide_Character_Mapping_Function is passed to any of the Wide_String handling subprograms, Constraint_Error is propagated. 48 (13) Each Wide_Character_Set constant in the package Strings.Wide_ Maps.Wide_Constants contains no values outside the Character portion of Wide_Character. Similarly, each Wide_Character_Mapping constant in this package is the identity mapping when applied to any element outside the Character portion of Wide_Character. A.5 The Numerics Packages 1 The library package Numerics is the parent of several child units that provide facilities for mathematical computation. One child, the generic package Generic_Elementary_Functions, is defined in A.5.1, together with nongeneric equivalents; two others, the package Float_Random and the generic package Discrete_Random, are defined in A.5.2. Additional (optional) children are defined in Annex G, ``Numerics''. Static Semantics 2 3 package Ada.Numerics is pragma Pure(Numerics); Argument_Error : exception; Pi : constant := 3.14159_26535_89793_23846_26433_83279_50288_41971_69399_37511; e : constant := 2.71828_18284_59045_23536_02874_71352_66249_77572_47093_69996; end Ada.Numerics; 4 The Argument_Error exception is raised by a subprogram in a child unit of Numerics to signal that one or more of the actual subprogram parameters are outside the domain of the corresponding mathematical function. Implementation Permissions 5 The implementation may specify the values of Pi and e to a larger number of significant digits. A.5.1 Elementary Functions 1 Implementation-defined approximations to the mathematical functions known as the ``elementary functions'' are provided by the subprograms in Numerics.Generic_Elementary_Functions. Nongeneric equivalents of this generic package for each of the predefined floating point types are also provided as children of Numerics. Static Semantics 2 The generic library package Numerics.Generic_Elementary_Functions has the following declaration: 3 generic type Float_Type is digits <>; package Ada.Numerics.Generic_Elementary_Functions is pragma Pure(Generic_Elementary_Functions); 4 function Sqrt (X : Float_Type'Base) return Float_Typ\ e'Base; function Log (X : Float_Type'Base) return Float_Typ\ e'Base; function Log (X, Base : Float_Type'Base) return Float_Typ\ e'Base; function Exp (X : Float_Type'Base) return Float_Typ\ e'Base; function "**" (Left, Right : Float_Type'Base) return Float_Typ\ e'Base; 5 function Sin (X : Float_Type'Base) return Float_Typ\ e'Base; function Sin (X, Cycle : Float_Type'Base) return Float_Typ\ e'Base; function Cos (X : Float_Type'Base) return Float_Typ\ e'Base; function Cos (X, Cycle : Float_Type'Base) return Float_Typ\ e'Base; function Tan (X : Float_Type'Base) return Float_Typ\ e'Base; function Tan (X, Cycle : Float_Type'Base) return Float_Typ\ e'Base; function Cot (X : Float_Type'Base) return Float_Typ\ e'Base; function Cot (X, Cycle : Float_Type'Base) return Float_Typ\ e'Base; 6 function Arcsin (X : Float_Type'Base) return Float_Typ\ e'Base; function Arcsin (X, Cycle : Float_Type'Base) return Float_Typ\ e'Base; function Arccos (X : Float_Type'Base) return Float_Typ\ e'Base; function Arccos (X, Cycle : Float_Type'Base) return Float_Typ\ e'Base; function Arctan (Y : Float_Type'Base; X : Float_Type'Base := 1.0) return Float_Typ\ e'Base; function Arctan (Y : Float_Type'Base; X : Float_Type'Base := 1.0; Cycle : Float_Type'Base) return Float_Typ\ e'Base; function Arccot (X : Float_Type'Base; Y : Float_Type'Base := 1.0) return Float_Typ\ e'Base; function Arccot (X : Float_Type'Base; Y : Float_Type'Base := 1.0; Cycle : Float_Type'Base) return Float_Typ\ e'Base; 7 function Sinh (X : Float_Type'Base) return Float_Typ\ e'Base; function Cosh (X : Float_Type'Base) return Float_Typ\ e'Base; function Tanh (X : Float_Type'Base) return Float_Typ\ e'Base; function Coth (X : Float_Type'Base) return Float_Typ\ e'Base; function Arcsinh (X : Float_Type'Base) return Float_Typ\ e'Base; function Arccosh (X : Float_Type'Base) return Float_Typ\ e'Base; function Arctanh (X : Float_Type'Base) return Float_Typ\ e'Base; function Arccoth (X : Float_Type'Base) return Float_Typ\ e'Base; 8 end Ada.Numerics.Generic_Elementary_Functions; 9 The library package Numerics.Elementary_Functions defines the same subprograms as Numerics.Generic_Elementary_Functions, except that the predefined type Float is systematically substituted for Float_Type'Base throughout. Nongeneric equivalents of Numerics.Generic_Elementary_Functions for each of the other predefined floating point types are defined similarly, with the names Numerics.Short_Elementary_Functions, Numerics.Long_Elementary_ Functions, etc. 10 The functions have their usual mathematical meanings. When the Base parameter is specified, the Log function computes the logarithm to the given base; otherwise, it computes the natural logarithm. When the Cycle parameter is specified, the parameter X of the forward trigonometric functions (Sin, Cos, Tan, and Cot) and the results of the inverse trigonometric functions (Arcsin, Arccos, Arctan, and Arccot) are measured in units such that a full cycle of revolution has the given value; otherwise, they are measured in radians. 11 The computed results of the mathematically multivalued functions are rendered single-valued by the following conventions, which are meant to imply the principal branch: 12 The results of the Sqrt and Arccosh functions and that of the exponentiation operator are nonnegative. 13 The result of the Arcsin function is in the quadrant containing the point (1.0, x), where x is the value of the parameter X. This quadrant is I or IV; thus, the range of the Arcsin function is approximately -Pi/2.0 to Pi/2.0 (-Cycle/4.0 to Cycle/4.0, if the parameter Cycle is specified). 14 The result of the Arccos function is in the quadrant containing the point (x, 1.0), where x is the value of the parameter X. This quadrant is I or II; thus, the Arccos function ranges from 0.0 to approximately Pi (Cycle/2.0, if the parameter Cycle is specified). 15 The results of the Arctan and Arccot functions are in the quadrant containing the point (x, y), where x and y are the values of the parameters X and Y, respectively. This may be any quadrant (I through IV) when the parameter X (resp., Y) of Arctan (resp., Arccot) is specified, but it is restricted to quadrants I and IV (resp., I and II) when that parameter is omitted. Thus, the range when that parameter is specified is approximately -Pi