Debian Codegraph @

gcc/ada/doc/gnat_rm/implementation_defined_attributes.rst

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