OSDN Git Service

* 41intnam.ads, 42intnam.ads, 4aintnam.ads, 4cintnam.ads,
[pf3gnuchains/gcc-fork.git] / gcc / ada / uintp.ads
1 ------------------------------------------------------------------------------
2 --                                                                          --
3 --                         GNAT COMPILER COMPONENTS                         --
4 --                                                                          --
5 --                                U I N T P                                 --
6 --                                                                          --
7 --                                 S p e c                                  --
8 --                                                                          --
9 --                            $Revision$
10 --                                                                          --
11 --          Copyright (C) 1992-2002, Free Software Foundation, Inc.         --
12 --                                                                          --
13 -- GNAT is free software;  you can  redistribute it  and/or modify it under --
14 -- terms of the  GNU General Public License as published  by the Free Soft- --
15 -- ware  Foundation;  either version 2,  or (at your option) any later ver- --
16 -- sion.  GNAT is distributed in the hope that it will be useful, but WITH- --
17 -- OUT ANY WARRANTY;  without even the  implied warranty of MERCHANTABILITY --
18 -- or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License --
19 -- for  more details.  You should have  received  a copy of the GNU General --
20 -- Public License  distributed with GNAT;  see file COPYING.  If not, write --
21 -- to  the Free Software Foundation,  59 Temple Place - Suite 330,  Boston, --
22 -- MA 02111-1307, USA.                                                      --
23 --                                                                          --
24 -- As a special exception,  if other files  instantiate  generics from this --
25 -- unit, or you link  this unit with other files  to produce an executable, --
26 -- this  unit  does not  by itself cause  the resulting  executable  to  be --
27 -- covered  by the  GNU  General  Public  License.  This exception does not --
28 -- however invalidate  any other reasons why  the executable file  might be --
29 -- covered by the  GNU Public License.                                      --
30 --                                                                          --
31 -- GNAT was originally developed  by the GNAT team at  New York University. --
32 -- It is now maintained by Ada Core Technologies Inc (http://www.gnat.com). --
33 --                                                                          --
34 ------------------------------------------------------------------------------
35
36 --  Support for universal integer arithmetic
37
38 --  WARNING: There is a C version of this package. Any changes to this
39 --  source file must be properly reflected in the C header file sinfo.h
40
41 with Alloc;
42 with Table;
43 pragma Elaborate_All (Table);
44 with Types; use Types;
45
46 package Uintp is
47
48    -------------------------------------------------
49    -- Basic Types and Constants for Uintp Package --
50    -------------------------------------------------
51
52    type Uint is private;
53    --  The basic universal integer type
54
55    No_Uint : constant Uint;
56    --  A constant value indicating a missing or unset Uint value
57
58    Uint_0   : constant Uint;
59    Uint_1   : constant Uint;
60    Uint_2   : constant Uint;
61    Uint_3   : constant Uint;
62    Uint_4   : constant Uint;
63    Uint_5   : constant Uint;
64    Uint_6   : constant Uint;
65    Uint_7   : constant Uint;
66    Uint_8   : constant Uint;
67    Uint_9   : constant Uint;
68    Uint_10  : constant Uint;
69    Uint_12  : constant Uint;
70    Uint_15  : constant Uint;
71    Uint_16  : constant Uint;
72    Uint_24  : constant Uint;
73    Uint_32  : constant Uint;
74    Uint_63  : constant Uint;
75    Uint_64  : constant Uint;
76    Uint_128 : constant Uint;
77
78    Uint_Minus_1   : constant Uint;
79    Uint_Minus_2   : constant Uint;
80    Uint_Minus_3   : constant Uint;
81    Uint_Minus_4   : constant Uint;
82    Uint_Minus_5   : constant Uint;
83    Uint_Minus_6   : constant Uint;
84    Uint_Minus_7   : constant Uint;
85    Uint_Minus_8   : constant Uint;
86    Uint_Minus_9   : constant Uint;
87    Uint_Minus_12  : constant Uint;
88    Uint_Minus_128 : constant Uint;
89
90    -----------------
91    -- Subprograms --
92    -----------------
93
94    procedure Initialize;
95    --  Initialize Uint tables. Note that Initialize must not be called if
96    --  Tree_Read is used. Note also that there is no lock routine in this
97    --  unit, these are among the few tables that can be expanded during
98    --  gigi processing.
99
100    procedure Tree_Read;
101    --  Initializes internal tables from current tree file using Tree_Read.
102    --  Note that Initialize should not be called if Tree_Read is used.
103    --  Tree_Read includes all necessary initialization.
104
105    procedure Tree_Write;
106    --  Writes out internal tables to current tree file using Tree_Write.
107
108    function UI_Abs (Right : Uint) return Uint;
109    pragma Inline (UI_Abs);
110    --  Returns abs function of universal integer.
111
112    function UI_Add (Left : Uint; Right : Uint) return Uint;
113    function UI_Add (Left : Int;  Right : Uint) return Uint;
114    function UI_Add (Left : Uint; Right : Int)  return Uint;
115    --  Returns sum of two integer values.
116
117    function UI_Decimal_Digits_Hi (U : Uint) return Nat;
118    --  Returns an estimate of the number of decimal digits required to
119    --  represent the absolute value of U. This estimate is correct or high,
120    --  i.e. it never returns a value that is too low. The accuracy of the
121    --  estimate affects only the effectiveness of comparison optimizations
122    --  in Urealp.
123
124    function UI_Decimal_Digits_Lo (U : Uint) return Nat;
125    --  Returns an estimate of the number of decimal digits required to
126    --  represent the absolute value of U. This estimate is correct or low,
127    --  i.e. it never returns a value that is too high. The accuracy of the
128    --  estimate affects only the effectiveness of comparison optimizations
129    --  in Urealp.
130
131    function UI_Div (Left : Uint; Right : Uint) return Uint;
132    function UI_Div (Left : Int;  Right : Uint) return Uint;
133    function UI_Div (Left : Uint; Right : Int)  return Uint;
134    --  Returns quotient of two integer values. Fatal error if Right = 0
135
136    function UI_Eq (Left : Uint; Right : Uint) return Boolean;
137    function UI_Eq (Left : Int;  Right : Uint) return Boolean;
138    function UI_Eq (Left : Uint; Right : Int)  return Boolean;
139    pragma Inline (UI_Eq);
140    --  Compares integer values for equality.
141
142    function UI_Expon (Left : Uint; Right : Uint) return Uint;
143    function UI_Expon (Left : Int;  Right : Uint) return Uint;
144    function UI_Expon (Left : Uint; Right : Int)  return Uint;
145    function UI_Expon (Left : Int;  Right : Int)  return Uint;
146    --  Returns result of exponentiating two integer values
147    --  Fatal error if Right is negative.
148
149    function UI_GCD (Uin, Vin : Uint) return Uint;
150    --  Computes GCD of input values. Assumes Uin >= Vin >= 0.
151
152    function UI_Ge (Left : Uint; Right : Uint) return Boolean;
153    function UI_Ge (Left : Int;  Right : Uint) return Boolean;
154    function UI_Ge (Left : Uint; Right : Int)  return Boolean;
155    pragma Inline (UI_Ge);
156    --  Compares integer values for greater than or equal.
157
158    function UI_Gt (Left : Uint; Right : Uint) return Boolean;
159    function UI_Gt (Left : Int;  Right : Uint) return Boolean;
160    function UI_Gt (Left : Uint; Right : Int)  return Boolean;
161    pragma Inline (UI_Gt);
162    --  Compares integer values for greater than.
163
164    function UI_Is_In_Int_Range (Input : Uint) return Boolean;
165    pragma Inline (UI_Is_In_Int_Range);
166    --  Determines if universal integer is in Int range.
167
168    function UI_Le (Left : Uint; Right : Uint) return Boolean;
169    function UI_Le (Left : Int;  Right : Uint) return Boolean;
170    function UI_Le (Left : Uint; Right : Int)  return Boolean;
171    pragma Inline (UI_Le);
172    --  Compares integer values for less than or equal.
173
174    function UI_Lt (Left : Uint; Right : Uint) return Boolean;
175    function UI_Lt (Left : Int;  Right : Uint) return Boolean;
176    function UI_Lt (Left : Uint; Right : Int)  return Boolean;
177    --  Compares integer values for less than.
178
179    function UI_Max (Left : Uint; Right : Uint) return Uint;
180    function UI_Max (Left : Int;  Right : Uint) return Uint;
181    function UI_Max (Left : Uint; Right : Int)  return Uint;
182    --  Returns maximum of two integer values
183
184    function UI_Min (Left : Uint; Right : Uint) return Uint;
185    function UI_Min (Left : Int;  Right : Uint) return Uint;
186    function UI_Min (Left : Uint; Right : Int)  return Uint;
187    --  Returns minimum of two integer values.
188
189    function UI_Mod (Left : Uint; Right : Uint) return Uint;
190    function UI_Mod (Left : Int;  Right : Uint) return Uint;
191    function UI_Mod (Left : Uint; Right : Int)  return Uint;
192    pragma Inline (UI_Mod);
193    --  Returns mod function of two integer values.
194
195    function UI_Mul (Left : Uint; Right : Uint) return Uint;
196    function UI_Mul (Left : Int;  Right : Uint) return Uint;
197    function UI_Mul (Left : Uint; Right : Int)  return Uint;
198    --  Returns product of two integer values
199
200    function UI_Ne (Left : Uint; Right : Uint) return Boolean;
201    function UI_Ne (Left : Int;  Right : Uint) return Boolean;
202    function UI_Ne (Left : Uint; Right : Int)  return Boolean;
203    pragma Inline (UI_Ne);
204    --  Compares integer values for inequality.
205
206    function UI_Negate (Right : Uint) return Uint;
207    pragma Inline (UI_Negate);
208    --  Returns negative of universal integer.
209
210    function UI_Rem (Left : Uint; Right : Uint) return Uint;
211    function UI_Rem (Left : Int;  Right : Uint) return Uint;
212    function UI_Rem (Left : Uint; Right : Int)  return Uint;
213    --  Returns rem of two integer values.
214
215    function UI_Sub (Left : Uint; Right : Uint) return Uint;
216    function UI_Sub (Left : Int;  Right : Uint) return Uint;
217    function UI_Sub (Left : Uint; Right : Int)  return Uint;
218    pragma Inline (UI_Sub);
219    --  Returns difference of two integer values
220
221    function UI_From_Dint (Input : Dint) return Uint;
222    --  Converts Dint value to universal integer form.
223
224    function UI_From_Int (Input : Int) return Uint;
225    --  Converts Int value to universal integer form.
226
227    function UI_To_Int (Input : Uint) return Int;
228    --  Converts universal integer value to Int. Fatal error
229    --  if value is not in appropriate range.
230
231    function Num_Bits (Input : Uint) return Nat;
232    --  Approximate number of binary bits in given universal integer.
233    --  This function is used for capacity checks, and it can be one
234    --  bit off without affecting its usage.
235
236    ---------------------
237    -- Output Routines --
238    ---------------------
239
240    type UI_Format is (Hex, Decimal, Auto);
241    --  Used to determine whether UI_Image/UI_Write output is in hexadecimal
242    --  or decimal format. Auto, the default setting, lets the routine make
243    --  a decision based on the value.
244
245    UI_Image_Max    : constant := 32;
246    UI_Image_Buffer : String (1 .. UI_Image_Max);
247    UI_Image_Length : Natural;
248    --  Buffer used for UI_Image as described below
249
250    procedure UI_Image (Input : Uint; Format : UI_Format := Auto);
251    --  Places a representation of Uint, consisting of a possible minus sign,
252    --  followed by the value in UI_Image_Buffer. The form of the value is an
253    --  integer literal in either decimal (no base) or hexadecimal (base 16)
254    --  format. If Hex is True on entry, then hex mode is forced, otherwise
255    --  UI_Image makes a guess at which output format is more convenient. The
256    --  value must fit in UI_Image_Buffer. If necessary, the result is an
257    --  approximation of the proper value, using an exponential format. The
258    --  image of No_Uint is output as a single question mark.
259
260    procedure UI_Write (Input : Uint; Format : UI_Format := Auto);
261    --  Writes a representation of Uint, consisting of a possible minus sign,
262    --  followed by the value to the output file. The form of the value is an
263    --  integer literal in either decimal (no base) or hexadecimal (base 16)
264    --  format as appropriate. UI_Format shows which format to use. Auto,
265    --  the default, asks UI_Write to make a guess at which output format
266    --  will be more convenient to read.
267
268    procedure pid (Input : Uint);
269    pragma Export (Ada, pid);
270    --  Writes representation of Uint in decimal with a terminating line
271    --  return. This is intended for use from the debugger.
272
273    procedure pih (Input : Uint);
274    pragma Export (Ada, pih);
275    --  Writes representation of Uint in hex with a terminating line return.
276    --  This is intended for use from the debugger.
277
278    ------------------------
279    -- Operator Renamings --
280    ------------------------
281
282    function "+" (Left : Uint; Right : Uint) return Uint renames UI_Add;
283    function "+" (Left : Int;  Right : Uint) return Uint renames UI_Add;
284    function "+" (Left : Uint; Right : Int)  return Uint renames UI_Add;
285
286    function "/" (Left : Uint; Right : Uint) return Uint renames UI_Div;
287    function "/" (Left : Int;  Right : Uint) return Uint renames UI_Div;
288    function "/" (Left : Uint; Right : Int)  return Uint renames UI_Div;
289
290    function "*" (Left : Uint; Right : Uint) return Uint renames UI_Mul;
291    function "*" (Left : Int;  Right : Uint) return Uint renames UI_Mul;
292    function "*" (Left : Uint; Right : Int)  return Uint renames UI_Mul;
293
294    function "-" (Left : Uint; Right : Uint) return Uint renames UI_Sub;
295    function "-" (Left : Int;  Right : Uint) return Uint renames UI_Sub;
296    function "-" (Left : Uint; Right : Int)  return Uint renames UI_Sub;
297
298    function "**"  (Left : Uint; Right : Uint) return Uint renames UI_Expon;
299    function "**"  (Left : Uint; Right : Int)  return Uint renames UI_Expon;
300    function "**"  (Left : Int;  Right : Uint) return Uint renames UI_Expon;
301    function "**"  (Left : Int;  Right : Int)  return Uint renames UI_Expon;
302
303    function "abs" (Real : Uint) return Uint renames UI_Abs;
304
305    function "mod" (Left : Uint; Right : Uint) return Uint renames UI_Mod;
306    function "mod" (Left : Int;  Right : Uint) return Uint renames UI_Mod;
307    function "mod" (Left : Uint; Right : Int)  return Uint renames UI_Mod;
308
309    function "rem" (Left : Uint; Right : Uint) return Uint renames UI_Rem;
310    function "rem" (Left : Int;  Right : Uint) return Uint renames UI_Rem;
311    function "rem" (Left : Uint; Right : Int)  return Uint renames UI_Rem;
312
313    function "-"   (Real : Uint) return Uint renames UI_Negate;
314
315    function "="   (Left : Uint; Right : Uint) return Boolean renames UI_Eq;
316    function "="   (Left : Int;  Right : Uint) return Boolean renames UI_Eq;
317    function "="   (Left : Uint; Right : Int)  return Boolean renames UI_Eq;
318
319    function ">="  (Left : Uint; Right : Uint) return Boolean renames UI_Ge;
320    function ">="  (Left : Int;  Right : Uint) return Boolean renames UI_Ge;
321    function ">="  (Left : Uint; Right : Int)  return Boolean renames UI_Ge;
322
323    function ">"   (Left : Uint; Right : Uint) return Boolean renames UI_Gt;
324    function ">"   (Left : Int;  Right : Uint) return Boolean renames UI_Gt;
325    function ">"   (Left : Uint; Right : Int)  return Boolean renames UI_Gt;
326
327    function "<="  (Left : Uint; Right : Uint) return Boolean renames UI_Le;
328    function "<="  (Left : Int;  Right : Uint) return Boolean renames UI_Le;
329    function "<="  (Left : Uint; Right : Int)  return Boolean renames UI_Le;
330
331    function "<"   (Left : Uint; Right : Uint) return Boolean renames UI_Lt;
332    function "<"   (Left : Int;  Right : Uint) return Boolean renames UI_Lt;
333    function "<"   (Left : Uint; Right : Int)  return Boolean renames UI_Lt;
334
335    -----------------------------
336    -- Mark/Release Processing --
337    -----------------------------
338
339    --  The space used by Uint data is not automatically reclaimed. However,
340    --  a mark-release regime is implemented which allows storage to be
341    --  released back to a previously noted mark. This is used for example
342    --  when doing comparisons, where only intermediate results get stored
343    --  that do not need to be saved for future use.
344
345    type Save_Mark is private;
346
347    function Mark return Save_Mark;
348    --  Note mark point for future release
349
350    procedure Release (M : Save_Mark);
351    --  Release storage allocated since mark was noted
352
353    procedure Release_And_Save (M : Save_Mark; UI : in out Uint);
354    --  Like Release, except that the given Uint value (which is typically
355    --  among the data being released) is recopied after the release, so
356    --  that it is the most recent item, and UI is updated to point to
357    --  its copied location.
358
359    procedure Release_And_Save (M : Save_Mark; UI1, UI2 : in out Uint);
360    --  Like Release, except that the given Uint values (which are typically
361    --  among the data being released) are recopied after the release, so
362    --  that they are the most recent items, and UI1 and UI2 are updated if
363    --  necessary to point to the copied locations. This routine is careful
364    --  to do things in the right order, so that the values do not clobber
365    --  one another.
366
367    -----------------------------------
368    -- Representation of Uint Values --
369    -----------------------------------
370
371 private
372
373    type Uint is new Int range Uint_Low_Bound .. Uint_High_Bound;
374    for Uint'Size use 32;
375
376    No_Uint : constant Uint := Uint (Uint_Low_Bound);
377
378    --  Uint values are represented as multiple precision integers stored in
379    --  a multi-digit format using Base as the base. This value is chosen so
380    --  that the product Base*Base is within the range of allowed Int values.
381
382    --  Base is defined to allow efficient execution of the primitive
383    --  operations (a0, b0, c0) defined in the section "The Classical
384    --  Algorithms" (sec. 4.3.1) of Donald Knuth's "The Art of Computer
385    --  Programming", Vol. 2. These algorithms are used in this package.
386
387    Base_Bits : constant := 15;
388    --  Number of bits in base value
389
390    Base : constant Int := 2 ** Base_Bits;
391
392    --  Values in the range -(Base+1) .. maxdirect are encoded directly as
393    --  Uint values by adding a bias value. The value of maxdirect is chosen
394    --  so that a directly represented number always fits in two digits when
395    --  represented in base format.
396
397    Min_Direct : constant Int := -(Base - 1);
398    Max_Direct : constant Int := (Base - 1) * (Base - 1);
399
400    --  The following values define the bias used to store Uint values which
401    --  are in this range, as well as the biased values for the first and
402    --  last values in this range. We use a new derived type for these
403    --  constants to avoid accidental use of Uint arithmetic on these
404    --  values, which is never correct.
405
406    type Ctrl is range Int'First .. Int'Last;
407
408    Uint_Direct_Bias  : constant Ctrl := Ctrl (Uint_Low_Bound) + Ctrl (Base);
409    Uint_Direct_First : constant Ctrl := Uint_Direct_Bias + Ctrl (Min_Direct);
410    Uint_Direct_Last  : constant Ctrl := Uint_Direct_Bias + Ctrl (Max_Direct);
411
412    Uint_0   : constant Uint := Uint (Uint_Direct_Bias);
413    Uint_1   : constant Uint := Uint (Uint_Direct_Bias + 1);
414    Uint_2   : constant Uint := Uint (Uint_Direct_Bias + 2);
415    Uint_3   : constant Uint := Uint (Uint_Direct_Bias + 3);
416    Uint_4   : constant Uint := Uint (Uint_Direct_Bias + 4);
417    Uint_5   : constant Uint := Uint (Uint_Direct_Bias + 5);
418    Uint_6   : constant Uint := Uint (Uint_Direct_Bias + 6);
419    Uint_7   : constant Uint := Uint (Uint_Direct_Bias + 7);
420    Uint_8   : constant Uint := Uint (Uint_Direct_Bias + 8);
421    Uint_9   : constant Uint := Uint (Uint_Direct_Bias + 9);
422    Uint_10  : constant Uint := Uint (Uint_Direct_Bias + 10);
423    Uint_12  : constant Uint := Uint (Uint_Direct_Bias + 12);
424    Uint_15  : constant Uint := Uint (Uint_Direct_Bias + 15);
425    Uint_16  : constant Uint := Uint (Uint_Direct_Bias + 16);
426    Uint_24  : constant Uint := Uint (Uint_Direct_Bias + 24);
427    Uint_32  : constant Uint := Uint (Uint_Direct_Bias + 32);
428    Uint_63  : constant Uint := Uint (Uint_Direct_Bias + 63);
429    Uint_64  : constant Uint := Uint (Uint_Direct_Bias + 64);
430    Uint_128 : constant Uint := Uint (Uint_Direct_Bias + 128);
431
432    Uint_Minus_1   : constant Uint := Uint (Uint_Direct_Bias - 1);
433    Uint_Minus_2   : constant Uint := Uint (Uint_Direct_Bias - 2);
434    Uint_Minus_3   : constant Uint := Uint (Uint_Direct_Bias - 3);
435    Uint_Minus_4   : constant Uint := Uint (Uint_Direct_Bias - 4);
436    Uint_Minus_5   : constant Uint := Uint (Uint_Direct_Bias - 5);
437    Uint_Minus_6   : constant Uint := Uint (Uint_Direct_Bias - 6);
438    Uint_Minus_7   : constant Uint := Uint (Uint_Direct_Bias - 7);
439    Uint_Minus_8   : constant Uint := Uint (Uint_Direct_Bias - 8);
440    Uint_Minus_9   : constant Uint := Uint (Uint_Direct_Bias - 9);
441    Uint_Minus_12  : constant Uint := Uint (Uint_Direct_Bias - 12);
442    Uint_Minus_128 : constant Uint := Uint (Uint_Direct_Bias - 128);
443
444    type Save_Mark is record
445       Save_Uint   : Uint;
446       Save_Udigit : Int;
447    end record;
448
449    --  Values outside the range that is represented directly are stored
450    --  using two tables. The secondary table Udigits contains sequences of
451    --  Int values consisting of the digits of the number in a radix Base
452    --  system. The digits are stored from most significant to least
453    --  significant with the first digit only carrying the sign.
454
455    --  There is one entry in the primary Uints table for each distinct Uint
456    --  value. This table entry contains the length (number of digits) and
457    --  a starting offset of the value in the Udigits table.
458
459    Uint_First_Entry : constant Uint := Uint (Uint_Table_Start);
460
461    --  Some subprograms defined in this package manipulate the Udigits
462    --  table directly, while for others it is more convenient to work with
463    --  locally defined arrays of the digits of the Universal Integers.
464    --  The type UI_Vector is defined for this purpose and some internal
465    --  subprograms used for converting from one to the other are defined.
466
467    type UI_Vector is array (Pos range <>) of Int;
468    --  Vector containing the integer values of a Uint value
469
470    --  Note: An earlier version of this package used pointers of arrays
471    --  of Ints (dynamically allocated) for the Uint type. The change
472    --  leads to a few less natural idioms used throughout this code, but
473    --  eliminates all uses of the heap except for the table package itself.
474    --  For example, Uint parameters are often converted to UI_Vectors for
475    --  internal manipulation. This is done by creating the local UI_Vector
476    --  using the function N_Digits on the Uint to find the size needed for
477    --  the vector, and then calling Init_Operand to copy the values out
478    --  of the table into the vector.
479
480    type Uint_Entry is record
481       Length : Pos;
482       --  Length of entry in Udigits table in digits (i.e. in words)
483
484       Loc : Int;
485       --  Starting location in Udigits table of this Uint value
486    end record;
487
488    package Uints is new Table.Table (
489      Table_Component_Type => Uint_Entry,
490      Table_Index_Type     => Uint,
491      Table_Low_Bound      => Uint_First_Entry,
492      Table_Initial        => Alloc.Uints_Initial,
493      Table_Increment      => Alloc.Uints_Increment,
494      Table_Name           => "Uints");
495
496    package Udigits is new Table.Table (
497      Table_Component_Type => Int,
498      Table_Index_Type     => Int,
499      Table_Low_Bound      => 0,
500      Table_Initial        => Alloc.Udigits_Initial,
501      Table_Increment      => Alloc.Udigits_Increment,
502      Table_Name           => "Udigits");
503
504    --  Note: the reason these tables are defined here in the private part of
505    --  the spec, rather than in the body, is that they are refrerenced
506    --  directly by gigi.
507
508 end Uintp;