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