1.. _Implementation_Defined_Attributes: 2 3********************************* 4Implementation Defined Attributes 5********************************* 6 7Ada defines (throughout the Ada reference manual, 8summarized in Annex K), 9a set of attributes that provide useful additional functionality in all 10areas of the language. These language defined attributes are implemented 11in GNAT and work as described in the Ada Reference Manual. 12 13In addition, Ada allows implementations to define additional 14attributes whose meaning is defined by the implementation. GNAT provides 15a number of these implementation-dependent attributes which can be used 16to extend and enhance the functionality of the compiler. This section of 17the GNAT reference manual describes these additional attributes. It also 18describes additional implementation-dependent features of standard 19language-defined attributes. 20 21Note that any program using these attributes may not be portable to 22other compilers (although GNAT implements this set of attributes on all 23platforms). Therefore if portability to other compilers is an important 24consideration, you should minimize the use of these attributes. 25 26Attribute Abort_Signal 27====================== 28.. index:: Abort_Signal 29 30``Standard'Abort_Signal`` (``Standard`` is the only allowed 31prefix) provides the entity for the special exception used to signal 32task abort or asynchronous transfer of control. Normally this attribute 33should only be used in the tasking runtime (it is highly peculiar, and 34completely outside the normal semantics of Ada, for a user program to 35intercept the abort exception). 36 37Attribute Address_Size 38====================== 39.. index:: Size of ``Address`` 40 41.. index:: Address_Size 42 43``Standard'Address_Size`` (``Standard`` is the only allowed 44prefix) is a static constant giving the number of bits in an 45``Address``. It is the same value as System.Address'Size, 46but has the advantage of being static, while a direct 47reference to System.Address'Size is nonstatic because Address 48is a private type. 49 50Attribute Asm_Input 51=================== 52.. index:: Asm_Input 53 54The ``Asm_Input`` attribute denotes a function that takes two 55parameters. The first is a string, the second is an expression of the 56type designated by the prefix. The first (string) argument is required 57to be a static expression, and is the constraint for the parameter, 58(e.g., what kind of register is required). The second argument is the 59value to be used as the input argument. The possible values for the 60constant are the same as those used in the RTL, and are dependent on 61the configuration file used to built the GCC back end. 62:ref:`Machine_Code_Insertions` 63 64Attribute Asm_Output 65==================== 66.. index:: Asm_Output 67 68The ``Asm_Output`` attribute denotes a function that takes two 69parameters. The first is a string, the second is the name of a variable 70of the type designated by the attribute prefix. The first (string) 71argument is required to be a static expression and designates the 72constraint for the parameter (e.g., what kind of register is 73required). The second argument is the variable to be updated with the 74result. The possible values for constraint are the same as those used in 75the RTL, and are dependent on the configuration file used to build the 76GCC back end. If there are no output operands, then this argument may 77either be omitted, or explicitly given as ``No_Output_Operands``. 78:ref:`Machine_Code_Insertions` 79 80Attribute Atomic_Always_Lock_Free 81================================= 82.. index:: Atomic_Always_Lock_Free 83 84The prefix of the ``Atomic_Always_Lock_Free`` attribute is a type. 85The result is a Boolean value which is True if the type has discriminants, 86and False otherwise. The result indicate whether atomic operations are 87supported by the target for the given type. 88 89Attribute Bit 90============= 91.. index:: Bit 92 93``obj'Bit``, where ``obj`` is any object, yields the bit 94offset within the storage unit (byte) that contains the first bit of 95storage allocated for the object. The value of this attribute is of the 96type *universal_integer*, and is always a non-negative number not 97exceeding the value of ``System.Storage_Unit``. 98 99For an object that is a variable or a constant allocated in a register, 100the value is zero. (The use of this attribute does not force the 101allocation of a variable to memory). 102 103For an object that is a formal parameter, this attribute applies 104to either the matching actual parameter or to a copy of the 105matching actual parameter. 106 107For an access object the value is zero. Note that 108``obj.all'Bit`` is subject to an ``Access_Check`` for the 109designated object. Similarly for a record component 110``X.C'Bit`` is subject to a discriminant check and 111``X(I).Bit`` and ``X(I1..I2)'Bit`` 112are subject to index checks. 113 114This attribute is designed to be compatible with the DEC Ada 83 definition 115and implementation of the ``Bit`` attribute. 116 117Attribute Bit_Position 118====================== 119.. index:: Bit_Position 120 121``R.C'Bit_Position``, where ``R`` is a record object and ``C`` is one 122of the fields of the record type, yields the bit 123offset within the record contains the first bit of 124storage allocated for the object. The value of this attribute is of the 125type *universal_integer*. The value depends only on the field 126``C`` and is independent of the alignment of 127the containing record ``R``. 128 129Attribute Code_Address 130====================== 131.. index:: Code_Address 132.. index:: Subprogram address 133 134.. index:: Address of subprogram code 135 136The ``'Address`` 137attribute may be applied to subprograms in Ada 95 and Ada 2005, but the 138intended effect seems to be to provide 139an address value which can be used to call the subprogram by means of 140an address clause as in the following example: 141 142.. code-block:: ada 143 144 procedure K is ... 145 146 procedure L; 147 for L'Address use K'Address; 148 pragma Import (Ada, L); 149 150 151A call to ``L`` is then expected to result in a call to ``K``. 152In Ada 83, where there were no access-to-subprogram values, this was 153a common work-around for getting the effect of an indirect call. 154GNAT implements the above use of ``Address`` and the technique 155illustrated by the example code works correctly. 156 157However, for some purposes, it is useful to have the address of the start 158of the generated code for the subprogram. On some architectures, this is 159not necessarily the same as the ``Address`` value described above. 160For example, the ``Address`` value may reference a subprogram 161descriptor rather than the subprogram itself. 162 163The ``'Code_Address`` attribute, which can only be applied to 164subprogram entities, always returns the address of the start of the 165generated code of the specified subprogram, which may or may not be 166the same value as is returned by the corresponding ``'Address`` 167attribute. 168 169Attribute Compiler_Version 170========================== 171.. index:: Compiler_Version 172 173``Standard'Compiler_Version`` (``Standard`` is the only allowed 174prefix) yields a static string identifying the version of the compiler 175being used to compile the unit containing the attribute reference. 176 177Attribute Constrained 178===================== 179.. index:: Constrained 180 181In addition to the usage of this attribute in the Ada RM, GNAT 182also permits the use of the ``'Constrained`` attribute 183in a generic template 184for any type, including types without discriminants. The value of this 185attribute in the generic instance when applied to a scalar type or a 186record type without discriminants is always ``True``. This usage is 187compatible with older Ada compilers, including notably DEC Ada. 188 189 190Attribute Default_Bit_Order 191=========================== 192.. index:: Big endian 193 194.. index:: Little endian 195 196.. index:: Default_Bit_Order 197 198``Standard'Default_Bit_Order`` (``Standard`` is the only 199permissible prefix), provides the value ``System.Default_Bit_Order`` 200as a ``Pos`` value (0 for ``High_Order_First``, 1 for 201``Low_Order_First``). This is used to construct the definition of 202``Default_Bit_Order`` in package ``System``. 203 204Attribute Default_Scalar_Storage_Order 205====================================== 206.. index:: Big endian 207 208.. index:: Little endian 209 210.. index:: Default_Scalar_Storage_Order 211 212``Standard'Default_Scalar_Storage_Order`` (``Standard`` is the only 213permissible prefix), provides the current value of the default scalar storage 214order (as specified using pragma ``Default_Scalar_Storage_Order``, or 215equal to ``Default_Bit_Order`` if unspecified) as a 216``System.Bit_Order`` value. This is a static attribute. 217 218Attribute Deref 219=============== 220.. index:: Deref 221 222The attribute ``typ'Deref(expr)`` where ``expr`` is of type ``System.Address`` yields 223the variable of type ``typ`` that is located at the given address. It is similar 224to ``(totyp (expr).all)``, where ``totyp`` is an unchecked conversion from address to 225a named access-to-`typ` type, except that it yields a variable, so it can be 226used on the left side of an assignment. 227 228Attribute Descriptor_Size 229========================= 230.. index:: Descriptor 231 232.. index:: Dope vector 233 234.. index:: Descriptor_Size 235 236Nonstatic attribute ``Descriptor_Size`` returns the size in bits of the 237descriptor allocated for a type. The result is non-zero only for unconstrained 238array types and the returned value is of type universal integer. In GNAT, an 239array descriptor contains bounds information and is located immediately before 240the first element of the array. 241 242.. code-block:: ada 243 244 type Unconstr_Array is array (Positive range <>) of Boolean; 245 Put_Line ("Descriptor size = " & Unconstr_Array'Descriptor_Size'Img); 246 247 248The attribute takes into account any additional padding due to type alignment. 249In the example above, the descriptor contains two values of type 250``Positive`` representing the low and high bound. Since ``Positive`` has 251a size of 31 bits and an alignment of 4, the descriptor size is ``2 * Positive'Size + 2`` or 64 bits. 252 253Attribute Elaborated 254==================== 255.. index:: Elaborated 256 257The prefix of the ``'Elaborated`` attribute must be a unit name. The 258value is a Boolean which indicates whether or not the given unit has been 259elaborated. This attribute is primarily intended for internal use by the 260generated code for dynamic elaboration checking, but it can also be used 261in user programs. The value will always be True once elaboration of all 262units has been completed. An exception is for units which need no 263elaboration, the value is always False for such units. 264 265Attribute Elab_Body 266=================== 267.. index:: Elab_Body 268 269This attribute can only be applied to a program unit name. It returns 270the entity for the corresponding elaboration procedure for elaborating 271the body of the referenced unit. This is used in the main generated 272elaboration procedure by the binder and is not normally used in any 273other context. However, there may be specialized situations in which it 274is useful to be able to call this elaboration procedure from Ada code, 275e.g., if it is necessary to do selective re-elaboration to fix some 276error. 277 278Attribute Elab_Spec 279=================== 280.. index:: Elab_Spec 281 282This attribute can only be applied to a program unit name. It returns 283the entity for the corresponding elaboration procedure for elaborating 284the spec of the referenced unit. This is used in the main 285generated elaboration procedure by the binder and is not normally used 286in any other context. However, there may be specialized situations in 287which it is useful to be able to call this elaboration procedure from 288Ada code, e.g., if it is necessary to do selective re-elaboration to fix 289some error. 290 291Attribute Elab_Subp_Body 292======================== 293.. index:: Elab_Subp_Body 294 295This attribute can only be applied to a library level subprogram 296name and is only allowed in CodePeer mode. It returns the entity 297for the corresponding elaboration procedure for elaborating the body 298of the referenced subprogram unit. This is used in the main generated 299elaboration procedure by the binder in CodePeer mode only and is unrecognized 300otherwise. 301 302Attribute Emax 303============== 304.. index:: Ada 83 attributes 305 306.. index:: Emax 307 308The ``Emax`` attribute is provided for compatibility with Ada 83. See 309the Ada 83 reference manual for an exact description of the semantics of 310this attribute. 311 312Attribute Enabled 313================= 314.. index:: Enabled 315 316The ``Enabled`` attribute allows an application program to check at compile 317time to see if the designated check is currently enabled. The prefix is a 318simple identifier, referencing any predefined check name (other than 319``All_Checks``) or a check name introduced by pragma Check_Name. If 320no argument is given for the attribute, the check is for the general state 321of the check, if an argument is given, then it is an entity name, and the 322check indicates whether an ``Suppress`` or ``Unsuppress`` has been 323given naming the entity (if not, then the argument is ignored). 324 325Note that instantiations inherit the check status at the point of the 326instantiation, so a useful idiom is to have a library package that 327introduces a check name with ``pragma Check_Name``, and then contains 328generic packages or subprograms which use the ``Enabled`` attribute 329to see if the check is enabled. A user of this package can then issue 330a ``pragma Suppress`` or ``pragma Unsuppress`` before instantiating 331the package or subprogram, controlling whether the check will be present. 332 333Attribute Enum_Rep 334================== 335.. index:: Representation of enums 336 337.. index:: Enum_Rep 338 339For every enumeration subtype ``S``, ``S'Enum_Rep`` denotes a 340function with the following spec: 341 342.. code-block:: ada 343 344 function S'Enum_Rep (Arg : S'Base) return <Universal_Integer>; 345 346 347It is also allowable to apply ``Enum_Rep`` directly to an object of an 348enumeration type or to a non-overloaded enumeration 349literal. In this case ``S'Enum_Rep`` is equivalent to 350``typ'Enum_Rep(S)`` where ``typ`` is the type of the 351enumeration literal or object. 352 353The function returns the representation value for the given enumeration 354value. This will be equal to value of the ``Pos`` attribute in the 355absence of an enumeration representation clause. This is a static 356attribute (i.e.,:the result is static if the argument is static). 357 358``S'Enum_Rep`` can also be used with integer types and objects, 359in which case it simply returns the integer value. The reason for this 360is to allow it to be used for ``(<>)`` discrete formal arguments in 361a generic unit that can be instantiated with either enumeration types 362or integer types. Note that if ``Enum_Rep`` is used on a modular 363type whose upper bound exceeds the upper bound of the largest signed 364integer type, and the argument is a variable, so that the universal 365integer calculation is done at run time, then the call to ``Enum_Rep`` 366may raise ``Constraint_Error``. 367 368Attribute Enum_Val 369================== 370.. index:: Representation of enums 371 372.. index:: Enum_Val 373 374For every enumeration subtype ``S``, ``S'Enum_Val`` denotes a 375function with the following spec: 376 377.. code-block:: ada 378 379 function S'Enum_Val (Arg : <Universal_Integer>) return S'Base; 380 381 382The function returns the enumeration value whose representation matches the 383argument, or raises Constraint_Error if no enumeration literal of the type 384has the matching value. 385This will be equal to value of the ``Val`` attribute in the 386absence of an enumeration representation clause. This is a static 387attribute (i.e., the result is static if the argument is static). 388 389Attribute Epsilon 390================= 391.. index:: Ada 83 attributes 392 393.. index:: Epsilon 394 395The ``Epsilon`` attribute is provided for compatibility with Ada 83. See 396the Ada 83 reference manual for an exact description of the semantics of 397this attribute. 398 399Attribute Fast_Math 400=================== 401.. index:: Fast_Math 402 403``Standard'Fast_Math`` (``Standard`` is the only allowed 404prefix) yields a static Boolean value that is True if pragma 405``Fast_Math`` is active, and False otherwise. 406 407Attribute Finalization_Size 408=========================== 409.. index:: Finalization_Size 410 411The prefix of attribute ``Finalization_Size`` must be an object or 412a non-class-wide type. This attribute returns the size of any hidden data 413reserved by the compiler to handle finalization-related actions. The type of 414the attribute is *universal_integer*. 415 416``Finalization_Size`` yields a value of zero for a type with no controlled 417parts, an object whose type has no controlled parts, or an object of a 418class-wide type whose tag denotes a type with no controlled parts. 419 420Note that only heap-allocated objects contain finalization data. 421 422Attribute Fixed_Value 423===================== 424.. index:: Fixed_Value 425 426For every fixed-point type ``S``, ``S'Fixed_Value`` denotes a 427function with the following specification: 428 429.. code-block:: ada 430 431 function S'Fixed_Value (Arg : <Universal_Integer>) return S; 432 433The value returned is the fixed-point value ``V`` such that:: 434 435 V = Arg * S'Small 436 437 438The effect is thus similar to first converting the argument to the 439integer type used to represent ``S``, and then doing an unchecked 440conversion to the fixed-point type. The difference is 441that there are full range checks, to ensure that the result is in range. 442This attribute is primarily intended for use in implementation of the 443input-output functions for fixed-point values. 444 445Attribute From_Any 446================== 447.. index:: From_Any 448 449This internal attribute is used for the generation of remote subprogram 450stubs in the context of the Distributed Systems Annex. 451 452Attribute Has_Access_Values 453=========================== 454.. index:: Access values, testing for 455 456.. index:: Has_Access_Values 457 458The prefix of the ``Has_Access_Values`` attribute is a type. The result 459is a Boolean value which is True if the is an access type, or is a composite 460type with a component (at any nesting depth) that is an access type, and is 461False otherwise. 462The intended use of this attribute is in conjunction with generic 463definitions. If the attribute is applied to a generic private type, it 464indicates whether or not the corresponding actual type has access values. 465 466Attribute Has_Discriminants 467=========================== 468.. index:: Discriminants, testing for 469 470.. index:: Has_Discriminants 471 472The prefix of the ``Has_Discriminants`` attribute is a type. The result 473is a Boolean value which is True if the type has discriminants, and False 474otherwise. The intended use of this attribute is in conjunction with generic 475definitions. If the attribute is applied to a generic private type, it 476indicates whether or not the corresponding actual type has discriminants. 477 478Attribute Img 479============= 480.. index:: Img 481 482The ``Img`` attribute differs from ``Image`` in that it is applied 483directly to an object, and yields the same result as 484``Image`` for the subtype of the object. This is convenient for 485debugging: 486 487.. code-block:: ada 488 489 Put_Line ("X = " & X'Img); 490 491 492has the same meaning as the more verbose: 493 494.. code-block:: ada 495 496 Put_Line ("X = " & T'Image (X)); 497 498where ``T`` is the (sub)type of the object ``X``. 499 500Note that technically, in analogy to ``Image``, 501``X'Img`` returns a parameterless function 502that returns the appropriate string when called. This means that 503``X'Img`` can be renamed as a function-returning-string, or used 504in an instantiation as a function parameter. 505 506Attribute Integer_Value 507======================= 508.. index:: Integer_Value 509 510For every integer type ``S``, ``S'Integer_Value`` denotes a 511function with the following spec: 512 513.. code-block:: ada 514 515 function S'Integer_Value (Arg : <Universal_Fixed>) return S; 516 517The value returned is the integer value ``V``, such that:: 518 519 Arg = V * T'Small 520 521 522where ``T`` is the type of ``Arg``. 523The effect is thus similar to first doing an unchecked conversion from 524the fixed-point type to its corresponding implementation type, and then 525converting the result to the target integer type. The difference is 526that there are full range checks, to ensure that the result is in range. 527This attribute is primarily intended for use in implementation of the 528standard input-output functions for fixed-point values. 529 530Attribute Invalid_Value 531======================= 532.. index:: Invalid_Value 533 534For every scalar type S, S'Invalid_Value returns an undefined value of the 535type. If possible this value is an invalid representation for the type. The 536value returned is identical to the value used to initialize an otherwise 537uninitialized value of the type if pragma Initialize_Scalars is used, 538including the ability to modify the value with the binder -Sxx flag and 539relevant environment variables at run time. 540 541Attribute Iterable 542================== 543.. index:: Iterable 544 545Equivalent to Aspect Iterable. 546 547Attribute Large 548=============== 549.. index:: Ada 83 attributes 550 551.. index:: Large 552 553The ``Large`` attribute is provided for compatibility with Ada 83. See 554the Ada 83 reference manual for an exact description of the semantics of 555this attribute. 556 557Attribute Library_Level 558======================= 559.. index:: Library_Level 560 561``P'Library_Level``, where P is an entity name, 562returns a Boolean value which is True if the entity is declared 563at the library level, and False otherwise. Note that within a 564generic instantition, the name of the generic unit denotes the 565instance, which means that this attribute can be used to test 566if a generic is instantiated at the library level, as shown 567in this example: 568 569.. code-block:: ada 570 571 generic 572 ... 573 package Gen is 574 pragma Compile_Time_Error 575 (not Gen'Library_Level, 576 "Gen can only be instantiated at library level"); 577 ... 578 end Gen; 579 580 581Attribute Lock_Free 582=================== 583.. index:: Lock_Free 584 585``P'Lock_Free``, where P is a protected object, returns True if a 586pragma ``Lock_Free`` applies to P. 587 588Attribute Loop_Entry 589==================== 590.. index:: Loop_Entry 591 592Syntax:: 593 594 X'Loop_Entry [(loop_name)] 595 596 597The ``Loop_Entry`` attribute is used to refer to the value that an 598expression had upon entry to a given loop in much the same way that the 599``Old`` attribute in a subprogram postcondition can be used to refer 600to the value an expression had upon entry to the subprogram. The 601relevant loop is either identified by the given loop name, or it is the 602innermost enclosing loop when no loop name is given. 603 604A ``Loop_Entry`` attribute can only occur within a 605``Loop_Variant`` or ``Loop_Invariant`` pragma. A common use of 606``Loop_Entry`` is to compare the current value of objects with their 607initial value at loop entry, in a ``Loop_Invariant`` pragma. 608 609The effect of using ``X'Loop_Entry`` is the same as declaring 610a constant initialized with the initial value of ``X`` at loop 611entry. This copy is not performed if the loop is not entered, or if the 612corresponding pragmas are ignored or disabled. 613 614Attribute Machine_Size 615====================== 616.. index:: Machine_Size 617 618This attribute is identical to the ``Object_Size`` attribute. It is 619provided for compatibility with the DEC Ada 83 attribute of this name. 620 621Attribute Mantissa 622================== 623.. index:: Ada 83 attributes 624 625.. index:: Mantissa 626 627The ``Mantissa`` attribute is provided for compatibility with Ada 83. See 628the Ada 83 reference manual for an exact description of the semantics of 629this attribute. 630 631.. _Attribute_Maximum_Alignment: 632 633Attribute Maximum_Alignment 634=========================== 635.. index:: Alignment, maximum 636 637.. index:: Maximum_Alignment 638 639``Standard'Maximum_Alignment`` (``Standard`` is the only 640permissible prefix) provides the maximum useful alignment value for the 641target. This is a static value that can be used to specify the alignment 642for an object, guaranteeing that it is properly aligned in all 643cases. 644 645Attribute Mechanism_Code 646======================== 647.. index:: Return values, passing mechanism 648 649.. index:: Parameters, passing mechanism 650 651.. index:: Mechanism_Code 652 653``func'Mechanism_Code`` yields an integer code for the 654mechanism used for the result of function ``func``, and 655``subprog'Mechanism_Code (n)`` yields the mechanism 656used for formal parameter number *n* (a static integer value, with 1 657meaning the first parameter) of subprogram ``subprog``. The code returned is: 658 659 660 661*1* 662 by copy (value) 663 664*2* 665 by reference 666 667Attribute Null_Parameter 668======================== 669.. index:: Zero address, passing 670 671.. index:: Null_Parameter 672 673A reference ``T'Null_Parameter`` denotes an imaginary object of 674type or subtype ``T`` allocated at machine address zero. The attribute 675is allowed only as the default expression of a formal parameter, or as 676an actual expression of a subprogram call. In either case, the 677subprogram must be imported. 678 679The identity of the object is represented by the address zero in the 680argument list, independent of the passing mechanism (explicit or 681default). 682 683This capability is needed to specify that a zero address should be 684passed for a record or other composite object passed by reference. 685There is no way of indicating this without the ``Null_Parameter`` 686attribute. 687 688.. _Attribute-Object_Size: 689 690Attribute Object_Size 691===================== 692.. index:: Size, used for objects 693 694.. index:: Object_Size 695 696The size of an object is not necessarily the same as the size of the type 697of an object. This is because by default object sizes are increased to be 698a multiple of the alignment of the object. For example, 699``Natural'Size`` is 70031, but by default objects of type ``Natural`` will have a size of 32 bits. 701Similarly, a record containing an integer and a character: 702 703.. code-block:: ada 704 705 type Rec is record 706 I : Integer; 707 C : Character; 708 end record; 709 710 711will have a size of 40 (that is ``Rec'Size`` will be 40). The 712alignment will be 4, because of the 713integer field, and so the default size of record objects for this type 714will be 64 (8 bytes). 715 716If the alignment of the above record is specified to be 1, then the 717object size will be 40 (5 bytes). This is true by default, and also 718an object size of 40 can be explicitly specified in this case. 719 720A consequence of this capability is that different object sizes can be 721given to subtypes that would otherwise be considered in Ada to be 722statically matching. But it makes no sense to consider such subtypes 723as statically matching. Consequently, GNAT adds a rule 724to the static matching rules that requires object sizes to match. 725Consider this example: 726 727.. code-block:: ada 728 729 1. procedure BadAVConvert is 730 2. type R is new Integer; 731 3. subtype R1 is R range 1 .. 10; 732 4. subtype R2 is R range 1 .. 10; 733 5. for R1'Object_Size use 8; 734 6. for R2'Object_Size use 16; 735 7. type R1P is access all R1; 736 8. type R2P is access all R2; 737 9. R1PV : R1P := new R1'(4); 738 10. R2PV : R2P; 739 11. begin 740 12. R2PV := R2P (R1PV); 741 | 742 >>> target designated subtype not compatible with 743 type "R1" defined at line 3 744 745 13. end; 746 747 748In the absence of lines 5 and 6, 749types ``R1`` and ``R2`` statically match and 750hence the conversion on line 12 is legal. But since lines 5 and 6 751cause the object sizes to differ, GNAT considers that types 752``R1`` and ``R2`` are not statically matching, and line 12 753generates the diagnostic shown above. 754 755Similar additional checks are performed in other contexts requiring 756statically matching subtypes. 757 758Attribute Old 759============= 760.. index:: Old 761 762In addition to the usage of ``Old`` defined in the Ada 2012 RM (usage 763within ``Post`` aspect), GNAT also permits the use of this attribute 764in implementation defined pragmas ``Postcondition``, 765``Contract_Cases`` and ``Test_Case``. Also usages of 766``Old`` which would be illegal according to the Ada 2012 RM 767definition are allowed under control of 768implementation defined pragma ``Unevaluated_Use_Of_Old``. 769 770Attribute Passed_By_Reference 771============================= 772.. index:: Parameters, when passed by reference 773 774.. index:: Passed_By_Reference 775 776``typ'Passed_By_Reference`` for any subtype `typ` returns 777a value of type ``Boolean`` value that is ``True`` if the type is 778normally passed by reference and ``False`` if the type is normally 779passed by copy in calls. For scalar types, the result is always ``False`` 780and is static. For non-scalar types, the result is nonstatic. 781 782Attribute Pool_Address 783====================== 784.. index:: Parameters, when passed by reference 785 786.. index:: Pool_Address 787 788``X'Pool_Address`` for any object ``X`` returns the address 789of X within its storage pool. This is the same as 790``X'Address``, except that for an unconstrained array whose 791bounds are allocated just before the first component, 792``X'Pool_Address`` returns the address of those bounds, 793whereas ``X'Address`` returns the address of the first 794component. 795 796Here, we are interpreting 'storage pool' broadly to mean 797``wherever the object is allocated``, which could be a 798user-defined storage pool, 799the global heap, on the stack, or in a static memory area. 800For an object created by ``new``, ``Ptr.all'Pool_Address`` is 801what is passed to ``Allocate`` and returned from ``Deallocate``. 802 803Attribute Range_Length 804====================== 805.. index:: Range_Length 806 807``typ'Range_Length`` for any discrete type `typ` yields 808the number of values represented by the subtype (zero for a null 809range). The result is static for static subtypes. ``Range_Length`` 810applied to the index subtype of a one dimensional array always gives the 811same result as ``Length`` applied to the array itself. 812 813Attribute Restriction_Set 814========================= 815.. index:: Restriction_Set 816.. index:: Restrictions 817 818This attribute allows compile time testing of restrictions that 819are currently in effect. It is primarily intended for specializing 820code in the run-time based on restrictions that are active (e.g. 821don't need to save fpt registers if restriction No_Floating_Point 822is known to be in effect), but can be used anywhere. 823 824There are two forms: 825 826.. code-block:: ada 827 828 System'Restriction_Set (partition_boolean_restriction_NAME) 829 System'Restriction_Set (No_Dependence => library_unit_NAME); 830 831 832In the case of the first form, the only restriction names 833allowed are parameterless restrictions that are checked 834for consistency at bind time. For a complete list see the 835subtype ``System.Rident.Partition_Boolean_Restrictions``. 836 837The result returned is True if the restriction is known to 838be in effect, and False if the restriction is known not to 839be in effect. An important guarantee is that the value of 840a Restriction_Set attribute is known to be consistent throughout 841all the code of a partition. 842 843This is trivially achieved if the entire partition is compiled 844with a consistent set of restriction pragmas. However, the 845compilation model does not require this. It is possible to 846compile one set of units with one set of pragmas, and another 847set of units with another set of pragmas. It is even possible 848to compile a spec with one set of pragmas, and then WITH the 849same spec with a different set of pragmas. Inconsistencies 850in the actual use of the restriction are checked at bind time. 851 852In order to achieve the guarantee of consistency for the 853Restriction_Set pragma, we consider that a use of the pragma 854that yields False is equivalent to a violation of the 855restriction. 856 857So for example if you write 858 859.. code-block:: ada 860 861 if System'Restriction_Set (No_Floating_Point) then 862 ... 863 else 864 ... 865 end if; 866 867 868And the result is False, so that the else branch is executed, 869you can assume that this restriction is not set for any unit 870in the partition. This is checked by considering this use of 871the restriction pragma to be a violation of the restriction 872No_Floating_Point. This means that no other unit can attempt 873to set this restriction (if some unit does attempt to set it, 874the binder will refuse to bind the partition). 875 876Technical note: The restriction name and the unit name are 877intepreted entirely syntactically, as in the corresponding 878Restrictions pragma, they are not analyzed semantically, 879so they do not have a type. 880 881Attribute Result 882================ 883.. index:: Result 884 885``function'Result`` can only be used with in a Postcondition pragma 886for a function. The prefix must be the name of the corresponding function. This 887is used to refer to the result of the function in the postcondition expression. 888For a further discussion of the use of this attribute and examples of its use, 889see the description of pragma Postcondition. 890 891Attribute Safe_Emax 892=================== 893.. index:: Ada 83 attributes 894 895.. index:: Safe_Emax 896 897The ``Safe_Emax`` attribute is provided for compatibility with Ada 83. See 898the Ada 83 reference manual for an exact description of the semantics of 899this attribute. 900 901Attribute Safe_Large 902==================== 903.. index:: Ada 83 attributes 904 905.. index:: Safe_Large 906 907The ``Safe_Large`` attribute is provided for compatibility with Ada 83. See 908the Ada 83 reference manual for an exact description of the semantics of 909this attribute. 910 911Attribute Safe_Small 912==================== 913.. index:: Ada 83 attributes 914 915.. index:: Safe_Small 916 917The ``Safe_Small`` attribute is provided for compatibility with Ada 83. See 918the Ada 83 reference manual for an exact description of the semantics of 919this attribute. 920 921.. _Attribute-Scalar_Storage_Order: 922 923Attribute Scalar_Storage_Order 924============================== 925.. index:: Endianness 926 927.. index:: Scalar storage order 928 929.. index:: Scalar_Storage_Order 930 931For every array or record type ``S``, the representation attribute 932``Scalar_Storage_Order`` denotes the order in which storage elements 933that make up scalar components are ordered within S. The value given must 934be a static expression of type System.Bit_Order. The following is an example 935of the use of this feature: 936 937.. code-block:: ada 938 939 -- Component type definitions 940 941 subtype Yr_Type is Natural range 0 .. 127; 942 subtype Mo_Type is Natural range 1 .. 12; 943 subtype Da_Type is Natural range 1 .. 31; 944 945 -- Record declaration 946 947 type Date is record 948 Years_Since_1980 : Yr_Type; 949 Month : Mo_Type; 950 Day_Of_Month : Da_Type; 951 end record; 952 953 -- Record representation clause 954 955 for Date use record 956 Years_Since_1980 at 0 range 0 .. 6; 957 Month at 0 range 7 .. 10; 958 Day_Of_Month at 0 range 11 .. 15; 959 end record; 960 961 -- Attribute definition clauses 962 963 for Date'Bit_Order use System.High_Order_First; 964 for Date'Scalar_Storage_Order use System.High_Order_First; 965 -- If Scalar_Storage_Order is specified, it must be consistent with 966 -- Bit_Order, so it's best to always define the latter explicitly if 967 -- the former is used. 968 969 970Other properties are as for standard representation attribute ``Bit_Order``, 971as defined by Ada RM 13.5.3(4). The default is ``System.Default_Bit_Order``. 972 973For a record type ``T``, if ``T'Scalar_Storage_Order`` is 974specified explicitly, it shall be equal to ``T'Bit_Order``. Note: 975this means that if a ``Scalar_Storage_Order`` attribute definition 976clause is not confirming, then the type's ``Bit_Order`` shall be 977specified explicitly and set to the same value. 978 979Derived types inherit an explicitly set scalar storage order from their parent 980types. This may be overridden for the derived type by giving an explicit scalar 981storage order for the derived type. For a record extension, the derived type 982must have the same scalar storage order as the parent type. 983 984A component of a record type that is itself a record or an array and that does 985not start and end on a byte boundary must have have the same scalar storage 986order as the record type. A component of a bit-packed array type that is itself 987a record or an array must have the same scalar storage order as the array type. 988 989No component of a type that has an explicit ``Scalar_Storage_Order`` 990attribute definition may be aliased. 991 992A confirming ``Scalar_Storage_Order`` attribute definition clause (i.e. 993with a value equal to ``System.Default_Bit_Order``) has no effect. 994 995If the opposite storage order is specified, then whenever the value of 996a scalar component of an object of type ``S`` is read, the storage 997elements of the enclosing machine scalar are first reversed (before 998retrieving the component value, possibly applying some shift and mask 999operatings on the enclosing machine scalar), and the opposite operation 1000is done for writes. 1001 1002In that case, the restrictions set forth in 13.5.1(10.3/2) for scalar components 1003are relaxed. Instead, the following rules apply: 1004 1005* the underlying storage elements are those at positions 1006 ``(position + first_bit / storage_element_size) .. (position + (last_bit + storage_element_size - 1) / storage_element_size)`` 1007* the sequence of underlying storage elements shall have 1008 a size no greater than the largest machine scalar 1009* the enclosing machine scalar is defined as the smallest machine 1010 scalar starting at a position no greater than 1011 ``position + first_bit / storage_element_size`` and covering 1012 storage elements at least up to ``position + (last_bit + storage_element_size - 1) / storage_element_size``` 1013* the position of the component is interpreted relative to that machine 1014 scalar. 1015 1016If no scalar storage order is specified for a type (either directly, or by 1017inheritance in the case of a derived type), then the default is normally 1018the native ordering of the target, but this default can be overridden using 1019pragma ``Default_Scalar_Storage_Order``. 1020 1021Note that if a component of ``T`` is itself of a record or array type, 1022the specfied ``Scalar_Storage_Order`` does *not* apply to that nested type: 1023an explicit attribute definition clause must be provided for the component 1024type as well if desired. 1025 1026Note that the scalar storage order only affects the in-memory data 1027representation. It has no effect on the representation used by stream 1028attributes. 1029 1030.. _Attribute_Simple_Storage_Pool: 1031 1032Attribute Simple_Storage_Pool 1033============================= 1034.. index:: Storage pool, simple 1035 1036.. index:: Simple storage pool 1037 1038.. index:: Simple_Storage_Pool 1039 1040For every nonformal, nonderived access-to-object type ``Acc``, the 1041representation attribute ``Simple_Storage_Pool`` may be specified 1042via an attribute_definition_clause (or by specifying the equivalent aspect): 1043 1044.. code-block:: ada 1045 1046 My_Pool : My_Simple_Storage_Pool_Type; 1047 1048 type Acc is access My_Data_Type; 1049 1050 for Acc'Simple_Storage_Pool use My_Pool; 1051 1052 1053 1054The name given in an attribute_definition_clause for the 1055``Simple_Storage_Pool`` attribute shall denote a variable of 1056a 'simple storage pool type' (see pragma `Simple_Storage_Pool_Type`). 1057 1058The use of this attribute is only allowed for a prefix denoting a type 1059for which it has been specified. The type of the attribute is the type 1060of the variable specified as the simple storage pool of the access type, 1061and the attribute denotes that variable. 1062 1063It is illegal to specify both ``Storage_Pool`` and ``Simple_Storage_Pool`` 1064for the same access type. 1065 1066If the ``Simple_Storage_Pool`` attribute has been specified for an access 1067type, then applying the ``Storage_Pool`` attribute to the type is flagged 1068with a warning and its evaluation raises the exception ``Program_Error``. 1069 1070If the Simple_Storage_Pool attribute has been specified for an access 1071type ``S``, then the evaluation of the attribute ``S'Storage_Size`` 1072returns the result of calling ``Storage_Size (S'Simple_Storage_Pool)``, 1073which is intended to indicate the number of storage elements reserved for 1074the simple storage pool. If the Storage_Size function has not been defined 1075for the simple storage pool type, then this attribute returns zero. 1076 1077If an access type ``S`` has a specified simple storage pool of type 1078``SSP``, then the evaluation of an allocator for that access type calls 1079the primitive ``Allocate`` procedure for type ``SSP``, passing 1080``S'Simple_Storage_Pool`` as the pool parameter. The detailed 1081semantics of such allocators is the same as those defined for allocators 1082in section 13.11 of the :title:`Ada Reference Manual`, with the term 1083*simple storage pool* substituted for *storage pool*. 1084 1085If an access type ``S`` has a specified simple storage pool of type 1086``SSP``, then a call to an instance of the ``Ada.Unchecked_Deallocation`` 1087for that access type invokes the primitive ``Deallocate`` procedure 1088for type ``SSP``, passing ``S'Simple_Storage_Pool`` as the pool 1089parameter. The detailed semantics of such unchecked deallocations is the same 1090as defined in section 13.11.2 of the Ada Reference Manual, except that the 1091term *simple storage pool* is substituted for *storage pool*. 1092 1093Attribute Small 1094=============== 1095.. index:: Ada 83 attributes 1096 1097.. index:: Small 1098 1099The ``Small`` attribute is defined in Ada 95 (and Ada 2005) only for 1100fixed-point types. 1101GNAT also allows this attribute to be applied to floating-point types 1102for compatibility with Ada 83. See 1103the Ada 83 reference manual for an exact description of the semantics of 1104this attribute when applied to floating-point types. 1105 1106Attribute Storage_Unit 1107====================== 1108.. index:: Storage_Unit 1109 1110``Standard'Storage_Unit`` (``Standard`` is the only permissible 1111prefix) provides the same value as ``System.Storage_Unit``. 1112 1113Attribute Stub_Type 1114=================== 1115.. index:: Stub_Type 1116 1117The GNAT implementation of remote access-to-classwide types is 1118organized as described in AARM section E.4 (20.t): a value of an RACW type 1119(designating a remote object) is represented as a normal access 1120value, pointing to a "stub" object which in turn contains the 1121necessary information to contact the designated remote object. A 1122call on any dispatching operation of such a stub object does the 1123remote call, if necessary, using the information in the stub object 1124to locate the target partition, etc. 1125 1126For a prefix ``T`` that denotes a remote access-to-classwide type, 1127``T'Stub_Type`` denotes the type of the corresponding stub objects. 1128 1129By construction, the layout of ``T'Stub_Type`` is identical to that of 1130type ``RACW_Stub_Type`` declared in the internal implementation-defined 1131unit ``System.Partition_Interface``. Use of this attribute will create 1132an implicit dependency on this unit. 1133 1134Attribute System_Allocator_Alignment 1135==================================== 1136.. index:: Alignment, allocator 1137 1138.. index:: System_Allocator_Alignment 1139 1140``Standard'System_Allocator_Alignment`` (``Standard`` is the only 1141permissible prefix) provides the observable guaranted to be honored by 1142the system allocator (malloc). This is a static value that can be used 1143in user storage pools based on malloc either to reject allocation 1144with alignment too large or to enable a realignment circuitry if the 1145alignment request is larger than this value. 1146 1147Attribute Target_Name 1148===================== 1149.. index:: Target_Name 1150 1151``Standard'Target_Name`` (``Standard`` is the only permissible 1152prefix) provides a static string value that identifies the target 1153for the current compilation. For GCC implementations, this is the 1154standard gcc target name without the terminating slash (for 1155example, GNAT 5.0 on windows yields "i586-pc-mingw32msv"). 1156 1157Attribute To_Address 1158==================== 1159.. index:: To_Address 1160 1161The ``System'To_Address`` 1162(``System`` is the only permissible prefix) 1163denotes a function identical to 1164``System.Storage_Elements.To_Address`` except that 1165it is a static attribute. This means that if its argument is 1166a static expression, then the result of the attribute is a 1167static expression. This means that such an expression can be 1168used in contexts (e.g., preelaborable packages) which require a 1169static expression and where the function call could not be used 1170(since the function call is always nonstatic, even if its 1171argument is static). The argument must be in the range 1172-(2**(m-1)) .. 2**m-1, where m is the memory size 1173(typically 32 or 64). Negative values are intepreted in a 1174modular manner (e.g., -1 means the same as 16#FFFF_FFFF# on 1175a 32 bits machine). 1176 1177Attribute To_Any 1178================ 1179.. index:: To_Any 1180 1181This internal attribute is used for the generation of remote subprogram 1182stubs in the context of the Distributed Systems Annex. 1183 1184Attribute Type_Class 1185==================== 1186.. index:: Type_Class 1187 1188``typ'Type_Class`` for any type or subtype `typ` yields 1189the value of the type class for the full type of `typ`. If 1190`typ` is a generic formal type, the value is the value for the 1191corresponding actual subtype. The value of this attribute is of type 1192``System.Aux_DEC.Type_Class``, which has the following definition: 1193 1194.. code-block:: ada 1195 1196 type Type_Class is 1197 (Type_Class_Enumeration, 1198 Type_Class_Integer, 1199 Type_Class_Fixed_Point, 1200 Type_Class_Floating_Point, 1201 Type_Class_Array, 1202 Type_Class_Record, 1203 Type_Class_Access, 1204 Type_Class_Task, 1205 Type_Class_Address); 1206 1207 1208Protected types yield the value ``Type_Class_Task``, which thus 1209applies to all concurrent types. This attribute is designed to 1210be compatible with the DEC Ada 83 attribute of the same name. 1211 1212Attribute Type_Key 1213================== 1214.. index:: Type_Key 1215 1216The ``Type_Key`` attribute is applicable to a type or subtype and 1217yields a value of type Standard.String containing encoded information 1218about the type or subtype. This provides improved compatibility with 1219other implementations that support this attribute. 1220 1221Attribute TypeCode 1222================== 1223.. index:: TypeCode 1224 1225This internal attribute is used for the generation of remote subprogram 1226stubs in the context of the Distributed Systems Annex. 1227 1228Attribute Unconstrained_Array 1229============================= 1230.. index:: Unconstrained_Array 1231 1232The ``Unconstrained_Array`` attribute can be used with a prefix that 1233denotes any type or subtype. It is a static attribute that yields 1234``True`` if the prefix designates an unconstrained array, 1235and ``False`` otherwise. In a generic instance, the result is 1236still static, and yields the result of applying this test to the 1237generic actual. 1238 1239Attribute Universal_Literal_String 1240================================== 1241.. index:: Named numbers, representation of 1242 1243.. index:: Universal_Literal_String 1244 1245The prefix of ``Universal_Literal_String`` must be a named 1246number. The static result is the string consisting of the characters of 1247the number as defined in the original source. This allows the user 1248program to access the actual text of named numbers without intermediate 1249conversions and without the need to enclose the strings in quotes (which 1250would preclude their use as numbers). 1251 1252For example, the following program prints the first 50 digits of pi: 1253 1254.. code-block:: ada 1255 1256 with Text_IO; use Text_IO; 1257 with Ada.Numerics; 1258 procedure Pi is 1259 begin 1260 Put (Ada.Numerics.Pi'Universal_Literal_String); 1261 end; 1262 1263 1264Attribute Unrestricted_Access 1265============================= 1266.. index:: Access, unrestricted 1267 1268.. index:: Unrestricted_Access 1269 1270The ``Unrestricted_Access`` attribute is similar to ``Access`` 1271except that all accessibility and aliased view checks are omitted. This 1272is a user-beware attribute. 1273 1274For objects, it is similar to ``Address``, for which it is a 1275desirable replacement where the value desired is an access type. 1276In other words, its effect is similar to first applying the 1277``Address`` attribute and then doing an unchecked conversion to a 1278desired access type. 1279 1280For subprograms, ``P'Unrestricted_Access`` may be used where 1281``P'Access`` would be illegal, to construct a value of a 1282less-nested named access type that designates a more-nested 1283subprogram. This value may be used in indirect calls, so long as the 1284more-nested subprogram still exists; once the subprogram containing it 1285has returned, such calls are erroneous. For example: 1286 1287.. code-block:: ada 1288 1289 package body P is 1290 1291 type Less_Nested is not null access procedure; 1292 Global : Less_Nested; 1293 1294 procedure P1 is 1295 begin 1296 Global.all; 1297 end P1; 1298 1299 procedure P2 is 1300 Local_Var : Integer; 1301 1302 procedure More_Nested is 1303 begin 1304 ... Local_Var ... 1305 end More_Nested; 1306 begin 1307 Global := More_Nested'Unrestricted_Access; 1308 P1; 1309 end P2; 1310 1311 end P; 1312 1313 1314When P1 is called from P2, the call via Global is OK, but if P1 were 1315called after P2 returns, it would be an erroneous use of a dangling 1316pointer. 1317 1318For objects, it is possible to use ``Unrestricted_Access`` for any 1319type. However, if the result is of an access-to-unconstrained array 1320subtype, then the resulting pointer has the same scope as the context 1321of the attribute, and must not be returned to some enclosing scope. 1322For instance, if a function uses ``Unrestricted_Access`` to create 1323an access-to-unconstrained-array and returns that value to the caller, 1324the result will involve dangling pointers. In addition, it is only 1325valid to create pointers to unconstrained arrays using this attribute 1326if the pointer has the normal default 'fat' representation where a 1327pointer has two components, one points to the array and one points to 1328the bounds. If a size clause is used to force 'thin' representation 1329for a pointer to unconstrained where there is only space for a single 1330pointer, then the resulting pointer is not usable. 1331 1332In the simple case where a direct use of Unrestricted_Access attempts 1333to make a thin pointer for a non-aliased object, the compiler will 1334reject the use as illegal, as shown in the following example: 1335 1336.. code-block:: ada 1337 1338 with System; use System; 1339 procedure SliceUA2 is 1340 type A is access all String; 1341 for A'Size use Standard'Address_Size; 1342 1343 procedure P (Arg : A) is 1344 begin 1345 null; 1346 end P; 1347 1348 X : String := "hello world!"; 1349 X2 : aliased String := "hello world!"; 1350 1351 AV : A := X'Unrestricted_Access; -- ERROR 1352 | 1353 >>> illegal use of Unrestricted_Access attribute 1354 >>> attempt to generate thin pointer to unaliased object 1355 1356 begin 1357 P (X'Unrestricted_Access); -- ERROR 1358 | 1359 >>> illegal use of Unrestricted_Access attribute 1360 >>> attempt to generate thin pointer to unaliased object 1361 1362 P (X(7 .. 12)'Unrestricted_Access); -- ERROR 1363 | 1364 >>> illegal use of Unrestricted_Access attribute 1365 >>> attempt to generate thin pointer to unaliased object 1366 1367 P (X2'Unrestricted_Access); -- OK 1368 end; 1369 1370 1371but other cases cannot be detected by the compiler, and are 1372considered to be erroneous. Consider the following example: 1373 1374.. code-block:: ada 1375 1376 with System; use System; 1377 with System; use System; 1378 procedure SliceUA is 1379 type AF is access all String; 1380 1381 type A is access all String; 1382 for A'Size use Standard'Address_Size; 1383 1384 procedure P (Arg : A) is 1385 begin 1386 if Arg'Length /= 6 then 1387 raise Program_Error; 1388 end if; 1389 end P; 1390 1391 X : String := "hello world!"; 1392 Y : AF := X (7 .. 12)'Unrestricted_Access; 1393 1394 begin 1395 P (A (Y)); 1396 end; 1397 1398 1399A normal unconstrained array value 1400or a constrained array object marked as aliased has the bounds in memory 1401just before the array, so a thin pointer can retrieve both the data and 1402the bounds. But in this case, the non-aliased object ``X`` does not have the 1403bounds before the string. If the size clause for type ``A`` 1404were not present, then the pointer 1405would be a fat pointer, where one component is a pointer to the bounds, 1406and all would be well. But with the size clause present, the conversion from 1407fat pointer to thin pointer in the call loses the bounds, and so this 1408is erroneous, and the program likely raises a ``Program_Error`` exception. 1409 1410In general, it is advisable to completely 1411avoid mixing the use of thin pointers and the use of 1412``Unrestricted_Access`` where the designated type is an 1413unconstrained array. The use of thin pointers should be restricted to 1414cases of porting legacy code that implicitly assumes the size of pointers, 1415and such code should not in any case be using this attribute. 1416 1417Another erroneous situation arises if the attribute is 1418applied to a constant. The resulting pointer can be used to access the 1419constant, but the effect of trying to modify a constant in this manner 1420is not well-defined. Consider this example: 1421 1422.. code-block:: ada 1423 1424 P : constant Integer := 4; 1425 type R is access all Integer; 1426 RV : R := P'Unrestricted_Access; 1427 .. 1428 RV.all := 3; 1429 1430 1431Here we attempt to modify the constant P from 4 to 3, but the compiler may 1432or may not notice this attempt, and subsequent references to P may yield 1433either the value 3 or the value 4 or the assignment may blow up if the 1434compiler decides to put P in read-only memory. One particular case where 1435``Unrestricted_Access`` can be used in this way is to modify the 1436value of an ``in`` parameter: 1437 1438.. code-block:: ada 1439 1440 procedure K (S : in String) is 1441 type R is access all Character; 1442 RV : R := S (3)'Unrestricted_Access; 1443 begin 1444 RV.all := 'a'; 1445 end; 1446 1447 1448In general this is a risky approach. It may appear to "work" but such uses of 1449``Unrestricted_Access`` are potentially non-portable, even from one version 1450of GNAT to another, so are best avoided if possible. 1451 1452Attribute Update 1453================ 1454.. index:: Update 1455 1456The ``Update`` attribute creates a copy of an array or record value 1457with one or more modified components. The syntax is:: 1458 1459 PREFIX'Update ( RECORD_COMPONENT_ASSOCIATION_LIST ) 1460 PREFIX'Update ( ARRAY_COMPONENT_ASSOCIATION {, ARRAY_COMPONENT_ASSOCIATION } ) 1461 PREFIX'Update ( MULTIDIMENSIONAL_ARRAY_COMPONENT_ASSOCIATION 1462 {, MULTIDIMENSIONAL_ARRAY_COMPONENT_ASSOCIATION } ) 1463 1464 MULTIDIMENSIONAL_ARRAY_COMPONENT_ASSOCIATION ::= INDEX_EXPRESSION_LIST_LIST => EXPRESSION 1465 INDEX_EXPRESSION_LIST_LIST ::= INDEX_EXPRESSION_LIST {| INDEX_EXPRESSION_LIST } 1466 INDEX_EXPRESSION_LIST ::= ( EXPRESSION {, EXPRESSION } ) 1467 1468 1469where ``PREFIX`` is the name of an array or record object, the 1470association list in parentheses does not contain an ``others`` 1471choice and the box symbol ``<>`` may not appear in any 1472expression. The effect is to yield a copy of the array or record value 1473which is unchanged apart from the components mentioned in the 1474association list, which are changed to the indicated value. The 1475original value of the array or record value is not affected. For 1476example: 1477 1478.. code-block:: ada 1479 1480 type Arr is Array (1 .. 5) of Integer; 1481 ... 1482 Avar1 : Arr := (1,2,3,4,5); 1483 Avar2 : Arr := Avar1'Update (2 => 10, 3 .. 4 => 20); 1484 1485 1486yields a value for ``Avar2`` of 1,10,20,20,5 with ``Avar1`` 1487begin unmodified. Similarly: 1488 1489.. code-block:: ada 1490 1491 type Rec is A, B, C : Integer; 1492 ... 1493 Rvar1 : Rec := (A => 1, B => 2, C => 3); 1494 Rvar2 : Rec := Rvar1'Update (B => 20); 1495 1496 1497yields a value for ``Rvar2`` of (A => 1, B => 20, C => 3), 1498with ``Rvar1`` being unmodifed. 1499Note that the value of the attribute reference is computed 1500completely before it is used. This means that if you write: 1501 1502.. code-block:: ada 1503 1504 Avar1 := Avar1'Update (1 => 10, 2 => Function_Call); 1505 1506 1507then the value of ``Avar1`` is not modified if ``Function_Call`` 1508raises an exception, unlike the effect of a series of direct assignments 1509to elements of ``Avar1``. In general this requires that 1510two extra complete copies of the object are required, which should be 1511kept in mind when considering efficiency. 1512 1513The ``Update`` attribute cannot be applied to prefixes of a limited 1514type, and cannot reference discriminants in the case of a record type. 1515The accessibility level of an Update attribute result object is defined 1516as for an aggregate. 1517 1518In the record case, no component can be mentioned more than once. In 1519the array case, two overlapping ranges can appear in the association list, 1520in which case the modifications are processed left to right. 1521 1522Multi-dimensional arrays can be modified, as shown by this example: 1523 1524.. code-block:: ada 1525 1526 A : array (1 .. 10, 1 .. 10) of Integer; 1527 .. 1528 A := A'Update ((1, 2) => 20, (3, 4) => 30); 1529 1530 1531which changes element (1,2) to 20 and (3,4) to 30. 1532 1533Attribute Valid_Scalars 1534======================= 1535.. index:: Valid_Scalars 1536 1537The ``'Valid_Scalars`` attribute is intended to make it easier to 1538check the validity of scalar subcomponents of composite objects. It 1539is defined for any prefix ``X`` that denotes an object. 1540The value of this attribute is of the predefined type Boolean. 1541``X'Valid_Scalars`` yields True if and only if evaluation of 1542``P'Valid`` yields True for every scalar part P of X or if X has 1543no scalar parts. It is not specified in what order the scalar parts 1544are checked, nor whether any more are checked after any one of them 1545is determined to be invalid. If the prefix ``X`` is of a class-wide 1546type ``T'Class`` (where ``T`` is the associated specific type), 1547or if the prefix ``X`` is of a specific tagged type ``T``, then 1548only the scalar parts of components of ``T`` are traversed; in other 1549words, components of extensions of ``T`` are not traversed even if 1550``T'Class (X)'Tag /= T'Tag`` . The compiler will issue a warning if it can 1551be determined at compile time that the prefix of the attribute has no 1552scalar parts (e.g., if the prefix is of an access type, an interface type, 1553an undiscriminated task type, or an undiscriminated protected type). 1554 1555For scalar types, ``Valid_Scalars`` is equivalent to ``Valid``. The use 1556of this attribute is not permitted for ``Unchecked_Union`` types for which 1557in general it is not possible to determine the values of the discriminants. 1558 1559Note: ``Valid_Scalars`` can generate a lot of code, especially in the case 1560of a large variant record. If the attribute is called in many places in the 1561same program applied to objects of the same type, it can reduce program size 1562to write a function with a single use of the attribute, and then call that 1563function from multiple places. 1564 1565Attribute VADS_Size 1566=================== 1567.. index:: Size, VADS compatibility 1568 1569.. index:: VADS_Size 1570 1571The ``'VADS_Size`` attribute is intended to make it easier to port 1572legacy code which relies on the semantics of ``'Size`` as implemented 1573by the VADS Ada 83 compiler. GNAT makes a best effort at duplicating the 1574same semantic interpretation. In particular, ``'VADS_Size`` applied 1575to a predefined or other primitive type with no Size clause yields the 1576Object_Size (for example, ``Natural'Size`` is 32 rather than 31 on 1577typical machines). In addition ``'VADS_Size`` applied to an object 1578gives the result that would be obtained by applying the attribute to 1579the corresponding type. 1580 1581.. _Attribute-Value_Size: 1582 1583Attribute Value_Size 1584==================== 1585.. index:: Size, setting for not-first subtype 1586 1587.. index:: Value_Size 1588 1589``type'Value_Size`` is the number of bits required to represent 1590a value of the given subtype. It is the same as ``type'Size``, 1591but, unlike ``Size``, may be set for non-first subtypes. 1592 1593Attribute Wchar_T_Size 1594====================== 1595.. index:: Wchar_T_Size 1596 1597``Standard'Wchar_T_Size`` (``Standard`` is the only permissible 1598prefix) provides the size in bits of the C ``wchar_t`` type 1599primarily for constructing the definition of this type in 1600package ``Interfaces.C``. The result is a static constant. 1601 1602Attribute Word_Size 1603=================== 1604.. index:: Word_Size 1605 1606``Standard'Word_Size`` (``Standard`` is the only permissible 1607prefix) provides the value ``System.Word_Size``. The result is 1608a static constant. 1609 1610