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