From: Pierre-Marie de Rodat Date: Fri, 5 Jul 2019 07:02:23 +0000 (+0000) Subject: [Ada] Import documentation from the RM for Ada.Strings.Unbounded X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=034a6629f4b3d64bf53dda42bf79b328c6d83190;p=gcc.git [Ada] Import documentation from the RM for Ada.Strings.Unbounded 2019-07-05 Pierre-Marie de Rodat gcc/ada/ * libgnat/a-strunb.ads: Import documentation from the RM From-SVN: r273110 --- diff --git a/gcc/ada/ChangeLog b/gcc/ada/ChangeLog index 4c75bc92270..a3bdd0ce53e 100644 --- a/gcc/ada/ChangeLog +++ b/gcc/ada/ChangeLog @@ -1,3 +1,7 @@ +2019-07-05 Pierre-Marie de Rodat + + * libgnat/a-strunb.ads: Import documentation from the RM + 2019-07-05 Pierre-Marie de Rodat * libgnat/a-strfix.ads: Import documentation from the RM diff --git a/gcc/ada/libgnat/a-strunb.ads b/gcc/ada/libgnat/a-strunb.ads index 601e69e9b06..c0caf10bb72 100644 --- a/gcc/ada/libgnat/a-strunb.ads +++ b/gcc/ada/libgnat/a-strunb.ads @@ -36,6 +36,15 @@ with Ada.Strings.Maps; with Ada.Finalization; +-- 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. + package Ada.Strings.Unbounded is pragma Preelaborate; @@ -43,12 +52,19 @@ package Ada.Strings.Unbounded is pragma Preelaborable_Initialization (Unbounded_String); Null_Unbounded_String : constant 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. function Length (Source : Unbounded_String) return Natural; + -- Returns the length of the String represented by Source type String_Access is access all String; + -- Provides a (nonprivate) access type for explicit processing of + -- unbounded-length strings. procedure Free (X : in out String_Access); + -- Performs an unchecked deallocation of an object of type String_Access -------------------------------------------------------- -- Conversion, Concatenation, and Selection Functions -- @@ -56,16 +72,28 @@ package Ada.Strings.Unbounded is function To_Unbounded_String (Source : String) return Unbounded_String; + -- Returns an Unbounded_String that represents Source function To_Unbounded_String (Length : Natural) return Unbounded_String; + -- Returns an Unbounded_String that represents an uninitialized String + -- whose length is Length. function To_String (Source : Unbounded_String) return String; + -- Returns the String with lower bound 1 represented by Source + + -- To_String and To_Unbounded_String are related as follows: + -- + -- * If S is a String, then To_String (To_Unbounded_String (S)) = S. + -- + -- * If U is an Unbounded_String, then + -- To_Unbounded_String (To_String (U)) = U. procedure Set_Unbounded_String (Target : out Unbounded_String; Source : String); pragma Ada_05 (Set_Unbounded_String); + -- Sets Target to an Unbounded_String that represents Source procedure Append (Source : in out Unbounded_String; @@ -79,6 +107,10 @@ package Ada.Strings.Unbounded is (Source : in out Unbounded_String; New_Item : Character); + -- 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. + function "&" (Left : Unbounded_String; Right : Unbounded_String) return Unbounded_String; @@ -99,25 +131,43 @@ package Ada.Strings.Unbounded is (Left : Character; Right : Unbounded_String) return Unbounded_String; + -- 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. + function Element (Source : Unbounded_String; Index : Positive) return Character; + -- Returns the character at position Index in the string represented by + -- Source; propagates Index_Error if Index > Length (Source). procedure Replace_Element (Source : in out Unbounded_String; Index : Positive; By : Character); + -- Updates Source such that the character at position Index in the string + -- represented by Source is By; propagates Index_Error if + -- Index > Length (Source). function Slice (Source : Unbounded_String; Low : Positive; High : Natural) return String; + -- Returns the slice at positions Low through High in the string + -- represented by Source; propagates Index_Error if + -- Low > Length (Source) + 1 or High > Length (Source). The bounds of the + -- returned string are Low and High. function Unbounded_Slice (Source : Unbounded_String; Low : Positive; High : Natural) return Unbounded_String; pragma Ada_05 (Unbounded_Slice); + -- Returns the slice at positions Low through High in the string + -- represented by Source as an Unbounded_String. This propagates + -- Index_Error if Low > Length(Source) + 1 or High > Length (Source). procedure Unbounded_Slice (Source : Unbounded_String; @@ -125,6 +175,9 @@ package Ada.Strings.Unbounded is Low : Positive; High : Natural); pragma Ada_05 (Unbounded_Slice); + -- Sets Target to the Unbounded_String representing the slice at positions + -- Low through High in the string represented by Source. This propagates + -- Index_Error if Low > Length(Source) + 1 or High > Length (Source). function "=" (Left : Unbounded_String; @@ -186,6 +239,10 @@ package Ada.Strings.Unbounded is (Left : String; Right : Unbounded_String) return Boolean; + -- 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. + ------------------------ -- Search Subprograms -- ------------------------ @@ -272,6 +329,11 @@ package Ada.Strings.Unbounded is First : out Positive; Last : out Natural); + -- 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. + ------------------------------------ -- String Translation Subprograms -- ------------------------------------ @@ -292,6 +354,11 @@ package Ada.Strings.Unbounded is (Source : in out Unbounded_String; Mapping : Maps.Character_Mapping_Function); + -- 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. + --------------------------------------- -- String Transformation Subprograms -- --------------------------------------- @@ -388,6 +455,19 @@ package Ada.Strings.Unbounded is (Left : Natural; Right : Unbounded_String) return Unbounded_String; + -- 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. + -- + -- 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. + private pragma Inline (Length);