From 13e8f0ed8e2cb25baa3fb424b4e721c46165ff93 Mon Sep 17 00:00:00 2001 From: Pierre-Marie de Rodat Date: Fri, 5 Jul 2019 07:02:17 +0000 Subject: [PATCH] [Ada] Import documentation from the RM for Ada.Strings.Fixed 2019-07-05 Pierre-Marie de Rodat gcc/ada/ * libgnat/a-strfix.ads: Import documentation from the RM From-SVN: r273109 --- gcc/ada/ChangeLog | 4 + gcc/ada/libgnat/a-strfix.ads | 223 +++++++++++++++++++++++++++++++---- 2 files changed, 202 insertions(+), 25 deletions(-) diff --git a/gcc/ada/ChangeLog b/gcc/ada/ChangeLog index 7fe957764f5..4c75bc92270 100644 --- a/gcc/ada/ChangeLog +++ b/gcc/ada/ChangeLog @@ -1,3 +1,7 @@ +2019-07-05 Pierre-Marie de Rodat + + * libgnat/a-strfix.ads: Import documentation from the RM + 2019-07-05 Yannick Moy * adabkend.adb (Scan_Back_End_Switches): Accept -Og and -Ofast diff --git a/gcc/ada/libgnat/a-strfix.ads b/gcc/ada/libgnat/a-strfix.ads index 56db8bc9458..157186104d2 100644 --- a/gcc/ada/libgnat/a-strfix.ads +++ b/gcc/ada/libgnat/a-strfix.ads @@ -15,6 +15,25 @@ with Ada.Strings.Maps; +-- 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. + package Ada.Strings.Fixed is pragma Preelaborate; @@ -28,6 +47,44 @@ package Ada.Strings.Fixed is Drop : Truncation := Error; Justify : Alignment := Left; Pad : Character := Space); + -- 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: + -- + -- * If Justify=Left, then Source is copied into the first Source'Length + -- characters of Target. + -- + -- * If Justify=Right, then Source is copied into the last Source'Length + -- characters of Target. + -- + -- * 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. + -- + -- * Pad is copied to each Target character not otherwise assigned. + -- + -- If Source is longer than Target, then the effect is based on Drop. + -- + -- * If Drop=Left, then the rightmost Target'Length characters of Source + -- are copied into Target. + -- + -- * If Drop=Right, then the leftmost Target'Length characters of Source + -- are copied into Target. + -- + -- * 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: + -- + -- * 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. + -- + -- * 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. + -- + -- * Otherwise, Length_Error is propagated. ------------------------ -- Search Subprograms -- @@ -36,36 +93,57 @@ package Ada.Strings.Fixed is function Index (Source : String; Pattern : String; + From : Positive; Going : Direction := Forward; - Mapping : Maps.Character_Mapping := Maps.Identity) return Natural; + Mapping : Maps.Character_Mapping_Function) return Natural; + pragma Ada_05 (Index); function Index (Source : String; Pattern : String; + From : Positive; Going : Direction := Forward; - Mapping : Maps.Character_Mapping_Function) return Natural; + Mapping : Maps.Character_Mapping := Maps.Identity) return Natural; + pragma Ada_05 (Index); - function Index - (Source : String; - Set : Maps.Character_Set; - Test : Membership := Inside; - Going : Direction := Forward) return Natural; + -- Each Index function searches, starting from From, 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 + -- Source is the null string, Index returns 0; otherwise, if From is not in + -- Source'Range, then Index_Error is propagated. If Going = Forward, then + -- Index returns the smallest index I which is greater than or equal to + -- From 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 and has an upper bound + -- less than or equal to From. If there is no such slice, then 0 is + -- returned. If Pattern is the null string, then Pattern_Error is + -- propagated. function Index (Source : String; Pattern : String; - From : Positive; Going : Direction := Forward; Mapping : Maps.Character_Mapping := Maps.Identity) return Natural; - pragma Ada_05 (Index); function Index (Source : String; Pattern : String; - From : Positive; Going : Direction := Forward; Mapping : Maps.Character_Mapping_Function) return Natural; - pragma Ada_05 (Index); + + -- If Going = Forward, returns: + -- + -- Index (Source, Pattern, Source'First, Forward, Mapping) + -- + -- otherwise, returns: + -- + -- Index (Source, Pattern, Source'Last, Backward, Mapping). + + function Index + (Source : String; + Set : Maps.Character_Set; + Test : Membership := Inside; + Going : Direction := Forward) return Natural; function Index (Source : String; @@ -74,16 +152,26 @@ package Ada.Strings.Fixed is Test : Membership := Inside; Going : Direction := Forward) return Natural; pragma Ada_05 (Index); + -- 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). If Source is the null string, Index + -- returns 0; otherwise, if From is not in Source'Range, then Index_Error + -- is propagated. Otherwise, it returns the smallest index I >= From (if + -- Going=Forward) or the largest index I <= From (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. function Index_Non_Blank (Source : String; + From : Positive; Going : Direction := Forward) return Natural; + pragma Ada_05 (Index_Non_Blank); + -- Returns Index (Source, Maps.To_Set(Space), From, Outside, Going) function Index_Non_Blank (Source : String; - From : Positive; Going : Direction := Forward) return Natural; - pragma Ada_05 (Index_Non_Blank); + -- Returns Index (Source, Maps.To_Set(Space), Outside, Going) function Count (Source : String; @@ -95,9 +183,15 @@ package Ada.Strings.Fixed is Pattern : String; Mapping : Maps.Character_Mapping_Function) return Natural; + -- 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. + function Count (Source : String; Set : Maps.Character_Set) return Natural; + -- Returns the number of occurrences in Source of characters that are in + -- Set. procedure Find_Token (Source : String; @@ -107,6 +201,13 @@ package Ada.Strings.Fixed is First : out Positive; Last : out Natural); pragma Ada_2012 (Find_Token); + -- If Source is not the null string and From is not in Source'Range, then + -- Index_Error is raised. Otherwise, First is set to the index of the first + -- character in Source(From .. Source'Last) that satisfies the Test + -- condition. Last is set to the largest index such that all characters in + -- Source(First .. Last) satisfy the Test condition. If no characters in + -- Source(From .. Source'Last) satisfy the Test condition, First is set to + -- From, and Last is set to 0. procedure Find_Token (Source : String; @@ -114,6 +215,7 @@ package Ada.Strings.Fixed is Test : Membership; First : out Positive; Last : out Natural); + -- Equivalent to Find_Token (Source, Set, Source'First, Test, First, Last) ------------------------------------ -- String Translation Subprograms -- @@ -121,30 +223,30 @@ package Ada.Strings.Fixed is function Translate (Source : String; - Mapping : Maps.Character_Mapping) return String; - - procedure Translate - (Source : in out String; - Mapping : Maps.Character_Mapping); + Mapping : Maps.Character_Mapping_Function) return String; function Translate (Source : String; - Mapping : Maps.Character_Mapping_Function) return String; + Mapping : Maps.Character_Mapping) return String; + + -- 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. procedure Translate (Source : in out String; Mapping : Maps.Character_Mapping_Function); + procedure Translate + (Source : in out String; + Mapping : Maps.Character_Mapping); + + -- Equivalent to Source := Translate(Source, Mapping) + --------------------------------------- -- String Transformation Subprograms -- --------------------------------------- - function Replace_Slice - (Source : String; - Low : Positive; - High : Natural; - By : String) return String; - procedure Replace_Slice (Source : in out String; Low : Positive; @@ -153,33 +255,67 @@ package Ada.Strings.Fixed is Drop : Truncation := Error; Justify : Alignment := Left; Pad : Character := Space); + -- 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), but with lower bound 1. + -- + -- * If High < Low, then the returned string is + -- Insert (Source, Before => Low, New_Item => By). + + function Replace_Slice + (Source : String; + Low : Positive; + High : Natural; + By : String) return String; + -- Equivalent to: + -- + -- Move (Replace_Slice (Source, Low, High, By), + -- Source, Drop, Justify, Pad). function Insert (Source : String; Before : Positive; New_Item : String) return String; + -- 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. procedure Insert (Source : in out String; Before : Positive; New_Item : String; Drop : Truncation := Error); + -- Equivalent to Move (Insert (Source, Before, New_Item), Source, Drop) function Overwrite (Source : String; Position : Positive; New_Item : String) return String; + -- 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. procedure Overwrite (Source : in out String; Position : Positive; New_Item : String; Drop : Truncation := Right); + -- Equivalent to Move(Overwrite(Source, Position, New_Item), Source, Drop) function Delete (Source : String; From : Positive; Through : Natural) return String; + -- If From <= Through, the returned string is + -- Replace_Slice(Source, From, Through, ""); otherwise, it is Source with + -- lower bound 1. procedure Delete (Source : in out String; @@ -187,6 +323,10 @@ package Ada.Strings.Fixed is Through : Natural; Justify : Alignment := Left; Pad : Character := Space); + -- Equivalent to: + -- + -- Move (Delete (Source, From, Through), + -- Source, Justify => Justify, Pad => Pad). --------------------------------- -- String Selector Subprograms -- @@ -195,17 +335,26 @@ package Ada.Strings.Fixed is function Trim (Source : String; Side : Trim_End) return String; + -- 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). procedure Trim (Source : in out String; Side : Trim_End; Justify : Alignment := Left; Pad : Character := Space); + -- Equivalent to: + -- + -- Move (Trim (Source, Side), Source, Justify=>Justify, Pad=>Pad). function Trim (Source : String; Left : Maps.Character_Set; Right : Maps.Character_Set) return String; + -- Returns the string obtained by removing from Source all leading + -- characters in Left and all trailing characters in Right. procedure Trim (Source : in out String; @@ -213,28 +362,46 @@ package Ada.Strings.Fixed is Right : Maps.Character_Set; Justify : Alignment := Strings.Left; Pad : Character := Space); + -- Equivalent to: + -- + -- Move (Trim (Source, Left, Right), + -- Source, Justify => Justify, Pad=>Pad). function Head (Source : String; Count : Natural; Pad : Character := Space) return String; + -- 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. procedure Head (Source : in out String; Count : Natural; Justify : Alignment := Left; Pad : Character := Space); + -- Equivalent to: + -- + -- Move (Head (Source, Count, Pad), + -- Source, Drop => Error, Justify => Justify, Pad => Pad). function Tail (Source : String; Count : Natural; Pad : Character := Space) return String; + -- 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. procedure Tail (Source : in out String; Count : Natural; Justify : Alignment := Left; Pad : Character := Space); + -- Equivalent to: + -- + -- Move (Tail (Source, Count, Pad), + -- Source, Drop => Error, Justify => Justify, Pad => Pad). ---------------------------------- -- String Constructor Functions -- @@ -248,4 +415,10 @@ package Ada.Strings.Fixed is (Left : Natural; Right : String) return String; + -- 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 otherwise is (Left - 1)*Right & Right with lower bound 1. + end Ada.Strings.Fixed; -- 2.30.2