gcc/ada/doc/gnat_rm/intrinsic_subprograms.rst

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