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