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 instantition, 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 Lock_Free
610 ===================
611 .. index:: Lock_Free
612
613 ``P'Lock_Free``, where P is a protected object, returns True if a
614 pragma ``Lock_Free`` applies to P.
615
616 Attribute Loop_Entry
617 ====================
618 .. index:: Loop_Entry
619
620 Syntax::
621
622 X'Loop_Entry [(loop_name)]
623
624
625 The ``Loop_Entry`` attribute is used to refer to the value that an
626 expression had upon entry to a given loop in much the same way that the
627 ``Old`` attribute in a subprogram postcondition can be used to refer
628 to the value an expression had upon entry to the subprogram. The
629 relevant loop is either identified by the given loop name, or it is the
630 innermost enclosing loop when no loop name is given.
631
632 A ``Loop_Entry`` attribute can only occur within a
633 ``Loop_Variant`` or ``Loop_Invariant`` pragma. A common use of
634 ``Loop_Entry`` is to compare the current value of objects with their
635 initial value at loop entry, in a ``Loop_Invariant`` pragma.
636
637 The effect of using ``X'Loop_Entry`` is the same as declaring
638 a constant initialized with the initial value of ``X`` at loop
639 entry. This copy is not performed if the loop is not entered, or if the
640 corresponding pragmas are ignored or disabled.
641
642 Attribute Machine_Size
643 ======================
644 .. index:: Machine_Size
645
646 This attribute is identical to the ``Object_Size`` attribute. It is
647 provided for compatibility with the DEC Ada 83 attribute of this name.
648
649 Attribute Mantissa
650 ==================
651 .. index:: Ada 83 attributes
652
653 .. index:: Mantissa
654
655 The ``Mantissa`` attribute is provided for compatibility with Ada 83. See
656 the Ada 83 reference manual for an exact description of the semantics of
657 this attribute.
658
659 .. _Attribute_Maximum_Alignment:
660
661 Attribute Maximum_Alignment
662 ===========================
663 .. index:: Alignment, maximum
664
665 .. index:: Maximum_Alignment
666
667 ``Standard'Maximum_Alignment`` (``Standard`` is the only
668 allowed prefix) provides the maximum useful alignment value for the
669 target. This is a static value that can be used to specify the alignment
670 for an object, guaranteeing that it is properly aligned in all
671 cases.
672
673 Attribute Max_Integer_Size
674 ==========================
675 .. index:: Max_Integer_Size
676
677 ``Standard'Max_Integer_Size`` (``Standard`` is the only allowed
678 prefix) provides the size of the largest supported integer type for
679 the target. The result is a static constant.
680
681 Attribute Mechanism_Code
682 ========================
683 .. index:: Return values, passing mechanism
684
685 .. index:: Parameters, passing mechanism
686
687 .. index:: Mechanism_Code
688
689 ``func'Mechanism_Code`` yields an integer code for the
690 mechanism used for the result of function ``func``, and
691 ``subprog'Mechanism_Code (n)`` yields the mechanism
692 used for formal parameter number *n* (a static integer value, with 1
693 meaning the first parameter) of subprogram ``subprog``. The code returned is:
694
695
696
697 *1*
698 by copy (value)
699
700 *2*
701 by reference
702
703 Attribute Null_Parameter
704 ========================
705 .. index:: Zero address, passing
706
707 .. index:: Null_Parameter
708
709 A reference ``T'Null_Parameter`` denotes an imaginary object of
710 type or subtype ``T`` allocated at machine address zero. The attribute
711 is allowed only as the default expression of a formal parameter, or as
712 an actual expression of a subprogram call. In either case, the
713 subprogram must be imported.
714
715 The identity of the object is represented by the address zero in the
716 argument list, independent of the passing mechanism (explicit or
717 default).
718
719 This capability is needed to specify that a zero address should be
720 passed for a record or other composite object passed by reference.
721 There is no way of indicating this without the ``Null_Parameter``
722 attribute.
723
724 .. _Attribute-Object_Size:
725
726 Attribute Object_Size
727 =====================
728 .. index:: Size, used for objects
729
730 .. index:: Object_Size
731
732 The size of an object is not necessarily the same as the size of the type
733 of an object. This is because by default object sizes are increased to be
734 a multiple of the alignment of the object. For example,
735 ``Natural'Size`` is
736 31, but by default objects of type ``Natural`` will have a size of 32 bits.
737 Similarly, a record containing an integer and a character:
738
739 .. code-block:: ada
740
741 type Rec is record
742 I : Integer;
743 C : Character;
744 end record;
745
746
747 will have a size of 40 (that is ``Rec'Size`` will be 40). The
748 alignment will be 4, because of the
749 integer field, and so the default size of record objects for this type
750 will be 64 (8 bytes).
751
752 If the alignment of the above record is specified to be 1, then the
753 object size will be 40 (5 bytes). This is true by default, and also
754 an object size of 40 can be explicitly specified in this case.
755
756 A consequence of this capability is that different object sizes can be
757 given to subtypes that would otherwise be considered in Ada to be
758 statically matching. But it makes no sense to consider such subtypes
759 as statically matching. Consequently, GNAT adds a rule
760 to the static matching rules that requires object sizes to match.
761 Consider this example:
762
763 .. code-block:: ada
764
765 1. procedure BadAVConvert is
766 2. type R is new Integer;
767 3. subtype R1 is R range 1 .. 10;
768 4. subtype R2 is R range 1 .. 10;
769 5. for R1'Object_Size use 8;
770 6. for R2'Object_Size use 16;
771 7. type R1P is access all R1;
772 8. type R2P is access all R2;
773 9. R1PV : R1P := new R1'(4);
774 10. R2PV : R2P;
775 11. begin
776 12. R2PV := R2P (R1PV);
777 |
778 >>> target designated subtype not compatible with
779 type "R1" defined at line 3
780
781 13. end;
782
783
784 In the absence of lines 5 and 6,
785 types ``R1`` and ``R2`` statically match and
786 hence the conversion on line 12 is legal. But since lines 5 and 6
787 cause the object sizes to differ, GNAT considers that types
788 ``R1`` and ``R2`` are not statically matching, and line 12
789 generates the diagnostic shown above.
790
791 Similar additional checks are performed in other contexts requiring
792 statically matching subtypes.
793
794 Attribute Old
795 =============
796 .. index:: Old
797
798 In addition to the usage of ``Old`` defined in the Ada 2012 RM (usage
799 within ``Post`` aspect), GNAT also permits the use of this attribute
800 in implementation defined pragmas ``Postcondition``,
801 ``Contract_Cases`` and ``Test_Case``. Also usages of
802 ``Old`` which would be illegal according to the Ada 2012 RM
803 definition are allowed under control of
804 implementation defined pragma ``Unevaluated_Use_Of_Old``.
805
806 Attribute Passed_By_Reference
807 =============================
808 .. index:: Parameters, when passed by reference
809
810 .. index:: Passed_By_Reference
811
812 ``typ'Passed_By_Reference`` for any subtype `typ` returns
813 a value of type ``Boolean`` value that is ``True`` if the type is
814 normally passed by reference and ``False`` if the type is normally
815 passed by copy in calls. For scalar types, the result is always ``False``
816 and is static. For non-scalar types, the result is nonstatic.
817
818 Attribute Pool_Address
819 ======================
820 .. index:: Pool_Address
821
822 ``X'Pool_Address`` for any object ``X`` returns the address
823 of X within its storage pool. This is the same as
824 ``X'Address``, except that for an unconstrained array whose
825 bounds are allocated just before the first component,
826 ``X'Pool_Address`` returns the address of those bounds,
827 whereas ``X'Address`` returns the address of the first
828 component.
829
830 Here, we are interpreting 'storage pool' broadly to mean
831 ``wherever the object is allocated``, which could be a
832 user-defined storage pool,
833 the global heap, on the stack, or in a static memory area.
834 For an object created by ``new``, ``Ptr.all'Pool_Address`` is
835 what is passed to ``Allocate`` and returned from ``Deallocate``.
836
837 Attribute Range_Length
838 ======================
839 .. index:: Range_Length
840
841 ``typ'Range_Length`` for any discrete type `typ` yields
842 the number of values represented by the subtype (zero for a null
843 range). The result is static for static subtypes. ``Range_Length``
844 applied to the index subtype of a one dimensional array always gives the
845 same result as ``Length`` applied to the array itself.
846
847 Attribute Restriction_Set
848 =========================
849 .. index:: Restriction_Set
850 .. index:: Restrictions
851
852 This attribute allows compile time testing of restrictions that
853 are currently in effect. It is primarily intended for specializing
854 code in the run-time based on restrictions that are active (e.g.
855 don't need to save fpt registers if restriction No_Floating_Point
856 is known to be in effect), but can be used anywhere.
857
858 There are two forms:
859
860 .. code-block:: ada
861
862 System'Restriction_Set (partition_boolean_restriction_NAME)
863 System'Restriction_Set (No_Dependence => library_unit_NAME);
864
865
866 In the case of the first form, the only restriction names
867 allowed are parameterless restrictions that are checked
868 for consistency at bind time. For a complete list see the
869 subtype ``System.Rident.Partition_Boolean_Restrictions``.
870
871 The result returned is True if the restriction is known to
872 be in effect, and False if the restriction is known not to
873 be in effect. An important guarantee is that the value of
874 a Restriction_Set attribute is known to be consistent throughout
875 all the code of a partition.
876
877 This is trivially achieved if the entire partition is compiled
878 with a consistent set of restriction pragmas. However, the
879 compilation model does not require this. It is possible to
880 compile one set of units with one set of pragmas, and another
881 set of units with another set of pragmas. It is even possible
882 to compile a spec with one set of pragmas, and then WITH the
883 same spec with a different set of pragmas. Inconsistencies
884 in the actual use of the restriction are checked at bind time.
885
886 In order to achieve the guarantee of consistency for the
887 Restriction_Set pragma, we consider that a use of the pragma
888 that yields False is equivalent to a violation of the
889 restriction.
890
891 So for example if you write
892
893 .. code-block:: ada
894
895 if System'Restriction_Set (No_Floating_Point) then
896 ...
897 else
898 ...
899 end if;
900
901
902 And the result is False, so that the else branch is executed,
903 you can assume that this restriction is not set for any unit
904 in the partition. This is checked by considering this use of
905 the restriction pragma to be a violation of the restriction
906 No_Floating_Point. This means that no other unit can attempt
907 to set this restriction (if some unit does attempt to set it,
908 the binder will refuse to bind the partition).
909
910 Technical note: The restriction name and the unit name are
911 intepreted entirely syntactically, as in the corresponding
912 Restrictions pragma, they are not analyzed semantically,
913 so they do not have a type.
914
915 Attribute Result
916 ================
917 .. index:: Result
918
919 ``function'Result`` can only be used with in a Postcondition pragma
920 for a function. The prefix must be the name of the corresponding function. This
921 is used to refer to the result of the function in the postcondition expression.
922 For a further discussion of the use of this attribute and examples of its use,
923 see the description of pragma Postcondition.
924
925 Attribute Safe_Emax
926 ===================
927 .. index:: Ada 83 attributes
928
929 .. index:: Safe_Emax
930
931 The ``Safe_Emax`` attribute is provided for compatibility with Ada 83. See
932 the Ada 83 reference manual for an exact description of the semantics of
933 this attribute.
934
935 Attribute Safe_Large
936 ====================
937 .. index:: Ada 83 attributes
938
939 .. index:: Safe_Large
940
941 The ``Safe_Large`` attribute is provided for compatibility with Ada 83. See
942 the Ada 83 reference manual for an exact description of the semantics of
943 this attribute.
944
945 Attribute Safe_Small
946 ====================
947 .. index:: Ada 83 attributes
948
949 .. index:: Safe_Small
950
951 The ``Safe_Small`` attribute is provided for compatibility with Ada 83. See
952 the Ada 83 reference manual for an exact description of the semantics of
953 this attribute.
954
955 .. _Attribute-Scalar_Storage_Order:
956
957 Attribute Scalar_Storage_Order
958 ==============================
959 .. index:: Endianness
960
961 .. index:: Scalar storage order
962
963 .. index:: Scalar_Storage_Order
964
965 For every array or record type ``S``, the representation attribute
966 ``Scalar_Storage_Order`` denotes the order in which storage elements
967 that make up scalar components are ordered within S. The value given must
968 be a static expression of type System.Bit_Order. The following is an example
969 of the use of this feature:
970
971 .. code-block:: ada
972
973 -- Component type definitions
974
975 subtype Yr_Type is Natural range 0 .. 127;
976 subtype Mo_Type is Natural range 1 .. 12;
977 subtype Da_Type is Natural range 1 .. 31;
978
979 -- Record declaration
980
981 type Date is record
982 Years_Since_1980 : Yr_Type;
983 Month : Mo_Type;
984 Day_Of_Month : Da_Type;
985 end record;
986
987 -- Record representation clause
988
989 for Date use record
990 Years_Since_1980 at 0 range 0 .. 6;
991 Month at 0 range 7 .. 10;
992 Day_Of_Month at 0 range 11 .. 15;
993 end record;
994
995 -- Attribute definition clauses
996
997 for Date'Bit_Order use System.High_Order_First;
998 for Date'Scalar_Storage_Order use System.High_Order_First;
999 -- If Scalar_Storage_Order is specified, it must be consistent with
1000 -- Bit_Order, so it's best to always define the latter explicitly if
1001 -- the former is used.
1002
1003
1004 Other properties are as for the standard representation attribute ``Bit_Order``
1005 defined by Ada RM 13.5.3(4). The default is ``System.Default_Bit_Order``.
1006
1007 For a record type ``T``, if ``T'Scalar_Storage_Order`` is
1008 specified explicitly, it shall be equal to ``T'Bit_Order``. Note:
1009 this means that if a ``Scalar_Storage_Order`` attribute definition
1010 clause is not confirming, then the type's ``Bit_Order`` shall be
1011 specified explicitly and set to the same value.
1012
1013 Derived types inherit an explicitly set scalar storage order from their parent
1014 types. This may be overridden for the derived type by giving an explicit scalar
1015 storage order for it. However, for a record extension, the derived type must
1016 have the same scalar storage order as the parent type.
1017
1018 A component of a record type that is itself a record or an array and that does
1019 not start and end on a byte boundary must have have the same scalar storage
1020 order as the record type. A component of a bit-packed array type that is itself
1021 a record or an array must have the same scalar storage order as the array type.
1022
1023 No component of a type that has an explicit ``Scalar_Storage_Order``
1024 attribute definition may be aliased.
1025
1026 A confirming ``Scalar_Storage_Order`` attribute definition clause (i.e.
1027 with a value equal to ``System.Default_Bit_Order``) has no effect.
1028
1029 If the opposite storage order is specified, then whenever the value of
1030 a scalar component of an object of type ``S`` is read, the storage
1031 elements of the enclosing machine scalar are first reversed (before
1032 retrieving the component value, possibly applying some shift and mask
1033 operatings on the enclosing machine scalar), and the opposite operation
1034 is done for writes.
1035
1036 In that case, the restrictions set forth in 13.5.1(10.3/2) for scalar components
1037 are relaxed. Instead, the following rules apply:
1038
1039 * the underlying storage elements are those at positions
1040 ``(position + first_bit / storage_element_size) .. (position + (last_bit + storage_element_size - 1) / storage_element_size)``
1041 * the sequence of underlying storage elements shall have
1042 a size no greater than the largest machine scalar
1043 * the enclosing machine scalar is defined as the smallest machine
1044 scalar starting at a position no greater than
1045 ``position + first_bit / storage_element_size`` and covering
1046 storage elements at least up to ``position + (last_bit + storage_element_size - 1) / storage_element_size```
1047 * the position of the component is interpreted relative to that machine
1048 scalar.
1049
1050 If no scalar storage order is specified for a type (either directly, or by
1051 inheritance in the case of a derived type), then the default is normally
1052 the native ordering of the target, but this default can be overridden using
1053 pragma ``Default_Scalar_Storage_Order``.
1054
1055 If a component of ``T`` is itself of a record or array type, the specfied
1056 ``Scalar_Storage_Order`` does *not* apply to that nested type: an explicit
1057 attribute definition clause must be provided for the component type as well
1058 if desired.
1059
1060 Representation changes that explicitly or implicitly toggle the scalar storage
1061 order are not supported and may result in erroneous execution of the program,
1062 except when performed by means of an instance of ``Ada.Unchecked_Conversion``.
1063
1064 In particular, overlays are not supported and a warning is given for them:
1065
1066 .. code-block:: ada
1067
1068 type Rec_LE is record
1069 I : Integer;
1070 end record;
1071
1072 for Rec_LE use record
1073 I at 0 range 0 .. 31;
1074 end record;
1075
1076 for Rec_LE'Bit_Order use System.Low_Order_First;
1077 for Rec_LE'Scalar_Storage_Order use System.Low_Order_First;
1078
1079 type Rec_BE is record
1080 I : Integer;
1081 end record;
1082
1083 for Rec_BE use record
1084 I at 0 range 0 .. 31;
1085 end record;
1086
1087 for Rec_BE'Bit_Order use System.High_Order_First;
1088 for Rec_BE'Scalar_Storage_Order use System.High_Order_First;
1089
1090 R_LE : Rec_LE;
1091
1092 R_BE : Rec_BE;
1093 for R_BE'Address use R_LE'Address;
1094
1095 ``warning: overlay changes scalar storage order [enabled by default]``
1096
1097 In most cases, such representation changes ought to be replaced by an
1098 instantiation of a function or procedure provided by ``GNAT.Byte_Swapping``.
1099
1100 Note that the scalar storage order only affects the in-memory data
1101 representation. It has no effect on the representation used by stream
1102 attributes.
1103
1104 Note that debuggers may be unable to display the correct value of scalar
1105 components of a type for which the opposite storage order is specified.
1106
1107 .. _Attribute_Simple_Storage_Pool:
1108
1109 Attribute Simple_Storage_Pool
1110 =============================
1111 .. index:: Storage pool, simple
1112
1113 .. index:: Simple storage pool
1114
1115 .. index:: Simple_Storage_Pool
1116
1117 For every nonformal, nonderived access-to-object type ``Acc``, the
1118 representation attribute ``Simple_Storage_Pool`` may be specified
1119 via an attribute_definition_clause (or by specifying the equivalent aspect):
1120
1121 .. code-block:: ada
1122
1123 My_Pool : My_Simple_Storage_Pool_Type;
1124
1125 type Acc is access My_Data_Type;
1126
1127 for Acc'Simple_Storage_Pool use My_Pool;
1128
1129
1130
1131 The name given in an attribute_definition_clause for the
1132 ``Simple_Storage_Pool`` attribute shall denote a variable of
1133 a 'simple storage pool type' (see pragma `Simple_Storage_Pool_Type`).
1134
1135 The use of this attribute is only allowed for a prefix denoting a type
1136 for which it has been specified. The type of the attribute is the type
1137 of the variable specified as the simple storage pool of the access type,
1138 and the attribute denotes that variable.
1139
1140 It is illegal to specify both ``Storage_Pool`` and ``Simple_Storage_Pool``
1141 for the same access type.
1142
1143 If the ``Simple_Storage_Pool`` attribute has been specified for an access
1144 type, then applying the ``Storage_Pool`` attribute to the type is flagged
1145 with a warning and its evaluation raises the exception ``Program_Error``.
1146
1147 If the Simple_Storage_Pool attribute has been specified for an access
1148 type ``S``, then the evaluation of the attribute ``S'Storage_Size``
1149 returns the result of calling ``Storage_Size (S'Simple_Storage_Pool)``,
1150 which is intended to indicate the number of storage elements reserved for
1151 the simple storage pool. If the Storage_Size function has not been defined
1152 for the simple storage pool type, then this attribute returns zero.
1153
1154 If an access type ``S`` has a specified simple storage pool of type
1155 ``SSP``, then the evaluation of an allocator for that access type calls
1156 the primitive ``Allocate`` procedure for type ``SSP``, passing
1157 ``S'Simple_Storage_Pool`` as the pool parameter. The detailed
1158 semantics of such allocators is the same as those defined for allocators
1159 in section 13.11 of the :title:`Ada Reference Manual`, with the term
1160 *simple storage pool* substituted for *storage pool*.
1161
1162 If an access type ``S`` has a specified simple storage pool of type
1163 ``SSP``, then a call to an instance of the ``Ada.Unchecked_Deallocation``
1164 for that access type invokes the primitive ``Deallocate`` procedure
1165 for type ``SSP``, passing ``S'Simple_Storage_Pool`` as the pool
1166 parameter. The detailed semantics of such unchecked deallocations is the same
1167 as defined in section 13.11.2 of the Ada Reference Manual, except that the
1168 term *simple storage pool* is substituted for *storage pool*.
1169
1170 Attribute Small
1171 ===============
1172 .. index:: Ada 83 attributes
1173
1174 .. index:: Small
1175
1176 The ``Small`` attribute is defined in Ada 95 (and Ada 2005) only for
1177 fixed-point types.
1178 GNAT also allows this attribute to be applied to floating-point types
1179 for compatibility with Ada 83. See
1180 the Ada 83 reference manual for an exact description of the semantics of
1181 this attribute when applied to floating-point types.
1182
1183 Attribute Small_Denominator
1184 ===========================
1185 .. index:: Small
1186
1187 .. index:: Small_Denominator
1188
1189 ``typ'Small_Denominator`` for any fixed-point subtype `typ` yields the
1190 denominator in the representation of ``typ'Small`` as a rational number
1191 with coprime factors (i.e. as an irreducible fraction).
1192
1193 Attribute Small_Numerator
1194 =========================
1195 .. index:: Small
1196
1197 .. index:: Small_Numerator
1198
1199 ``typ'Small_Numerator`` for any fixed-point subtype `typ` yields the
1200 numerator in the representation of ``typ'Small`` as a rational number
1201 with coprime factors (i.e. as an irreducible fraction).
1202
1203 Attribute Storage_Unit
1204 ======================
1205 .. index:: Storage_Unit
1206
1207 ``Standard'Storage_Unit`` (``Standard`` is the only allowed
1208 prefix) provides the same value as ``System.Storage_Unit``.
1209
1210 Attribute Stub_Type
1211 ===================
1212 .. index:: Stub_Type
1213
1214 The GNAT implementation of remote access-to-classwide types is
1215 organized as described in AARM section E.4 (20.t): a value of an RACW type
1216 (designating a remote object) is represented as a normal access
1217 value, pointing to a "stub" object which in turn contains the
1218 necessary information to contact the designated remote object. A
1219 call on any dispatching operation of such a stub object does the
1220 remote call, if necessary, using the information in the stub object
1221 to locate the target partition, etc.
1222
1223 For a prefix ``T`` that denotes a remote access-to-classwide type,
1224 ``T'Stub_Type`` denotes the type of the corresponding stub objects.
1225
1226 By construction, the layout of ``T'Stub_Type`` is identical to that of
1227 type ``RACW_Stub_Type`` declared in the internal implementation-defined
1228 unit ``System.Partition_Interface``. Use of this attribute will create
1229 an implicit dependency on this unit.
1230
1231 Attribute System_Allocator_Alignment
1232 ====================================
1233 .. index:: Alignment, allocator
1234
1235 .. index:: System_Allocator_Alignment
1236
1237 ``Standard'System_Allocator_Alignment`` (``Standard`` is the only
1238 allowed prefix) provides the observable guaranted to be honored by
1239 the system allocator (malloc). This is a static value that can be used
1240 in user storage pools based on malloc either to reject allocation
1241 with alignment too large or to enable a realignment circuitry if the
1242 alignment request is larger than this value.
1243
1244 Attribute Target_Name
1245 =====================
1246 .. index:: Target_Name
1247
1248 ``Standard'Target_Name`` (``Standard`` is the only allowed
1249 prefix) provides a static string value that identifies the target
1250 for the current compilation. For GCC implementations, this is the
1251 standard gcc target name without the terminating slash (for
1252 example, GNAT 5.0 on windows yields "i586-pc-mingw32msv").
1253
1254 Attribute To_Address
1255 ====================
1256 .. index:: To_Address
1257
1258 The ``System'To_Address``
1259 (``System`` is the only allowed prefix)
1260 denotes a function identical to
1261 ``System.Storage_Elements.To_Address`` except that
1262 it is a static attribute. This means that if its argument is
1263 a static expression, then the result of the attribute is a
1264 static expression. This means that such an expression can be
1265 used in contexts (e.g., preelaborable packages) which require a
1266 static expression and where the function call could not be used
1267 (since the function call is always nonstatic, even if its
1268 argument is static). The argument must be in the range
1269 -(2**(m-1)) .. 2**m-1, where m is the memory size
1270 (typically 32 or 64). Negative values are intepreted in a
1271 modular manner (e.g., -1 means the same as 16#FFFF_FFFF# on
1272 a 32 bits machine).
1273
1274 Attribute To_Any
1275 ================
1276 .. index:: To_Any
1277
1278 This internal attribute is used for the generation of remote subprogram
1279 stubs in the context of the Distributed Systems Annex.
1280
1281 Attribute Type_Class
1282 ====================
1283 .. index:: Type_Class
1284
1285 ``typ'Type_Class`` for any type or subtype `typ` yields
1286 the value of the type class for the full type of `typ`. If
1287 `typ` is a generic formal type, the value is the value for the
1288 corresponding actual subtype. The value of this attribute is of type
1289 ``System.Aux_DEC.Type_Class``, which has the following definition:
1290
1291 .. code-block:: ada
1292
1293 type Type_Class is
1294 (Type_Class_Enumeration,
1295 Type_Class_Integer,
1296 Type_Class_Fixed_Point,
1297 Type_Class_Floating_Point,
1298 Type_Class_Array,
1299 Type_Class_Record,
1300 Type_Class_Access,
1301 Type_Class_Task,
1302 Type_Class_Address);
1303
1304
1305 Protected types yield the value ``Type_Class_Task``, which thus
1306 applies to all concurrent types. This attribute is designed to
1307 be compatible with the DEC Ada 83 attribute of the same name.
1308
1309 Attribute Type_Key
1310 ==================
1311 .. index:: Type_Key
1312
1313 The ``Type_Key`` attribute is applicable to a type or subtype and
1314 yields a value of type Standard.String containing encoded information
1315 about the type or subtype. This provides improved compatibility with
1316 other implementations that support this attribute.
1317
1318 Attribute TypeCode
1319 ==================
1320 .. index:: TypeCode
1321
1322 This internal attribute is used for the generation of remote subprogram
1323 stubs in the context of the Distributed Systems Annex.
1324
1325 Attribute Unconstrained_Array
1326 =============================
1327 .. index:: Unconstrained_Array
1328
1329 The ``Unconstrained_Array`` attribute can be used with a prefix that
1330 denotes any type or subtype. It is a static attribute that yields
1331 ``True`` if the prefix designates an unconstrained array,
1332 and ``False`` otherwise. In a generic instance, the result is
1333 still static, and yields the result of applying this test to the
1334 generic actual.
1335
1336 Attribute Universal_Literal_String
1337 ==================================
1338 .. index:: Named numbers, representation of
1339
1340 .. index:: Universal_Literal_String
1341
1342 The prefix of ``Universal_Literal_String`` must be a named
1343 number. The static result is the string consisting of the characters of
1344 the number as defined in the original source. This allows the user
1345 program to access the actual text of named numbers without intermediate
1346 conversions and without the need to enclose the strings in quotes (which
1347 would preclude their use as numbers).
1348
1349 For example, the following program prints the first 50 digits of pi:
1350
1351 .. code-block:: ada
1352
1353 with Text_IO; use Text_IO;
1354 with Ada.Numerics;
1355 procedure Pi is
1356 begin
1357 Put (Ada.Numerics.Pi'Universal_Literal_String);
1358 end;
1359
1360
1361 Attribute Unrestricted_Access
1362 =============================
1363 .. index:: Access, unrestricted
1364
1365 .. index:: Unrestricted_Access
1366
1367 The ``Unrestricted_Access`` attribute is similar to ``Access``
1368 except that all accessibility and aliased view checks are omitted. This
1369 is a user-beware attribute.
1370
1371 For objects, it is similar to ``Address``, for which it is a
1372 desirable replacement where the value desired is an access type.
1373 In other words, its effect is similar to first applying the
1374 ``Address`` attribute and then doing an unchecked conversion to a
1375 desired access type.
1376
1377 For subprograms, ``P'Unrestricted_Access`` may be used where
1378 ``P'Access`` would be illegal, to construct a value of a
1379 less-nested named access type that designates a more-nested
1380 subprogram. This value may be used in indirect calls, so long as the
1381 more-nested subprogram still exists; once the subprogram containing it
1382 has returned, such calls are erroneous. For example:
1383
1384 .. code-block:: ada
1385
1386 package body P is
1387
1388 type Less_Nested is not null access procedure;
1389 Global : Less_Nested;
1390
1391 procedure P1 is
1392 begin
1393 Global.all;
1394 end P1;
1395
1396 procedure P2 is
1397 Local_Var : Integer;
1398
1399 procedure More_Nested is
1400 begin
1401 ... Local_Var ...
1402 end More_Nested;
1403 begin
1404 Global := More_Nested'Unrestricted_Access;
1405 P1;
1406 end P2;
1407
1408 end P;
1409
1410
1411 When P1 is called from P2, the call via Global is OK, but if P1 were
1412 called after P2 returns, it would be an erroneous use of a dangling
1413 pointer.
1414
1415 For objects, it is possible to use ``Unrestricted_Access`` for any
1416 type. However, if the result is of an access-to-unconstrained array
1417 subtype, then the resulting pointer has the same scope as the context
1418 of the attribute, and must not be returned to some enclosing scope.
1419 For instance, if a function uses ``Unrestricted_Access`` to create
1420 an access-to-unconstrained-array and returns that value to the caller,
1421 the result will involve dangling pointers. In addition, it is only
1422 valid to create pointers to unconstrained arrays using this attribute
1423 if the pointer has the normal default 'fat' representation where a
1424 pointer has two components, one points to the array and one points to
1425 the bounds. If a size clause is used to force 'thin' representation
1426 for a pointer to unconstrained where there is only space for a single
1427 pointer, then the resulting pointer is not usable.
1428
1429 In the simple case where a direct use of Unrestricted_Access attempts
1430 to make a thin pointer for a non-aliased object, the compiler will
1431 reject the use as illegal, as shown in the following example:
1432
1433 .. code-block:: ada
1434
1435 with System; use System;
1436 procedure SliceUA2 is
1437 type A is access all String;
1438 for A'Size use Standard'Address_Size;
1439
1440 procedure P (Arg : A) is
1441 begin
1442 null;
1443 end P;
1444
1445 X : String := "hello world!";
1446 X2 : aliased String := "hello world!";
1447
1448 AV : A := X'Unrestricted_Access; -- ERROR
1449 |
1450 >>> illegal use of Unrestricted_Access attribute
1451 >>> attempt to generate thin pointer to unaliased object
1452
1453 begin
1454 P (X'Unrestricted_Access); -- ERROR
1455 |
1456 >>> illegal use of Unrestricted_Access attribute
1457 >>> attempt to generate thin pointer to unaliased object
1458
1459 P (X(7 .. 12)'Unrestricted_Access); -- ERROR
1460 |
1461 >>> illegal use of Unrestricted_Access attribute
1462 >>> attempt to generate thin pointer to unaliased object
1463
1464 P (X2'Unrestricted_Access); -- OK
1465 end;
1466
1467
1468 but other cases cannot be detected by the compiler, and are
1469 considered to be erroneous. Consider the following example:
1470
1471 .. code-block:: ada
1472
1473 with System; use System;
1474 with System; use System;
1475 procedure SliceUA is
1476 type AF is access all String;
1477
1478 type A is access all String;
1479 for A'Size use Standard'Address_Size;
1480
1481 procedure P (Arg : A) is
1482 begin
1483 if Arg'Length /= 6 then
1484 raise Program_Error;
1485 end if;
1486 end P;
1487
1488 X : String := "hello world!";
1489 Y : AF := X (7 .. 12)'Unrestricted_Access;
1490
1491 begin
1492 P (A (Y));
1493 end;
1494
1495
1496 A normal unconstrained array value
1497 or a constrained array object marked as aliased has the bounds in memory
1498 just before the array, so a thin pointer can retrieve both the data and
1499 the bounds. But in this case, the non-aliased object ``X`` does not have the
1500 bounds before the string. If the size clause for type ``A``
1501 were not present, then the pointer
1502 would be a fat pointer, where one component is a pointer to the bounds,
1503 and all would be well. But with the size clause present, the conversion from
1504 fat pointer to thin pointer in the call loses the bounds, and so this
1505 is erroneous, and the program likely raises a ``Program_Error`` exception.
1506
1507 In general, it is advisable to completely
1508 avoid mixing the use of thin pointers and the use of
1509 ``Unrestricted_Access`` where the designated type is an
1510 unconstrained array. The use of thin pointers should be restricted to
1511 cases of porting legacy code that implicitly assumes the size of pointers,
1512 and such code should not in any case be using this attribute.
1513
1514 Another erroneous situation arises if the attribute is
1515 applied to a constant. The resulting pointer can be used to access the
1516 constant, but the effect of trying to modify a constant in this manner
1517 is not well-defined. Consider this example:
1518
1519 .. code-block:: ada
1520
1521 P : constant Integer := 4;
1522 type R is access all Integer;
1523 RV : R := P'Unrestricted_Access;
1524 ..
1525 RV.all := 3;
1526
1527
1528 Here we attempt to modify the constant P from 4 to 3, but the compiler may
1529 or may not notice this attempt, and subsequent references to P may yield
1530 either the value 3 or the value 4 or the assignment may blow up if the
1531 compiler decides to put P in read-only memory. One particular case where
1532 ``Unrestricted_Access`` can be used in this way is to modify the
1533 value of an ``in`` parameter:
1534
1535 .. code-block:: ada
1536
1537 procedure K (S : in String) is
1538 type R is access all Character;
1539 RV : R := S (3)'Unrestricted_Access;
1540 begin
1541 RV.all := 'a';
1542 end;
1543
1544
1545 In general this is a risky approach. It may appear to "work" but such uses of
1546 ``Unrestricted_Access`` are potentially non-portable, even from one version
1547 of GNAT to another, so are best avoided if possible.
1548
1549 Attribute Update
1550 ================
1551 .. index:: Update
1552
1553 The ``Update`` attribute creates a copy of an array or record value
1554 with one or more modified components. The syntax is::
1555
1556 PREFIX'Update ( RECORD_COMPONENT_ASSOCIATION_LIST )
1557 PREFIX'Update ( ARRAY_COMPONENT_ASSOCIATION {, ARRAY_COMPONENT_ASSOCIATION } )
1558 PREFIX'Update ( MULTIDIMENSIONAL_ARRAY_COMPONENT_ASSOCIATION
1559 {, MULTIDIMENSIONAL_ARRAY_COMPONENT_ASSOCIATION } )
1560
1561 MULTIDIMENSIONAL_ARRAY_COMPONENT_ASSOCIATION ::= INDEX_EXPRESSION_LIST_LIST => EXPRESSION
1562 INDEX_EXPRESSION_LIST_LIST ::= INDEX_EXPRESSION_LIST {| INDEX_EXPRESSION_LIST }
1563 INDEX_EXPRESSION_LIST ::= ( EXPRESSION {, EXPRESSION } )
1564
1565
1566 where ``PREFIX`` is the name of an array or record object, the
1567 association list in parentheses does not contain an ``others``
1568 choice and the box symbol ``<>`` may not appear in any
1569 expression. The effect is to yield a copy of the array or record value
1570 which is unchanged apart from the components mentioned in the
1571 association list, which are changed to the indicated value. The
1572 original value of the array or record value is not affected. For
1573 example:
1574
1575 .. code-block:: ada
1576
1577 type Arr is Array (1 .. 5) of Integer;
1578 ...
1579 Avar1 : Arr := (1,2,3,4,5);
1580 Avar2 : Arr := Avar1'Update (2 => 10, 3 .. 4 => 20);
1581
1582
1583 yields a value for ``Avar2`` of 1,10,20,20,5 with ``Avar1``
1584 begin unmodified. Similarly:
1585
1586 .. code-block:: ada
1587
1588 type Rec is A, B, C : Integer;
1589 ...
1590 Rvar1 : Rec := (A => 1, B => 2, C => 3);
1591 Rvar2 : Rec := Rvar1'Update (B => 20);
1592
1593
1594 yields a value for ``Rvar2`` of (A => 1, B => 20, C => 3),
1595 with ``Rvar1`` being unmodifed.
1596 Note that the value of the attribute reference is computed
1597 completely before it is used. This means that if you write:
1598
1599 .. code-block:: ada
1600
1601 Avar1 := Avar1'Update (1 => 10, 2 => Function_Call);
1602
1603
1604 then the value of ``Avar1`` is not modified if ``Function_Call``
1605 raises an exception, unlike the effect of a series of direct assignments
1606 to elements of ``Avar1``. In general this requires that
1607 two extra complete copies of the object are required, which should be
1608 kept in mind when considering efficiency.
1609
1610 The ``Update`` attribute cannot be applied to prefixes of a limited
1611 type, and cannot reference discriminants in the case of a record type.
1612 The accessibility level of an Update attribute result object is defined
1613 as for an aggregate.
1614
1615 In the record case, no component can be mentioned more than once. In
1616 the array case, two overlapping ranges can appear in the association list,
1617 in which case the modifications are processed left to right.
1618
1619 Multi-dimensional arrays can be modified, as shown by this example:
1620
1621 .. code-block:: ada
1622
1623 A : array (1 .. 10, 1 .. 10) of Integer;
1624 ..
1625 A := A'Update ((1, 2) => 20, (3, 4) => 30);
1626
1627
1628 which changes element (1,2) to 20 and (3,4) to 30.
1629
1630 Attribute Valid_Image
1631 =======================
1632 .. index:: Valid_Image
1633
1634 The ``'Valid_Image`` attribute is defined for enumeration types other than
1635 those in package Standard. This attribute is a function that takes
1636 a String, and returns Boolean. ``T'Valid_Image (S)`` returns True
1637 if and only if ``T'Value (S)`` would not raise Constraint_Error.
1638
1639 Attribute Valid_Scalars
1640 =======================
1641 .. index:: Valid_Scalars
1642
1643 The ``'Valid_Scalars`` attribute is intended to make it easier to check the
1644 validity of scalar subcomponents of composite objects. The attribute is defined
1645 for any prefix ``P`` which denotes an object. Prefix ``P`` can be any type
1646 except for tagged private or ``Unchecked_Union`` types. The value of the
1647 attribute is of type ``Boolean``.
1648
1649 ``P'Valid_Scalars`` yields ``True`` if and only if the evaluation of
1650 ``C'Valid`` yields ``True`` for every scalar subcomponent ``C`` of ``P``, or if
1651 ``P`` has no scalar subcomponents. Attribute ``'Valid_Scalars`` is equivalent
1652 to attribute ``'Valid`` for scalar types.
1653
1654 It is not specified in what order the subcomponents are checked, nor whether
1655 any more are checked after any one of them is determined to be invalid. If the
1656 prefix ``P`` is of a class-wide type ``T'Class`` (where ``T`` is the associated
1657 specific type), or if the prefix ``P`` is of a specific tagged type ``T``, then
1658 only the subcomponents of ``T`` are checked; in other words, components of
1659 extensions of ``T`` are not checked even if ``T'Class (P)'Tag /= T'Tag``.
1660
1661 The compiler will issue a warning if it can be determined at compile time that
1662 the prefix of the attribute has no scalar subcomponents.
1663
1664 Note: ``Valid_Scalars`` can generate a lot of code, especially in the case of
1665 a large variant record. If the attribute is called in many places in the same
1666 program applied to objects of the same type, it can reduce program size to
1667 write a function with a single use of the attribute, and then call that
1668 function from multiple places.
1669
1670 Attribute VADS_Size
1671 ===================
1672 .. index:: Size, VADS compatibility
1673
1674 .. index:: VADS_Size
1675
1676 The ``'VADS_Size`` attribute is intended to make it easier to port
1677 legacy code which relies on the semantics of ``'Size`` as implemented
1678 by the VADS Ada 83 compiler. GNAT makes a best effort at duplicating the
1679 same semantic interpretation. In particular, ``'VADS_Size`` applied
1680 to a predefined or other primitive type with no Size clause yields the
1681 Object_Size (for example, ``Natural'Size`` is 32 rather than 31 on
1682 typical machines). In addition ``'VADS_Size`` applied to an object
1683 gives the result that would be obtained by applying the attribute to
1684 the corresponding type.
1685
1686 .. _Attribute-Value_Size:
1687
1688 Attribute Value_Size
1689 ====================
1690 .. index:: Size, setting for not-first subtype
1691
1692 .. index:: Value_Size
1693
1694 ``type'Value_Size`` is the number of bits required to represent
1695 a value of the given subtype. It is the same as ``type'Size``,
1696 but, unlike ``Size``, may be set for non-first subtypes.
1697
1698 Attribute Wchar_T_Size
1699 ======================
1700 .. index:: Wchar_T_Size
1701
1702 ``Standard'Wchar_T_Size`` (``Standard`` is the only allowed
1703 prefix) provides the size in bits of the C ``wchar_t`` type
1704 primarily for constructing the definition of this type in
1705 package ``Interfaces.C``. The result is a static constant.
1706
1707 Attribute Word_Size
1708 ===================
1709 .. index:: Word_Size
1710
1711 ``Standard'Word_Size`` (``Standard`` is the only allowed
1712 prefix) provides the value ``System.Word_Size``. The result is
1713 a static constant.