gcc/ada/a-stwiun.ads

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