gcc/ada/a-strunb.ads

   1 ------------------------------------------------------------------------------
   2 --                                                                          --
   3 --                          GNAT RUNTIME COMPONENTS                         --
   4 --                                                                          --
   5 --                A D A . S T R I N G S . U N B O U N D E D                 --
   6 --                                                                          --
   7 --                                 S p e c                                  --
   8 --                                                                          --
   9 --          Copyright (C) 1992-2002 Free Software Foundation, Inc.          --
  10 --                                                                          --
  11 -- This specification is derived from the Ada Reference Manual for use with --
  12 -- GNAT. The copyright notice above, and the license provisions that follow --
  13 -- apply solely to the  contents of the part following the private keyword. --
  14 --                                                                          --
  15 -- GNAT is free software;  you can  redistribute it  and/or modify it under --
  16 -- terms of the  GNU General Public License as published  by the Free Soft- --
  17 -- ware  Foundation;  either version 2,  or (at your option) any later ver- --
  18 -- sion.  GNAT is distributed in the hope that it will be useful, but WITH- --
  19 -- OUT ANY WARRANTY;  without even the  implied warranty of MERCHANTABILITY --
  20 -- or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License --
  21 -- for  more details.  You should have  received  a copy of the GNU General --
  22 -- Public License  distributed with GNAT;  see file COPYING.  If not, write --
  23 -- to  the Free Software Foundation,  59 Temple Place - Suite 330,  Boston, --
  24 -- MA 02111-1307, USA.                                                      --
  25 --                                                                          --
  26 -- As a special exception,  if other files  instantiate  generics from this --
  27 -- unit, or you link  this unit with other files  to produce an executable, --
  28 -- this  unit  does not  by itself cause  the resulting  executable  to  be --
  29 -- covered  by the  GNU  General  Public  License.  This exception does not --
  30 -- however invalidate  any other reasons why  the executable file  might be --
  31 -- covered by the  GNU Public License.                                      --
  32 --                                                                          --
  33 -- GNAT was originally developed  by the GNAT team at  New York University. --
  34 -- Extensive contributions were provided by Ada Core Technologies Inc.      --
  35 --                                                                          --
  36 ------------------------------------------------------------------------------
  37
  38 with Ada.Strings.Maps;
  39 with Ada.Finalization;
  40
  41 package Ada.Strings.Unbounded is
  42 pragma Preelaborate (Unbounded);
  43
  44    type Unbounded_String is private;
  45
  46    Null_Unbounded_String : constant Unbounded_String;
  47
  48    function Length (Source : Unbounded_String) return Natural;
  49
  50    type String_Access is access all String;
  51
  52    procedure Free (X : in out String_Access);
  53
  54    --------------------------------------------------------
  55    -- Conversion, Concatenation, and Selection Functions --
  56    --------------------------------------------------------
  57
  58    function To_Unbounded_String (Source : String)     return Unbounded_String;
  59    function To_Unbounded_String (Length : in Natural) return Unbounded_String;
  60
  61    function To_String (Source : Unbounded_String) return String;
  62
  63    procedure Append
  64      (Source   : in out Unbounded_String;
  65       New_Item : in Unbounded_String);
  66
  67    procedure Append
  68      (Source   : in out Unbounded_String;
  69       New_Item : in String);
  70
  71    procedure Append
  72      (Source   : in out Unbounded_String;
  73       New_Item : in Character);
  74
  75    function "&" (Left, Right : Unbounded_String) return Unbounded_String;
  76
  77    function "&"
  78      (Left  : in Unbounded_String;
  79       Right : in String)
  80       return  Unbounded_String;
  81
  82    function "&"
  83      (Left  : in String;
  84       Right : in Unbounded_String)
  85       return  Unbounded_String;
  86
  87    function "&"
  88      (Left  : in Unbounded_String;
  89       Right : in Character)
  90       return  Unbounded_String;
  91
  92    function "&"
  93      (Left  : in Character;
  94       Right : in Unbounded_String)
  95       return  Unbounded_String;
  96
  97    function Element
  98      (Source : in Unbounded_String;
  99       Index  : in Positive)
 100       return   Character;
 101
 102    procedure Replace_Element
 103      (Source : in out Unbounded_String;
 104       Index  : in Positive;
 105       By     : Character);
 106
 107    function Slice
 108      (Source : in Unbounded_String;
 109       Low    : in Positive;
 110       High   : in Natural)
 111       return   String;
 112
 113    function "=" (Left, Right : in Unbounded_String) return Boolean;
 114
 115    function "="
 116      (Left  : in Unbounded_String;
 117       Right : in String)
 118       return  Boolean;
 119
 120    function "="
 121      (Left  : in String;
 122       Right : in Unbounded_String)
 123       return  Boolean;
 124
 125    function "<" (Left, Right : in Unbounded_String) return Boolean;
 126
 127    function "<"
 128      (Left  : in Unbounded_String;
 129       Right : in String)
 130       return  Boolean;
 131
 132    function "<"
 133      (Left  : in String;
 134       Right : in Unbounded_String)
 135       return  Boolean;
 136
 137    function "<=" (Left, Right : in Unbounded_String) return Boolean;
 138
 139    function "<="
 140      (Left  : in Unbounded_String;
 141       Right : in String)
 142       return  Boolean;
 143
 144    function "<="
 145      (Left  : in String;
 146       Right : in Unbounded_String)
 147       return  Boolean;
 148
 149    function ">" (Left, Right : in Unbounded_String) return Boolean;
 150
 151    function ">"
 152      (Left  : in Unbounded_String;
 153       Right : in String)
 154       return  Boolean;
 155
 156    function ">"
 157      (Left  : in String;
 158       Right : in Unbounded_String)
 159       return  Boolean;
 160
 161    function ">=" (Left, Right : in Unbounded_String) return Boolean;
 162
 163    function ">="
 164      (Left  : in Unbounded_String;
 165       Right : in String)
 166       return  Boolean;
 167
 168    function ">="
 169      (Left  : in String;
 170       Right : in Unbounded_String)
 171       return  Boolean;
 172
 173    ------------------------
 174    -- Search Subprograms --
 175    ------------------------
 176
 177    function Index
 178      (Source   : in Unbounded_String;
 179       Pattern  : in String;
 180       Going    : in Direction := Forward;
 181       Mapping  : in Maps.Character_Mapping := Maps.Identity)
 182       return     Natural;
 183
 184    function Index
 185      (Source   : in Unbounded_String;
 186       Pattern  : in String;
 187       Going    : in Direction := Forward;
 188       Mapping  : in Maps.Character_Mapping_Function)
 189       return     Natural;
 190
 191    function Index
 192      (Source : in Unbounded_String;
 193       Set    : in Maps.Character_Set;
 194       Test   : in Membership := Inside;
 195       Going  : in Direction  := Forward)
 196       return   Natural;
 197
 198    function Index_Non_Blank
 199      (Source : in Unbounded_String;
 200       Going  : in Direction := Forward)
 201       return   Natural;
 202
 203    function Count
 204      (Source  : in Unbounded_String;
 205       Pattern : in String;
 206       Mapping : in Maps.Character_Mapping := Maps.Identity)
 207       return    Natural;
 208
 209    function Count
 210      (Source   : in Unbounded_String;
 211       Pattern  : in String;
 212       Mapping  : in Maps.Character_Mapping_Function)
 213       return     Natural;
 214
 215    function Count
 216      (Source : in Unbounded_String;
 217       Set    : in Maps.Character_Set)
 218       return   Natural;
 219
 220    procedure Find_Token
 221      (Source : in Unbounded_String;
 222       Set    : in Maps.Character_Set;
 223       Test   : in Membership;
 224       First  : out Positive;
 225       Last   : out Natural);
 226
 227    ------------------------------------
 228    -- String Translation Subprograms --
 229    ------------------------------------
 230
 231    function Translate
 232      (Source  : in Unbounded_String;
 233       Mapping : in Maps.Character_Mapping)
 234       return    Unbounded_String;
 235
 236    procedure Translate
 237      (Source  : in out Unbounded_String;
 238       Mapping : Maps.Character_Mapping);
 239
 240    function Translate
 241      (Source  : in Unbounded_String;
 242       Mapping : in Maps.Character_Mapping_Function)
 243       return    Unbounded_String;
 244
 245    procedure Translate
 246      (Source  : in out Unbounded_String;
 247       Mapping : in Maps.Character_Mapping_Function);
 248
 249    ---------------------------------------
 250    -- String Transformation Subprograms --
 251    ---------------------------------------
 252
 253    function Replace_Slice
 254      (Source : in Unbounded_String;
 255       Low    : in Positive;
 256       High   : in Natural;
 257       By     : in String)
 258       return   Unbounded_String;
 259
 260    procedure Replace_Slice
 261      (Source   : in out Unbounded_String;
 262       Low      : in Positive;
 263       High     : in Natural;
 264       By       : in String);
 265
 266    function Insert
 267      (Source   : in Unbounded_String;
 268       Before   : in Positive;
 269       New_Item : in String)
 270       return     Unbounded_String;
 271
 272    procedure Insert
 273      (Source   : in out Unbounded_String;
 274       Before   : in Positive;
 275       New_Item : in String);
 276
 277    function Overwrite
 278      (Source   : in Unbounded_String;
 279       Position : in Positive;
 280       New_Item : in String)
 281       return     Unbounded_String;
 282
 283    procedure Overwrite
 284      (Source    : in out Unbounded_String;
 285       Position  : in Positive;
 286       New_Item  : in String);
 287
 288    function Delete
 289      (Source  : in Unbounded_String;
 290       From    : in Positive;
 291       Through : in Natural)
 292       return    Unbounded_String;
 293
 294    procedure Delete
 295      (Source  : in out Unbounded_String;
 296       From    : in Positive;
 297       Through : in Natural);
 298
 299    function Trim
 300      (Source : in Unbounded_String;
 301       Side   : in Trim_End)
 302       return   Unbounded_String;
 303
 304    procedure Trim
 305      (Source : in out Unbounded_String;
 306       Side   : in Trim_End);
 307
 308    function Trim
 309      (Source : in Unbounded_String;
 310       Left   : in Maps.Character_Set;
 311       Right  : in Maps.Character_Set)
 312       return   Unbounded_String;
 313
 314    procedure Trim
 315      (Source : in out Unbounded_String;
 316       Left   : in Maps.Character_Set;
 317       Right  : in Maps.Character_Set);
 318
 319    function Head
 320      (Source : in Unbounded_String;
 321       Count  : in Natural;
 322       Pad    : in Character := Space)
 323       return   Unbounded_String;
 324
 325    procedure Head
 326      (Source : in out Unbounded_String;
 327       Count  : in Natural;
 328       Pad    : in Character := Space);
 329
 330    function Tail
 331      (Source : in Unbounded_String;
 332       Count  : in Natural;
 333       Pad    : in Character := Space)
 334       return   Unbounded_String;
 335
 336    procedure Tail
 337      (Source : in out Unbounded_String;
 338       Count  : in Natural;
 339       Pad    : in Character := Space);
 340
 341    function "*"
 342      (Left  : in Natural;
 343       Right : in Character)
 344       return  Unbounded_String;
 345
 346    function "*"
 347      (Left  : in Natural;
 348       Right : in String)
 349       return  Unbounded_String;
 350
 351    function "*"
 352      (Left  : in Natural;
 353       Right : in Unbounded_String)
 354       return  Unbounded_String;
 355
 356 private
 357    pragma Inline (Length);
 358
 359    package AF renames Ada.Finalization;
 360
 361    Null_String : aliased String := "";
 362
 363    function To_Unbounded (S : String) return Unbounded_String
 364      renames To_Unbounded_String;
 365
 366    type Unbounded_String is new AF.Controlled with record
 367       Reference : String_Access := Null_String'Access;
 368       Last      : Natural       := 0;
 369    end record;
 370
 371    --  The Unbounded_String is using a buffered implementation to increase
 372    --  speed of the Append/Delete/Insert procedures. The Reference string
 373    --  pointer above contains the current string value and extra room at the
 374    --  end to be used by the next Append routine. Last is the index of the
 375    --  string ending character. So the current string value is really
 376    --  Reference (1 .. Last).
 377
 378    pragma Stream_Convert (Unbounded_String, To_Unbounded, To_String);
 379
 380    pragma Finalize_Storage_Only (Unbounded_String);
 381
 382    procedure Initialize (Object : in out Unbounded_String);
 383    procedure Adjust     (Object : in out Unbounded_String);
 384    procedure Finalize   (Object : in out Unbounded_String);
 385
 386    --  Note: the following declaration is illegal since library level
 387    --  controlled objects are not allowed in preelaborated units. See
 388    --  AI-161 for a discussion of this issue and an attempt to address it.
 389    --  Meanwhile, what happens in GNAT is that this check is omitted for
 390    --  internal implementation units (see check in sem_cat.adb).
 391
 392    Null_Unbounded_String : constant Unbounded_String :=
 393      (AF.Controlled with Reference => Null_String'Access, Last => 0);
 394
 395 end Ada.Strings.Unbounded;