| 1 |
.. _Intrinsic_Subprograms: |
| 2 |
|
| 3 |
********************* |
| 4 |
Intrinsic Subprograms |
| 5 |
********************* |
| 6 |
|
| 7 |
.. index:: Intrinsic Subprograms |
| 8 |
|
| 9 |
GNAT allows a user application program to write the declaration: |
| 10 |
|
| 11 |
|
| 12 |
.. code-block:: ada |
| 13 |
|
| 14 |
pragma Import (Intrinsic, name); |
| 15 |
|
| 16 |
|
| 17 |
providing that the name corresponds to one of the implemented intrinsic |
| 18 |
subprograms in GNAT, and that the parameter profile of the referenced |
| 19 |
subprogram meets the requirements. This chapter describes the set of |
| 20 |
implemented intrinsic subprograms, and the requirements on parameter profiles. |
| 21 |
Note that no body is supplied; as with other uses of pragma Import, the |
| 22 |
body is supplied elsewhere (in this case by the compiler itself). Note |
| 23 |
that any use of this feature is potentially non-portable, since the |
| 24 |
Ada standard does not require Ada compilers to implement this feature. |
| 25 |
|
| 26 |
.. _Intrinsic_Operators: |
| 27 |
|
| 28 |
Intrinsic Operators |
| 29 |
=================== |
| 30 |
|
| 31 |
.. index:: Intrinsic operator |
| 32 |
|
| 33 |
All the predefined numeric operators in package Standard |
| 34 |
in ``pragma Import (Intrinsic,..)`` |
| 35 |
declarations. In the binary operator case, the operands must have the same |
| 36 |
size. The operand or operands must also be appropriate for |
| 37 |
the operator. For example, for addition, the operands must |
| 38 |
both be floating-point or both be fixed-point, and the |
| 39 |
right operand for ``"**"`` must have a root type of |
| 40 |
``Standard.Integer'Base``. |
| 41 |
You can use an intrinsic operator declaration as in the following example: |
| 42 |
|
| 43 |
|
| 44 |
.. code-block:: ada |
| 45 |
|
| 46 |
type Int1 is new Integer; |
| 47 |
type Int2 is new Integer; |
| 48 |
|
| 49 |
function "+" (X1 : Int1; X2 : Int2) return Int1; |
| 50 |
function "+" (X1 : Int1; X2 : Int2) return Int2; |
| 51 |
pragma Import (Intrinsic, "+"); |
| 52 |
|
| 53 |
|
| 54 |
This declaration would permit 'mixed mode' arithmetic on items |
| 55 |
of the differing types ``Int1`` and ``Int2``. |
| 56 |
It is also possible to specify such operators for private types, if the |
| 57 |
full views are appropriate arithmetic types. |
| 58 |
|
| 59 |
.. _Compilation_ISO_Date: |
| 60 |
|
| 61 |
Compilation_ISO_Date |
| 62 |
==================== |
| 63 |
|
| 64 |
.. index:: Compilation_ISO_Date |
| 65 |
|
| 66 |
This intrinsic subprogram is used in the implementation of the |
| 67 |
library package ``GNAT.Source_Info``. The only useful use of the |
| 68 |
intrinsic import in this case is the one in this unit, so an |
| 69 |
application program should simply call the function |
| 70 |
``GNAT.Source_Info.Compilation_ISO_Date`` to obtain the date of |
| 71 |
the current compilation (in local time format YYYY-MM-DD). |
| 72 |
|
| 73 |
.. _Compilation_Date: |
| 74 |
|
| 75 |
Compilation_Date |
| 76 |
================ |
| 77 |
|
| 78 |
.. index:: Compilation_Date |
| 79 |
|
| 80 |
Same as Compilation_ISO_Date, except the string is in the form |
| 81 |
MMM DD YYYY. |
| 82 |
|
| 83 |
.. _Compilation_Time: |
| 84 |
|
| 85 |
Compilation_Time |
| 86 |
================ |
| 87 |
|
| 88 |
.. index:: Compilation_Time |
| 89 |
|
| 90 |
This intrinsic subprogram is used in the implementation of the |
| 91 |
library package ``GNAT.Source_Info``. The only useful use of the |
| 92 |
intrinsic import in this case is the one in this unit, so an |
| 93 |
application program should simply call the function |
| 94 |
``GNAT.Source_Info.Compilation_Time`` to obtain the time of |
| 95 |
the current compilation (in local time format HH:MM:SS). |
| 96 |
|
| 97 |
.. _Enclosing_Entity: |
| 98 |
|
| 99 |
Enclosing_Entity |
| 100 |
================ |
| 101 |
|
| 102 |
.. index:: Enclosing_Entity |
| 103 |
|
| 104 |
This intrinsic subprogram is used in the implementation of the |
| 105 |
library package ``GNAT.Source_Info``. The only useful use of the |
| 106 |
intrinsic import in this case is the one in this unit, so an |
| 107 |
application program should simply call the function |
| 108 |
``GNAT.Source_Info.Enclosing_Entity`` to obtain the name of |
| 109 |
the current subprogram, package, task, entry, or protected subprogram. |
| 110 |
|
| 111 |
.. _Exception_Information: |
| 112 |
|
| 113 |
Exception_Information |
| 114 |
===================== |
| 115 |
|
| 116 |
.. index:: Exception_Information' |
| 117 |
|
| 118 |
This intrinsic subprogram is used in the implementation of the |
| 119 |
library package ``GNAT.Current_Exception``. The only useful |
| 120 |
use of the intrinsic import in this case is the one in this unit, |
| 121 |
so an application program should simply call the function |
| 122 |
``GNAT.Current_Exception.Exception_Information`` to obtain |
| 123 |
the exception information associated with the current exception. |
| 124 |
|
| 125 |
.. _Exception_Message: |
| 126 |
|
| 127 |
Exception_Message |
| 128 |
================= |
| 129 |
|
| 130 |
.. index:: Exception_Message |
| 131 |
|
| 132 |
This intrinsic subprogram is used in the implementation of the |
| 133 |
library package ``GNAT.Current_Exception``. The only useful |
| 134 |
use of the intrinsic import in this case is the one in this unit, |
| 135 |
so an application program should simply call the function |
| 136 |
``GNAT.Current_Exception.Exception_Message`` to obtain |
| 137 |
the message associated with the current exception. |
| 138 |
|
| 139 |
.. _Exception_Name: |
| 140 |
|
| 141 |
Exception_Name |
| 142 |
============== |
| 143 |
|
| 144 |
.. index:: Exception_Name |
| 145 |
|
| 146 |
This intrinsic subprogram is used in the implementation of the |
| 147 |
library package ``GNAT.Current_Exception``. The only useful |
| 148 |
use of the intrinsic import in this case is the one in this unit, |
| 149 |
so an application program should simply call the function |
| 150 |
``GNAT.Current_Exception.Exception_Name`` to obtain |
| 151 |
the name of the current exception. |
| 152 |
|
| 153 |
.. _File: |
| 154 |
|
| 155 |
File |
| 156 |
==== |
| 157 |
|
| 158 |
.. index:: File |
| 159 |
|
| 160 |
This intrinsic subprogram is used in the implementation of the |
| 161 |
library package ``GNAT.Source_Info``. The only useful use of the |
| 162 |
intrinsic import in this case is the one in this unit, so an |
| 163 |
application program should simply call the function |
| 164 |
``GNAT.Source_Info.File`` to obtain the name of the current |
| 165 |
file. |
| 166 |
|
| 167 |
.. _Line: |
| 168 |
|
| 169 |
Line |
| 170 |
==== |
| 171 |
|
| 172 |
.. index:: Line |
| 173 |
|
| 174 |
This intrinsic subprogram is used in the implementation of the |
| 175 |
library package ``GNAT.Source_Info``. The only useful use of the |
| 176 |
intrinsic import in this case is the one in this unit, so an |
| 177 |
application program should simply call the function |
| 178 |
``GNAT.Source_Info.Line`` to obtain the number of the current |
| 179 |
source line. |
| 180 |
|
| 181 |
.. _Shifts_and_Rotates: |
| 182 |
|
| 183 |
Shifts and Rotates |
| 184 |
================== |
| 185 |
|
| 186 |
.. index:: Shift_Left |
| 187 |
|
| 188 |
.. index:: Shift_Right |
| 189 |
|
| 190 |
.. index:: Shift_Right_Arithmetic |
| 191 |
|
| 192 |
.. index:: Rotate_Left |
| 193 |
|
| 194 |
.. index:: Rotate_Right |
| 195 |
|
| 196 |
In standard Ada, the shift and rotate functions are available only |
| 197 |
for the predefined modular types in package ``Interfaces``. However, in |
| 198 |
GNAT it is possible to define these functions for any integer |
| 199 |
type (signed or modular), as in this example: |
| 200 |
|
| 201 |
|
| 202 |
.. code-block:: ada |
| 203 |
|
| 204 |
function Shift_Left |
| 205 |
(Value : T; |
| 206 |
Amount : Natural) return T |
| 207 |
with Import, Convention => Intrinsic; |
| 208 |
|
| 209 |
|
| 210 |
The function name must be one of |
| 211 |
Shift_Left, Shift_Right, Shift_Right_Arithmetic, Rotate_Left, or |
| 212 |
Rotate_Right. T must be an integer type. T'Size must be |
| 213 |
8, 16, 32 or 64 bits; if T is modular, the modulus |
| 214 |
must be 2**8, 2**16, 2**32 or 2**64. |
| 215 |
The result type must be the same as the type of ``Value``. |
| 216 |
The shift amount must be Natural. |
| 217 |
The formal parameter names can be anything. |
| 218 |
|
| 219 |
A more convenient way of providing these shift operators is to use the |
| 220 |
Provide_Shift_Operators pragma, which provides the function declarations and |
| 221 |
corresponding pragma Import's for all five shift functions. For signed types |
| 222 |
the semantics of these operators is to interpret the bitwise result of the |
| 223 |
corresponding operator for modular type. In particular, shifting a negative |
| 224 |
number may change its sign bit to positive. |
| 225 |
|
| 226 |
.. _Source_Location: |
| 227 |
|
| 228 |
Source_Location |
| 229 |
=============== |
| 230 |
|
| 231 |
.. index:: Source_Location |
| 232 |
|
| 233 |
This intrinsic subprogram is used in the implementation of the |
| 234 |
library routine ``GNAT.Source_Info``. The only useful use of the |
| 235 |
intrinsic import in this case is the one in this unit, so an |
| 236 |
application program should simply call the function |
| 237 |
``GNAT.Source_Info.Source_Location`` to obtain the current |
| 238 |
source file location. |