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