Debian Codegraph @

gcc/ada/doc/gnat_rm/intrinsic_subprograms.rst

raw
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.