gcc/ada/a-stzunb-shared.ads

   1 ------------------------------------------------------------------------------
   2 --                                                                          --
   3 --                         GNAT RUN-TIME COMPONENTS                         --
   4 --                                                                          --
   5 --      A D A . S T R I N G S . W I D E _ W I D E _ U N B O U N D E D       --
   6 --                                                                          --
   7 --                                 S p e c                                  --
   8 --                                                                          --
   9 --          Copyright (C) 1992-2010, 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 --  This version is supported on:
  39 --    - all Alpha platforms
  40 --    - all ia64 platforms
  41 --    - all PowerPC platforms
  42 --    - all SPARC V9 platforms
  43 --    - all x86_64 platforms
  44
  45 with Ada.Strings.Wide_Wide_Maps;
  46 private with Ada.Finalization;
  47 private with Interfaces;
  48
  49 package Ada.Strings.Wide_Wide_Unbounded is
  50    pragma Preelaborate;
  51
  52    type Unbounded_Wide_Wide_String is private;
  53    pragma Preelaborable_Initialization (Unbounded_Wide_Wide_String);
  54
  55    Null_Unbounded_Wide_Wide_String : constant Unbounded_Wide_Wide_String;
  56
  57    function Length (Source : Unbounded_Wide_Wide_String) return Natural;
  58
  59    type Wide_Wide_String_Access is access all Wide_Wide_String;
  60
  61    procedure Free (X : in out Wide_Wide_String_Access);
  62
  63    --------------------------------------------------------
  64    -- Conversion, Concatenation, and Selection Functions --
  65    --------------------------------------------------------
  66
  67    function To_Unbounded_Wide_Wide_String
  68      (Source : Wide_Wide_String) return Unbounded_Wide_Wide_String;
  69
  70    function To_Unbounded_Wide_Wide_String
  71      (Length : Natural) return Unbounded_Wide_Wide_String;
  72
  73    function To_Wide_Wide_String
  74      (Source : Unbounded_Wide_Wide_String) return Wide_Wide_String;
  75
  76    procedure Set_Unbounded_Wide_Wide_String
  77      (Target : out Unbounded_Wide_Wide_String;
  78       Source : Wide_Wide_String);
  79    pragma Ada_05 (Set_Unbounded_Wide_Wide_String);
  80
  81    procedure Append
  82      (Source   : in out Unbounded_Wide_Wide_String;
  83       New_Item : Unbounded_Wide_Wide_String);
  84
  85    procedure Append
  86      (Source   : in out Unbounded_Wide_Wide_String;
  87       New_Item : Wide_Wide_String);
  88
  89    procedure Append
  90      (Source   : in out Unbounded_Wide_Wide_String;
  91       New_Item : Wide_Wide_Character);
  92
  93    function "&"
  94      (Left  : Unbounded_Wide_Wide_String;
  95       Right : Unbounded_Wide_Wide_String) return Unbounded_Wide_Wide_String;
  96
  97    function "&"
  98      (Left  : Unbounded_Wide_Wide_String;
  99       Right : Wide_Wide_String) return Unbounded_Wide_Wide_String;
 100
 101    function "&"
 102      (Left  : Wide_Wide_String;
 103       Right : Unbounded_Wide_Wide_String) return Unbounded_Wide_Wide_String;
 104
 105    function "&"
 106      (Left  : Unbounded_Wide_Wide_String;
 107       Right : Wide_Wide_Character) return Unbounded_Wide_Wide_String;
 108
 109    function "&"
 110      (Left  : Wide_Wide_Character;
 111       Right : Unbounded_Wide_Wide_String) return Unbounded_Wide_Wide_String;
 112
 113    function Element
 114      (Source : Unbounded_Wide_Wide_String;
 115       Index  : Positive) return Wide_Wide_Character;
 116
 117    procedure Replace_Element
 118      (Source : in out Unbounded_Wide_Wide_String;
 119       Index  : Positive;
 120       By     : Wide_Wide_Character);
 121
 122    function Slice
 123      (Source : Unbounded_Wide_Wide_String;
 124       Low    : Positive;
 125       High   : Natural) return Wide_Wide_String;
 126
 127    function Unbounded_Slice
 128      (Source : Unbounded_Wide_Wide_String;
 129       Low    : Positive;
 130       High   : Natural) return Unbounded_Wide_Wide_String;
 131    pragma Ada_05 (Unbounded_Slice);
 132
 133    procedure Unbounded_Slice
 134      (Source : Unbounded_Wide_Wide_String;
 135       Target : out Unbounded_Wide_Wide_String;
 136       Low    : Positive;
 137       High   : Natural);
 138    pragma Ada_05 (Unbounded_Slice);
 139
 140    function "="
 141      (Left  : Unbounded_Wide_Wide_String;
 142       Right : Unbounded_Wide_Wide_String) return Boolean;
 143
 144    function "="
 145      (Left  : Unbounded_Wide_Wide_String;
 146       Right : Wide_Wide_String) return Boolean;
 147
 148    function "="
 149      (Left  : Wide_Wide_String;
 150       Right : Unbounded_Wide_Wide_String) return Boolean;
 151
 152    function "<"
 153      (Left  : Unbounded_Wide_Wide_String;
 154       Right : Unbounded_Wide_Wide_String) return Boolean;
 155
 156    function "<"
 157      (Left  : Unbounded_Wide_Wide_String;
 158       Right : Wide_Wide_String) return Boolean;
 159
 160    function "<"
 161      (Left  : Wide_Wide_String;
 162       Right : Unbounded_Wide_Wide_String) return Boolean;
 163
 164    function "<="
 165      (Left  : Unbounded_Wide_Wide_String;
 166       Right : Unbounded_Wide_Wide_String) return Boolean;
 167
 168    function "<="
 169      (Left  : Unbounded_Wide_Wide_String;
 170       Right : Wide_Wide_String) return Boolean;
 171
 172    function "<="
 173      (Left  : Wide_Wide_String;
 174       Right : Unbounded_Wide_Wide_String) return Boolean;
 175
 176    function ">"
 177      (Left  : Unbounded_Wide_Wide_String;
 178       Right : Unbounded_Wide_Wide_String) return Boolean;
 179
 180    function ">"
 181      (Left  : Unbounded_Wide_Wide_String;
 182       Right : Wide_Wide_String) return Boolean;
 183
 184    function ">"
 185      (Left  : Wide_Wide_String;
 186       Right : Unbounded_Wide_Wide_String) return Boolean;
 187
 188    function ">="
 189      (Left  : Unbounded_Wide_Wide_String;
 190       Right : Unbounded_Wide_Wide_String) return Boolean;
 191
 192    function ">="
 193      (Left  : Unbounded_Wide_Wide_String;
 194       Right : Wide_Wide_String) return Boolean;
 195
 196    function ">="
 197      (Left  : Wide_Wide_String;
 198       Right : Unbounded_Wide_Wide_String) return Boolean;
 199
 200    ------------------------
 201    -- Search Subprograms --
 202    ------------------------
 203
 204    function Index
 205      (Source  : Unbounded_Wide_Wide_String;
 206       Pattern : Wide_Wide_String;
 207       Going   : Direction := Forward;
 208       Mapping : Wide_Wide_Maps.Wide_Wide_Character_Mapping :=
 209                   Wide_Wide_Maps.Identity)
 210       return Natural;
 211
 212    function Index
 213      (Source  : Unbounded_Wide_Wide_String;
 214       Pattern : Wide_Wide_String;
 215       Going   : Direction := Forward;
 216       Mapping : Wide_Wide_Maps.Wide_Wide_Character_Mapping_Function)
 217       return Natural;
 218
 219    function Index
 220      (Source : Unbounded_Wide_Wide_String;
 221       Set    : Wide_Wide_Maps.Wide_Wide_Character_Set;
 222       Test   : Membership := Inside;
 223       Going  : Direction  := Forward) return Natural;
 224
 225    function Index
 226      (Source  : Unbounded_Wide_Wide_String;
 227       Pattern : Wide_Wide_String;
 228       From    : Positive;
 229       Going   : Direction := Forward;
 230       Mapping : Wide_Wide_Maps.Wide_Wide_Character_Mapping :=
 231                   Wide_Wide_Maps.Identity)
 232       return Natural;
 233    pragma Ada_05 (Index);
 234
 235    function Index
 236      (Source  : Unbounded_Wide_Wide_String;
 237       Pattern : Wide_Wide_String;
 238       From    : Positive;
 239       Going   : Direction := Forward;
 240       Mapping : Wide_Wide_Maps.Wide_Wide_Character_Mapping_Function)
 241       return Natural;
 242    pragma Ada_05 (Index);
 243
 244    function Index
 245      (Source  : Unbounded_Wide_Wide_String;
 246       Set     : Wide_Wide_Maps.Wide_Wide_Character_Set;
 247       From    : Positive;
 248       Test    : Membership := Inside;
 249       Going   : Direction := Forward) return Natural;
 250    pragma Ada_05 (Index);
 251
 252    function Index_Non_Blank
 253      (Source : Unbounded_Wide_Wide_String;
 254       Going  : Direction := Forward) return Natural;
 255
 256    function Index_Non_Blank
 257      (Source : Unbounded_Wide_Wide_String;
 258       From   : Positive;
 259       Going  : Direction := Forward) return Natural;
 260    pragma Ada_05 (Index_Non_Blank);
 261
 262    function Count
 263      (Source  : Unbounded_Wide_Wide_String;
 264       Pattern : Wide_Wide_String;
 265       Mapping : Wide_Wide_Maps.Wide_Wide_Character_Mapping :=
 266                   Wide_Wide_Maps.Identity)
 267       return Natural;
 268
 269    function Count
 270      (Source  : Unbounded_Wide_Wide_String;
 271       Pattern : Wide_Wide_String;
 272       Mapping : Wide_Wide_Maps.Wide_Wide_Character_Mapping_Function)
 273       return Natural;
 274
 275    function Count
 276      (Source : Unbounded_Wide_Wide_String;
 277       Set    : Wide_Wide_Maps.Wide_Wide_Character_Set) return Natural;
 278
 279    procedure Find_Token
 280      (Source : Unbounded_Wide_Wide_String;
 281       Set    : Wide_Wide_Maps.Wide_Wide_Character_Set;
 282       From   : Positive;
 283       Test   : Membership;
 284       First  : out Positive;
 285       Last   : out Natural);
 286    pragma Ada_2012 (Find_Token);
 287
 288    procedure Find_Token
 289      (Source : Unbounded_Wide_Wide_String;
 290       Set    : Wide_Wide_Maps.Wide_Wide_Character_Set;
 291       Test   : Membership;
 292       First  : out Positive;
 293       Last   : out Natural);
 294
 295    ------------------------------------
 296    -- String Translation Subprograms --
 297    ------------------------------------
 298
 299    function Translate
 300      (Source  : Unbounded_Wide_Wide_String;
 301       Mapping : Wide_Wide_Maps.Wide_Wide_Character_Mapping)
 302       return Unbounded_Wide_Wide_String;
 303
 304    procedure Translate
 305      (Source  : in out Unbounded_Wide_Wide_String;
 306       Mapping : Wide_Wide_Maps.Wide_Wide_Character_Mapping);
 307
 308    function Translate
 309      (Source  : Unbounded_Wide_Wide_String;
 310       Mapping : Wide_Wide_Maps.Wide_Wide_Character_Mapping_Function)
 311       return Unbounded_Wide_Wide_String;
 312
 313    procedure Translate
 314      (Source  : in out Unbounded_Wide_Wide_String;
 315       Mapping : Wide_Wide_Maps.Wide_Wide_Character_Mapping_Function);
 316
 317    ---------------------------------------
 318    -- String Transformation Subprograms --
 319    ---------------------------------------
 320
 321    function Replace_Slice
 322      (Source : Unbounded_Wide_Wide_String;
 323       Low    : Positive;
 324       High   : Natural;
 325       By     : Wide_Wide_String) return Unbounded_Wide_Wide_String;
 326
 327    procedure Replace_Slice
 328      (Source : in out Unbounded_Wide_Wide_String;
 329       Low    : Positive;
 330       High   : Natural;
 331       By     : Wide_Wide_String);
 332
 333    function Insert
 334      (Source   : Unbounded_Wide_Wide_String;
 335       Before   : Positive;
 336       New_Item : Wide_Wide_String) return Unbounded_Wide_Wide_String;
 337
 338    procedure Insert
 339      (Source   : in out Unbounded_Wide_Wide_String;
 340       Before   : Positive;
 341       New_Item : Wide_Wide_String);
 342
 343    function Overwrite
 344      (Source   : Unbounded_Wide_Wide_String;
 345       Position : Positive;
 346       New_Item : Wide_Wide_String) return Unbounded_Wide_Wide_String;
 347
 348    procedure Overwrite
 349      (Source   : in out Unbounded_Wide_Wide_String;
 350       Position : Positive;
 351       New_Item : Wide_Wide_String);
 352
 353    function Delete
 354      (Source  : Unbounded_Wide_Wide_String;
 355       From    : Positive;
 356       Through : Natural) return Unbounded_Wide_Wide_String;
 357
 358    procedure Delete
 359      (Source  : in out Unbounded_Wide_Wide_String;
 360       From    : Positive;
 361       Through : Natural);
 362
 363    function Trim
 364      (Source : Unbounded_Wide_Wide_String;
 365       Side   : Trim_End) return Unbounded_Wide_Wide_String;
 366
 367    procedure Trim
 368      (Source : in out Unbounded_Wide_Wide_String;
 369       Side   : Trim_End);
 370
 371    function Trim
 372      (Source : Unbounded_Wide_Wide_String;
 373       Left   : Wide_Wide_Maps.Wide_Wide_Character_Set;
 374       Right  : Wide_Wide_Maps.Wide_Wide_Character_Set)
 375       return Unbounded_Wide_Wide_String;
 376
 377    procedure Trim
 378      (Source : in out Unbounded_Wide_Wide_String;
 379       Left   : Wide_Wide_Maps.Wide_Wide_Character_Set;
 380       Right  : Wide_Wide_Maps.Wide_Wide_Character_Set);
 381
 382    function Head
 383      (Source : Unbounded_Wide_Wide_String;
 384       Count  : Natural;
 385       Pad    : Wide_Wide_Character := Wide_Wide_Space)
 386       return Unbounded_Wide_Wide_String;
 387
 388    procedure Head
 389      (Source : in out Unbounded_Wide_Wide_String;
 390       Count  : Natural;
 391       Pad    : Wide_Wide_Character := Wide_Wide_Space);
 392
 393    function Tail
 394      (Source : Unbounded_Wide_Wide_String;
 395       Count  : Natural;
 396       Pad    : Wide_Wide_Character := Wide_Wide_Space)
 397       return Unbounded_Wide_Wide_String;
 398
 399    procedure Tail
 400      (Source : in out Unbounded_Wide_Wide_String;
 401       Count  : Natural;
 402       Pad    : Wide_Wide_Character := Wide_Wide_Space);
 403
 404    function "*"
 405      (Left  : Natural;
 406       Right : Wide_Wide_Character) return Unbounded_Wide_Wide_String;
 407
 408    function "*"
 409      (Left  : Natural;
 410       Right : Wide_Wide_String) return Unbounded_Wide_Wide_String;
 411
 412    function "*"
 413      (Left  : Natural;
 414       Right : Unbounded_Wide_Wide_String) return Unbounded_Wide_Wide_String;
 415
 416 private
 417    pragma Inline (Length);
 418
 419    package AF renames Ada.Finalization;
 420
 421    type Shared_Wide_Wide_String (Max_Length : Natural) is limited record
 422       Counter : aliased Interfaces.Unsigned_32 := 1;
 423       --  Reference counter.
 424
 425       Last    : Natural                        := 0;
 426       Data    : Wide_Wide_String (1 .. Max_Length);
 427       --  Last is the index of last significant element of the Data. All
 428       --  elements with larger indecies are just an extra room.
 429    end record;
 430
 431    type Shared_Wide_Wide_String_Access is access all Shared_Wide_Wide_String;
 432
 433    procedure Reference (Item : not null Shared_Wide_Wide_String_Access);
 434    --  Increment reference counter.
 435
 436    procedure Unreference (Item : not null Shared_Wide_Wide_String_Access);
 437    --  Decrement reference counter. Deallocate Item when reference counter is
 438    --  zero.
 439
 440    function Can_Be_Reused
 441      (Item   : Shared_Wide_Wide_String_Access;
 442       Length : Natural) return Boolean;
 443    --  Returns True if Shared_Wide_Wide_String can be reused. There are two
 444    --  criteria when Shared_Wide_Wide_String can be reused: its reference
 445    --  counter must be one (thus Shared_Wide_Wide_String is owned exclusively)
 446    --  and its size is sufficient to store string with specified length
 447    --  effectively.
 448
 449    function Allocate
 450      (Max_Length : Natural) return Shared_Wide_Wide_String_Access;
 451    --  Allocates new Shared_Wide_Wide_String with at least specified maximum
 452    --  length. Actual maximum length of the allocated Shared_Wide_Wide_String
 453    --  can be sligtly greater. Returns reference to
 454    --  Empty_Shared_Wide_Wide_String when requested length is zero.
 455
 456    Empty_Shared_Wide_Wide_String : aliased Shared_Wide_Wide_String (0);
 457
 458    function To_Unbounded
 459      (S : Wide_Wide_String) return Unbounded_Wide_Wide_String
 460      renames To_Unbounded_Wide_Wide_String;
 461    --  This renames are here only to be used in the pragma Stream_Convert.
 462
 463    type Unbounded_Wide_Wide_String is new AF.Controlled with record
 464       Reference : Shared_Wide_Wide_String_Access :=
 465                     Empty_Shared_Wide_Wide_String'Access;
 466    end record;
 467
 468    --  The Unbounded_Wide_Wide_String uses several techniques to increasy speed
 469    --  of the application:
 470    --   - implicit sharing or copy-on-write. Unbounded_Wide_Wide_String
 471    --     contains only the reference to the data which is shared between
 472    --     several instances. The shared data is reallocated only when its value
 473    --     is changed and the object mutation can't be used or it is unefficient
 474    --     to use it;
 475    --   - object mutation. Shared data object can be reused without memory
 476    --     reallocation when all of the following requirements are meat:
 477    --      - shared data object don't used anywhere longer;
 478    --      - its size is sufficient to store new value;
 479    --      - the gap after reuse is less then some threashold.
 480    --   - memory preallocation. Most of used memory allocation algorithms
 481    --     alligns allocated segment on the some boundary, thus some amount of
 482    --     additional memory can be preallocated without any impact. Such
 483    --     preallocated memory can used later by Append/Insert operations
 484    --     without reallocation.
 485    --
 486    --  Reference counting uses GCC builtin atomic operations, which allows to
 487    --  safely share internal data between Ada tasks. Nevertheless, this not
 488    --  make objects of Unbounded_Wide_Wide_String thread-safe, so each instance
 489    --  can't be accessed by several tasks simulatenously.
 490
 491    pragma Stream_Convert
 492      (Unbounded_Wide_Wide_String, To_Unbounded, To_Wide_Wide_String);
 493    --  Provide stream routines without dragging in Ada.Streams
 494
 495    pragma Finalize_Storage_Only (Unbounded_Wide_Wide_String);
 496    --  Finalization is required only for freeing storage
 497
 498    overriding procedure Initialize
 499      (Object : in out Unbounded_Wide_Wide_String);
 500    overriding procedure Adjust
 501      (Object : in out Unbounded_Wide_Wide_String);
 502    overriding procedure Finalize
 503      (Object : in out Unbounded_Wide_Wide_String);
 504
 505    Null_Unbounded_Wide_Wide_String : constant Unbounded_Wide_Wide_String :=
 506                              (AF.Controlled with
 507                                 Reference =>
 508                                   Empty_Shared_Wide_Wide_String'Access);
 509
 510 end Ada.Strings.Wide_Wide_Unbounded;