gcc/ada/libgnat/s-genbig.ads

   1 ------------------------------------------------------------------------------
   2 --                                                                          --
   3 --                         GNAT COMPILER COMPONENTS                         --
   4 --                                                                          --
   5 --               S Y S T E M . G E N E R I C _ B I G N U M S                --
   6 --                                                                          --
   7 --                                 S p e c                                  --
   8 --                                                                          --
   9 --            Copyright (C) 2012-2023, Free Software Foundation, Inc.       --
  10 --                                                                          --
  11 -- GNAT is free software;  you can  redistribute it  and/or modify it under --
  12 -- terms of the  GNU General Public License as published  by the Free Soft- --
  13 -- ware  Foundation;  either version 3,  or (at your option) any later ver- --
  14 -- sion.  GNAT is distributed in the hope that it will be useful, but WITH- --
  15 -- OUT ANY WARRANTY;  without even the  implied warranty of MERCHANTABILITY --
  16 -- or FITNESS FOR A PARTICULAR PURPOSE.                                     --
  17 --                                                                          --
  18 -- As a special exception under Section 7 of GPL version 3, you are granted --
  19 -- additional permissions described in the GCC Runtime Library Exception,   --
  20 -- version 3.1, as published by the Free Software Foundation.               --
  21 --                                                                          --
  22 -- You should have received a copy of the GNU General Public License and    --
  23 -- a copy of the GCC Runtime Library Exception along with this program;     --
  24 -- see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see    --
  25 -- <http://www.gnu.org/licenses/>.                                          --
  26 --                                                                          --
  27 -- GNAT was originally developed  by the GNAT team at  New York University. --
  28 -- Extensive contributions were provided by Ada Core Technologies Inc.      --
  29 --                                                                          --
  30 ------------------------------------------------------------------------------
  31
  32 --  This package provides arbitrary precision signed integer arithmetic
  33 --  and can be used either built into the compiler via System.Bignums or to
  34 --  implement a default version of Ada.Numerics.Big_Numbers.Big_Integers.
  35
  36 with Interfaces;
  37 with System.Shared_Bignums;
  38
  39 generic
  40    type Big_Integer is private;
  41
  42    with function Allocate_Big_Integer
  43           (D : Shared_Bignums.Digit_Vector; Neg : Boolean) return Big_Integer;
  44    --  Allocate Bignum value with the given contents
  45
  46    with procedure Free_Big_Integer (X : in out Big_Integer);
  47    --  Free the memory associated with X
  48
  49    with function To_Bignum
  50           (X : aliased in out Big_Integer) return Shared_Bignums.Bignum;
  51    --  Convert the given Big_Integer to a Bignum
  52
  53 package System.Generic_Bignums is
  54    pragma Preelaborate;
  55
  56    subtype Bignum is Shared_Bignums.Bignum;
  57
  58    --  Note that this package never shares an allocated Big_Integer value, so
  59    --  so for example for X + 0, a copy of X is returned, not X itself.
  60
  61    --  Note: none of the subprograms in this package modify the Bignum_Data
  62    --  records referenced by Bignum arguments of mode IN.
  63
  64    function Big_Add (X, Y : Bignum) return Big_Integer;  --  "+"
  65    function Big_Sub (X, Y : Bignum) return Big_Integer;  --  "-"
  66    function Big_Mul (X, Y : Bignum) return Big_Integer;  --  "*"
  67    function Big_Div (X, Y : Bignum) return Big_Integer;  --  "/"
  68    function Big_Exp (X, Y : Bignum) return Big_Integer;  --  "**"
  69    function Big_Mod (X, Y : Bignum) return Big_Integer;  --  "mod"
  70    function Big_Rem (X, Y : Bignum) return Big_Integer;  --  "rem"
  71    function Big_Neg (X    : Bignum) return Big_Integer;  --  "-"
  72    function Big_Abs (X    : Bignum) return Big_Integer;  --  "abs"
  73    --  Perform indicated arithmetic operation on bignum values. No exception
  74    --  raised except for Div/Mod/Rem by 0 which raises Constraint_Error with
  75    --  an appropriate message.
  76
  77    function Big_And (X, Y : Bignum) return Big_Integer;  --  "and"
  78    function Big_Or  (X, Y : Bignum) return Big_Integer;  --  "or"
  79    --  Perform indicated bitwise operation on big num values.
  80    --  The negative flags of X and Y are also combined.
  81
  82    function Big_Shift_Left  (X : Bignum; Amount : Natural) return Big_Integer;
  83    function Big_Shift_Right (X : Bignum; Amount : Natural) return Big_Integer;
  84    --  Perform indicated bitwise operation on big num values.
  85    --  Constraint_Error is raised if X is negative.
  86
  87    function Big_EQ  (X, Y : Bignum) return Boolean;  -- "="
  88    function Big_NE  (X, Y : Bignum) return Boolean;  -- "/="
  89    function Big_GE  (X, Y : Bignum) return Boolean;  -- ">="
  90    function Big_LE  (X, Y : Bignum) return Boolean;  -- "<="
  91    function Big_GT  (X, Y : Bignum) return Boolean;  --  ">"
  92    function Big_LT  (X, Y : Bignum) return Boolean;  --  "<"
  93    --  Perform indicated comparison on bignums, returning result as Boolean.
  94    --  No exception raised for any input arguments.
  95
  96    function Bignum_In_LLI_Range (X : Bignum) return Boolean;
  97    --  Returns True if the Bignum value is in the range of Long_Long_Integer,
  98    --  so that a call to From_Bignum is guaranteed not to raise an exception.
  99
 100    function To_Bignum (X : Long_Long_Integer) return Big_Integer;
 101    --  Convert Long_Long_Integer to a big integer. No exception can be raised
 102    --  for any input argument.
 103
 104    function To_Bignum (X : Long_Long_Long_Integer) return Big_Integer;
 105    --  Convert Long_Long_Long_Integer to a big integer. No exception can be
 106    --  raised.
 107
 108    function To_Bignum (X : Interfaces.Unsigned_64) return Big_Integer;
 109    --  Convert Unsigned_64 to a big integer. No exception can be raised for any
 110    --  input argument.
 111
 112    function To_Bignum (X : Interfaces.Unsigned_128) return Big_Integer;
 113    --  Convert Unsigned_128 to a big integer. No exception can be raised for
 114    --  any input argument.
 115
 116    function From_Bignum (X : Bignum) return Long_Long_Integer;
 117    --  Convert Bignum to Long_Long_Integer. Constraint_Error raised with
 118    --  appropriate message if value is out of range of Long_Long_Integer.
 119
 120    function To_String
 121      (X : Bignum; Width : Natural := 0; Base : Positive := 10)
 122       return String;
 123    --  Return the image of X, based on the given Width and Base, as defined
 124    --  in the RM for Ada.Text_IO. Base should really be in the range 2 .. 16.
 125
 126    function Is_Zero (X : Bignum) return Boolean;
 127    --  Return True if X = 0
 128
 129 end System.Generic_Bignums;