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