gcc/ada/a-strunb.ads

   1 ------------------------------------------------------------------------------
   2 --                                                                          --
   3 --                         GNAT RUN-TIME 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-2005, 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,  51  Franklin  Street,  Fifth  Floor, --
  24 -- Boston, MA 02110-1301, 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;
  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
  59      (Source : String)  return Unbounded_String;
  60
  61    function To_Unbounded_String
  62      (Length : Natural) return Unbounded_String;
  63
  64    function To_String (Source : Unbounded_String) return String;
  65
  66    procedure Set_Unbounded_String
  67      (Target : out Unbounded_String;
  68       Source : String);
  69    pragma Ada_05 (Set_Unbounded_String);
  70
  71    procedure Append
  72      (Source   : in out Unbounded_String;
  73       New_Item : Unbounded_String);
  74
  75    procedure Append
  76      (Source   : in out Unbounded_String;
  77       New_Item : String);
  78
  79    procedure Append
  80      (Source   : in out Unbounded_String;
  81       New_Item : Character);
  82
  83    function "&"
  84      (Left  : Unbounded_String;
  85       Right : Unbounded_String) return Unbounded_String;
  86
  87    function "&"
  88      (Left  : Unbounded_String;
  89       Right : String) return Unbounded_String;
  90
  91    function "&"
  92      (Left  : String;
  93       Right : Unbounded_String) return Unbounded_String;
  94
  95    function "&"
  96      (Left  : Unbounded_String;
  97       Right : Character) return Unbounded_String;
  98
  99    function "&"
 100      (Left  : Character;
 101       Right : Unbounded_String) return Unbounded_String;
 102
 103    function Element
 104      (Source : Unbounded_String;
 105       Index  : Positive) return Character;
 106
 107    procedure Replace_Element
 108      (Source : in out Unbounded_String;
 109       Index  : Positive;
 110       By     : Character);
 111
 112    function Slice
 113      (Source : Unbounded_String;
 114       Low    : Positive;
 115       High   : Natural) return String;
 116
 117    function Unbounded_Slice
 118      (Source : Unbounded_String;
 119       Low    : Positive;
 120       High   : Natural) return Unbounded_String;
 121    pragma Ada_05 (Unbounded_Slice);
 122
 123    procedure Unbounded_Slice
 124      (Source : Unbounded_String;
 125       Target : out Unbounded_String;
 126       Low    : Positive;
 127       High   : Natural);
 128    pragma Ada_05 (Unbounded_Slice);
 129
 130    function "="
 131      (Left  : Unbounded_String;
 132       Right : Unbounded_String) return Boolean;
 133
 134    function "="
 135      (Left  : Unbounded_String;
 136       Right : String) return Boolean;
 137
 138    function "="
 139      (Left  : String;
 140       Right : Unbounded_String) return Boolean;
 141
 142    function "<"
 143      (Left  : Unbounded_String;
 144       Right : Unbounded_String) return Boolean;
 145
 146    function "<"
 147      (Left  : Unbounded_String;
 148       Right : String) return Boolean;
 149
 150    function "<"
 151      (Left  : String;
 152       Right : Unbounded_String) return Boolean;
 153
 154    function "<="
 155      (Left  : Unbounded_String;
 156       Right : Unbounded_String) return Boolean;
 157
 158    function "<="
 159      (Left  : Unbounded_String;
 160       Right : String) return Boolean;
 161
 162    function "<="
 163      (Left  : String;
 164       Right : Unbounded_String) return Boolean;
 165
 166    function ">"
 167      (Left  : Unbounded_String;
 168       Right : Unbounded_String) return Boolean;
 169
 170    function ">"
 171      (Left  : Unbounded_String;
 172       Right : String) return Boolean;
 173
 174    function ">"
 175      (Left  : String;
 176       Right : Unbounded_String) return Boolean;
 177
 178    function ">="
 179      (Left  : Unbounded_String;
 180       Right : Unbounded_String) return Boolean;
 181
 182    function ">="
 183      (Left  : Unbounded_String;
 184       Right : String) return Boolean;
 185
 186    function ">="
 187      (Left  : String;
 188       Right : Unbounded_String) return Boolean;
 189
 190    ------------------------
 191    -- Search Subprograms --
 192    ------------------------
 193
 194    function Index
 195      (Source  : Unbounded_String;
 196       Pattern : String;
 197       Going   : Direction := Forward;
 198       Mapping : Maps.Character_Mapping := Maps.Identity) return Natural;
 199
 200    function Index
 201      (Source  : Unbounded_String;
 202       Pattern : String;
 203       Going   : Direction := Forward;
 204       Mapping : Maps.Character_Mapping_Function) return Natural;
 205
 206    function Index
 207      (Source : Unbounded_String;
 208       Set    : Maps.Character_Set;
 209       Test   : Membership := Inside;
 210       Going  : Direction  := Forward) return Natural;
 211
 212    function Index
 213      (Source  : Unbounded_String;
 214       Pattern : String;
 215       From    : Positive;
 216       Going   : Direction := Forward;
 217       Mapping : Maps.Character_Mapping := Maps.Identity) return Natural;
 218    pragma Ada_05 (Index);
 219
 220    function Index
 221      (Source  : Unbounded_String;
 222       Pattern : String;
 223       From    : Positive;
 224       Going   : Direction := Forward;
 225       Mapping : Maps.Character_Mapping_Function) return Natural;
 226    pragma Ada_05 (Index);
 227
 228    function Index
 229      (Source  : Unbounded_String;
 230       Set     : Maps.Character_Set;
 231       From    : Positive;
 232       Test    : Membership := Inside;
 233       Going   : Direction := Forward) return Natural;
 234    pragma Ada_05 (Index);
 235
 236    function Index_Non_Blank
 237      (Source : Unbounded_String;
 238       Going  : Direction := Forward) return Natural;
 239
 240    function Index_Non_Blank
 241      (Source : Unbounded_String;
 242       From   : Positive;
 243       Going  : Direction := Forward) return Natural;
 244    pragma Ada_05 (Index_Non_Blank);
 245
 246    function Count
 247      (Source  : Unbounded_String;
 248       Pattern : String;
 249       Mapping : Maps.Character_Mapping := Maps.Identity) return Natural;
 250
 251    function Count
 252      (Source  : Unbounded_String;
 253       Pattern : String;
 254       Mapping : Maps.Character_Mapping_Function) return Natural;
 255
 256    function Count
 257      (Source : Unbounded_String;
 258       Set    : Maps.Character_Set) return Natural;
 259
 260    procedure Find_Token
 261      (Source : Unbounded_String;
 262       Set    : Maps.Character_Set;
 263       Test   : Membership;
 264       First  : out Positive;
 265       Last   : out Natural);
 266
 267    ------------------------------------
 268    -- String Translation Subprograms --
 269    ------------------------------------
 270
 271    function Translate
 272      (Source  : Unbounded_String;
 273       Mapping : Maps.Character_Mapping) return Unbounded_String;
 274
 275    procedure Translate
 276      (Source  : in out Unbounded_String;
 277       Mapping : Maps.Character_Mapping);
 278
 279    function Translate
 280      (Source  : Unbounded_String;
 281       Mapping : Maps.Character_Mapping_Function) return Unbounded_String;
 282
 283    procedure Translate
 284      (Source  : in out Unbounded_String;
 285       Mapping : Maps.Character_Mapping_Function);
 286
 287    ---------------------------------------
 288    -- String Transformation Subprograms --
 289    ---------------------------------------
 290
 291    function Replace_Slice
 292      (Source : Unbounded_String;
 293       Low    : Positive;
 294       High   : Natural;
 295       By     : String) return Unbounded_String;
 296
 297    procedure Replace_Slice
 298      (Source : in out Unbounded_String;
 299       Low    : Positive;
 300       High   : Natural;
 301       By     : String);
 302
 303    function Insert
 304      (Source   : Unbounded_String;
 305       Before   : Positive;
 306       New_Item : String) return Unbounded_String;
 307
 308    procedure Insert
 309      (Source   : in out Unbounded_String;
 310       Before   : Positive;
 311       New_Item : String);
 312
 313    function Overwrite
 314      (Source   : Unbounded_String;
 315       Position : Positive;
 316       New_Item : String) return Unbounded_String;
 317
 318    procedure Overwrite
 319      (Source   : in out Unbounded_String;
 320       Position : Positive;
 321       New_Item : String);
 322
 323    function Delete
 324      (Source  : Unbounded_String;
 325       From    : Positive;
 326       Through : Natural) return Unbounded_String;
 327
 328    procedure Delete
 329      (Source  : in out Unbounded_String;
 330       From    : Positive;
 331       Through : Natural);
 332
 333    function Trim
 334      (Source : Unbounded_String;
 335       Side   : Trim_End) return Unbounded_String;
 336
 337    procedure Trim
 338      (Source : in out Unbounded_String;
 339       Side   : Trim_End);
 340
 341    function Trim
 342      (Source : Unbounded_String;
 343       Left   : Maps.Character_Set;
 344       Right  : Maps.Character_Set) return Unbounded_String;
 345
 346    procedure Trim
 347      (Source : in out Unbounded_String;
 348       Left   : Maps.Character_Set;
 349       Right  : Maps.Character_Set);
 350
 351    function Head
 352      (Source : Unbounded_String;
 353       Count  : Natural;
 354       Pad    : Character := Space) return Unbounded_String;
 355
 356    procedure Head
 357      (Source : in out Unbounded_String;
 358       Count  : Natural;
 359       Pad    : Character := Space);
 360
 361    function Tail
 362      (Source : Unbounded_String;
 363       Count  : Natural;
 364       Pad    : Character := Space) return Unbounded_String;
 365
 366    procedure Tail
 367      (Source : in out Unbounded_String;
 368       Count  : Natural;
 369       Pad    : Character := Space);
 370
 371    function "*"
 372      (Left  : Natural;
 373       Right : Character) return Unbounded_String;
 374
 375    function "*"
 376      (Left  : Natural;
 377       Right : String) return Unbounded_String;
 378
 379    function "*"
 380      (Left  : Natural;
 381       Right : Unbounded_String) return Unbounded_String;
 382
 383 private
 384    pragma Inline (Length);
 385
 386    package AF renames Ada.Finalization;
 387
 388    Null_String : aliased String := "";
 389
 390    function To_Unbounded (S : String) return Unbounded_String
 391      renames To_Unbounded_String;
 392
 393    type Unbounded_String is new AF.Controlled with record
 394       Reference : String_Access := Null_String'Access;
 395       Last      : Natural       := 0;
 396    end record;
 397
 398    --  The Unbounded_String is using a buffered implementation to increase
 399    --  speed of the Append/Delete/Insert procedures. The Reference string
 400    --  pointer above contains the current string value and extra room at the
 401    --  end to be used by the next Append routine. Last is the index of the
 402    --  string ending character. So the current string value is really
 403    --  Reference (1 .. Last).
 404
 405    pragma Stream_Convert (Unbounded_String, To_Unbounded, To_String);
 406
 407    pragma Finalize_Storage_Only (Unbounded_String);
 408    --  Finalization is required only for freeing storage
 409
 410    procedure Initialize (Object : in out Unbounded_String);
 411    procedure Adjust     (Object : in out Unbounded_String);
 412    procedure Finalize   (Object : in out Unbounded_String);
 413
 414    procedure Realloc_For_Chunk
 415      (Source     : in out Unbounded_String;
 416       Chunk_Size : Natural);
 417    pragma Inline (Realloc_For_Chunk);
 418    --  Adjust the size allocated for the string. Add at least Chunk_Size so it
 419    --  is safe to add a string of this size at the end of the current content.
 420    --  The real size allocated for the string is Chunk_Size + x of the current
 421    --  string size. This buffered handling makes the Append unbounded string
 422    --  routines very fast. This spec is in the private part so that it can be
 423    --  accessed from children (e.g. from Unbounded.Text_IO).
 424
 425    Null_Unbounded_String : constant Unbounded_String :=
 426                              (AF.Controlled with
 427                                 Reference => Null_String'Access,
 428                                 Last => 0);
 429    --  Note: this declaration is illegal since library level controlled
 430    --  objects are not allowed in preelaborated units. See AI-161 for a
 431    --  discussion of this issue and an attempt to address it. Meanwhile,
 432    --  what happens in GNAT is that this check is omitted for internal
 433    --  implementation units (see check in sem_cat.adb).
 434
 435 end Ada.Strings.Unbounded;