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_ISO_Date:
60
61Compilation_ISO_Date
62====================
63
64.. index:: Compilation_ISO_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_ISO_Date`` to obtain the date of
71the current compilation (in local time format YYYY-MM-DD).
72
73.. _Compilation_Date:
74
75Compilation_Date
76================
77
78.. index:: Compilation_Date
79
80Same as Compilation_ISO_Date, except the string is in the form
81MMM DD YYYY.
82
83.. _Compilation_Time:
84
85Compilation_Time
86================
87
88.. index:: Compilation_Time
89
90This intrinsic subprogram is used in the implementation of the
91library package ``GNAT.Source_Info``.  The only useful use of the
92intrinsic import in this case is the one in this unit, so an
93application program should simply call the function
94``GNAT.Source_Info.Compilation_Time`` to obtain the time of
95the current compilation (in local time format HH:MM:SS).
96
97.. _Enclosing_Entity:
98
99Enclosing_Entity
100================
101
102.. index:: Enclosing_Entity
103
104This intrinsic subprogram is used in the implementation of the
105library package ``GNAT.Source_Info``.  The only useful use of the
106intrinsic import in this case is the one in this unit, so an
107application program should simply call the function
108``GNAT.Source_Info.Enclosing_Entity`` to obtain the name of
109the current subprogram, package, task, entry, or protected subprogram.
110
111.. _Exception_Information:
112
113Exception_Information
114=====================
115
116.. index:: Exception_Information'
117
118This intrinsic subprogram is used in the implementation of the
119library package ``GNAT.Current_Exception``.  The only useful
120use of the intrinsic import in this case is the one in this unit,
121so an application program should simply call the function
122``GNAT.Current_Exception.Exception_Information`` to obtain
123the exception information associated with the current exception.
124
125.. _Exception_Message:
126
127Exception_Message
128=================
129
130.. index:: Exception_Message
131
132This intrinsic subprogram is used in the implementation of the
133library package ``GNAT.Current_Exception``.  The only useful
134use of the intrinsic import in this case is the one in this unit,
135so an application program should simply call the function
136``GNAT.Current_Exception.Exception_Message`` to obtain
137the message associated with the current exception.
138
139.. _Exception_Name:
140
141Exception_Name
142==============
143
144.. index:: Exception_Name
145
146This intrinsic subprogram is used in the implementation of the
147library package ``GNAT.Current_Exception``.  The only useful
148use of the intrinsic import in this case is the one in this unit,
149so an application program should simply call the function
150``GNAT.Current_Exception.Exception_Name`` to obtain
151the name of the current exception.
152
153.. _File:
154
155File
156====
157
158.. index:: File
159
160This intrinsic subprogram is used in the implementation of the
161library package ``GNAT.Source_Info``.  The only useful use of the
162intrinsic import in this case is the one in this unit, so an
163application program should simply call the function
164``GNAT.Source_Info.File`` to obtain the name of the current
165file.
166
167.. _Line:
168
169Line
170====
171
172.. index:: Line
173
174This intrinsic subprogram is used in the implementation of the
175library package ``GNAT.Source_Info``.  The only useful use of the
176intrinsic import in this case is the one in this unit, so an
177application program should simply call the function
178``GNAT.Source_Info.Line`` to obtain the number of the current
179source line.
180
181.. _Shifts_and_Rotates:
182
183Shifts 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
196In standard Ada, the shift and rotate functions are available only
197for the predefined modular types in package ``Interfaces``.  However, in
198GNAT it is possible to define these functions for any integer
199type (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
208
209The function name must be one of
210Shift_Left, Shift_Right, Shift_Right_Arithmetic, Rotate_Left, or
211Rotate_Right. T must be an integer type. T'Size must be
2128, 16, 32 or 64 bits; if T is modular, the modulus
213must be 2**8, 2**16, 2**32 or 2**64.
214The result type must be the same as the type of ``Value``.
215The shift amount must be Natural.
216The formal parameter names can be anything.
217
218A more convenient way of providing these shift operators is to use
219the Provide_Shift_Operators pragma, which provides the function declarations
220and corresponding pragma Import's for all five shift functions.
221
222.. _Source_Location:
223
224Source_Location
225===============
226
227.. index:: Source_Location
228
229This intrinsic subprogram is used in the implementation of the
230library routine ``GNAT.Source_Info``.  The only useful use of the
231intrinsic import in this case is the one in this unit, so an
232application program should simply call the function
233``GNAT.Source_Info.Source_Location`` to obtain the current
234source file location.
235