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