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