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