libdecnumber/decNumber.h

   1 /* Decimal number arithmetic module header for the decNumber C Library.
   2    Copyright (C) 2005-2023 Free Software Foundation, Inc.
   3    Contributed by IBM Corporation.  Author Mike Cowlishaw.
   4
   5    This file is part of GCC.
   6
   7    GCC is free software; you can redistribute it and/or modify it under
   8    the terms of the GNU General Public License as published by the Free
   9    Software Foundation; either version 3, or (at your option) any later
  10    version.
  11
  12    GCC is distributed in the hope that it will be useful, but WITHOUT ANY
  13    WARRANTY; without even the implied warranty of MERCHANTABILITY or
  14    FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  15    for more details.
  16
  17 Under Section 7 of GPL version 3, you are granted additional
  18 permissions described in the GCC Runtime Library Exception, version
  19 3.1, as published by the Free Software Foundation.
  20
  21 You should have received a copy of the GNU General Public License and
  22 a copy of the GCC Runtime Library Exception along with this program;
  23 see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see
  24 <http://www.gnu.org/licenses/>.  */
  25
  26 /* ------------------------------------------------------------------ */
  27 /* Decimal Number arithmetic module header                            */
  28 /* ------------------------------------------------------------------ */
  29
  30 #if !defined(DECNUMBER)
  31   #define DECNUMBER
  32   #define DECNAME     "decNumber"                       /* Short name */
  33   #define DECFULLNAME "Decimal Number Module"         /* Verbose name */
  34   #define DECAUTHOR   "Mike Cowlishaw"                /* Who to blame */
  35
  36   #if !defined(DECCONTEXT)
  37     #include "decContext.h"
  38   #endif
  39
  40   /* Bit settings for decNumber.bits                                  */
  41   #define DECNEG    0x80      /* Sign; 1=negative, 0=positive or zero */
  42   #define DECINF    0x40      /* 1=Infinity                           */
  43   #define DECNAN    0x20      /* 1=NaN                                */
  44   #define DECSNAN   0x10      /* 1=sNaN                               */
  45   /* The remaining bits are reserved; they must be 0                  */
  46   #define DECSPECIAL (DECINF|DECNAN|DECSNAN) /* any special value     */
  47
  48   /* Define the decNumber data structure.  The size and shape of the  */
  49   /* units array in the structure is determined by the following      */
  50   /* constant.  This must not be changed without recompiling the      */
  51   /* decNumber library modules. */
  52
  53   #define DECDPUN 3           /* DECimal Digits Per UNit [must be >0  */
  54                               /* and <10; 3 or powers of 2 are best]. */
  55
  56   /* DECNUMDIGITS is the default number of digits that can be held in */
  57   /* the structure.  If undefined, 1 is assumed and it is assumed     */
  58   /* that the structure will be immediately followed by extra space,  */
  59   /* as required.  DECNUMDIGITS is always >0.                         */
  60   #if !defined(DECNUMDIGITS)
  61     #define DECNUMDIGITS 1
  62   #endif
  63
  64   /* The size (integer data type) of each unit is determined by the   */
  65   /* number of digits it will hold.                                   */
  66   #if   DECDPUN<=2
  67     #define decNumberUnit uint8_t
  68   #elif DECDPUN<=4
  69     #define decNumberUnit uint16_t
  70   #else
  71     #define decNumberUnit uint32_t
  72   #endif
  73   /* The number of units needed is ceil(DECNUMDIGITS/DECDPUN)         */
  74   #define DECNUMUNITS ((DECNUMDIGITS+DECDPUN-1)/DECDPUN)
  75
  76   /* The data structure... */
  77   typedef struct {
  78     int32_t digits;      /* Count of digits in the coefficient; >0    */
  79     int32_t exponent;    /* Unadjusted exponent, unbiased, in         */
  80                          /* range: -1999999997 through 999999999      */
  81     uint8_t bits;        /* Indicator bits (see above)                */
  82                          /* Coefficient, from least significant unit  */
  83     decNumberUnit lsu[DECNUMUNITS];
  84     } decNumber;
  85
  86   /* Notes:                                                           */
  87   /* 1. If digits is > DECDPUN then there will one or more            */
  88   /*    decNumberUnits immediately following the first element of lsu.*/
  89   /*    These contain the remaining (more significant) digits of the  */
  90   /*    number, and may be in the lsu array, or may be guaranteed by  */
  91   /*    some other mechanism (such as being contained in another      */
  92   /*    structure, or being overlaid on dynamically allocated         */
  93   /*    storage).                                                     */
  94   /*                                                                  */
  95   /*    Each integer of the coefficient (except potentially the last) */
  96   /*    contains DECDPUN digits (e.g., a value in the range 0 through */
  97   /*    99999999 if DECDPUN is 8, or 0 through 999 if DECDPUN is 3).  */
  98   /*                                                                  */
  99   /* 2. A decNumber converted to a string may need up to digits+14    */
 100   /*    characters.  The worst cases (non-exponential and exponential */
 101   /*    formats) are -0.00000{9...}# and -9.{9...}E+999999999#        */
 102   /*    (where # is '\0')                                             */
 103
 104
 105   /* ---------------------------------------------------------------- */
 106   /* decNumber public functions and macros                            */
 107   /* ---------------------------------------------------------------- */
 108
 109   #include "decNumberSymbols.h"
 110
 111   #ifdef __cplusplus
 112   extern "C" {
 113   #endif
 114
 115   /* Conversions                                                      */
 116   decNumber * decNumberFromInt32(decNumber *, int32_t);
 117   decNumber * decNumberFromUInt32(decNumber *, uint32_t);
 118   decNumber * decNumberFromString(decNumber *, const char *, decContext *);
 119   char      * decNumberToString(const decNumber *, char *);
 120   char      * decNumberToEngString(const decNumber *, char *);
 121   uint32_t    decNumberToUInt32(const decNumber *, decContext *);
 122   int32_t     decNumberToInt32(const decNumber *, decContext *);
 123   uint8_t   * decNumberGetBCD(const decNumber *, uint8_t *);
 124   decNumber * decNumberSetBCD(decNumber *, const uint8_t *, uint32_t);
 125
 126   /* Operators and elementary functions                               */
 127   decNumber * decNumberAbs(decNumber *, const decNumber *, decContext *);
 128   decNumber * decNumberAdd(decNumber *, const decNumber *, const decNumber *, decContext *);
 129   decNumber * decNumberAnd(decNumber *, const decNumber *, const decNumber *, decContext *);
 130   decNumber * decNumberCompare(decNumber *, const decNumber *, const decNumber *, decContext *);
 131   decNumber * decNumberCompareSignal(decNumber *, const decNumber *, const decNumber *, decContext *);
 132   decNumber * decNumberCompareTotal(decNumber *, const decNumber *, const decNumber *, decContext *);
 133   decNumber * decNumberCompareTotalMag(decNumber *, const decNumber *, const decNumber *, decContext *);
 134   decNumber * decNumberDivide(decNumber *, const decNumber *, const decNumber *, decContext *);
 135   decNumber * decNumberDivideInteger(decNumber *, const decNumber *, const decNumber *, decContext *);
 136   decNumber * decNumberExp(decNumber *, const decNumber *, decContext *);
 137   decNumber * decNumberFMA(decNumber *, const decNumber *, const decNumber *, const decNumber *, decContext *);
 138   decNumber * decNumberInvert(decNumber *, const decNumber *, decContext *);
 139   decNumber * decNumberLn(decNumber *, const decNumber *, decContext *);
 140   decNumber * decNumberLogB(decNumber *, const decNumber *, decContext *);
 141   decNumber * decNumberLog10(decNumber *, const decNumber *, decContext *);
 142   decNumber * decNumberMax(decNumber *, const decNumber *, const decNumber *, decContext *);
 143   decNumber * decNumberMaxMag(decNumber *, const decNumber *, const decNumber *, decContext *);
 144   decNumber * decNumberMin(decNumber *, const decNumber *, const decNumber *, decContext *);
 145   decNumber * decNumberMinMag(decNumber *, const decNumber *, const decNumber *, decContext *);
 146   decNumber * decNumberMinus(decNumber *, const decNumber *, decContext *);
 147   decNumber * decNumberMultiply(decNumber *, const decNumber *, const decNumber *, decContext *);
 148   decNumber * decNumberNormalize(decNumber *, const decNumber *, decContext *);
 149   decNumber * decNumberOr(decNumber *, const decNumber *, const decNumber *, decContext *);
 150   decNumber * decNumberPlus(decNumber *, const decNumber *, decContext *);
 151   decNumber * decNumberPower(decNumber *, const decNumber *, const decNumber *, decContext *);
 152   decNumber * decNumberQuantize(decNumber *, const decNumber *, const decNumber *, decContext *);
 153   decNumber * decNumberReduce(decNumber *, const decNumber *, decContext *);
 154   decNumber * decNumberRemainder(decNumber *, const decNumber *, const decNumber *, decContext *);
 155   decNumber * decNumberRemainderNear(decNumber *, const decNumber *, const decNumber *, decContext *);
 156   decNumber * decNumberRescale(decNumber *, const decNumber *, const decNumber *, decContext *);
 157   decNumber * decNumberRotate(decNumber *, const decNumber *, const decNumber *, decContext *);
 158   decNumber * decNumberSameQuantum(decNumber *, const decNumber *, const decNumber *);
 159   decNumber * decNumberScaleB(decNumber *, const decNumber *, const decNumber *, decContext *);
 160   decNumber * decNumberShift(decNumber *, const decNumber *, const decNumber *, decContext *);
 161   decNumber * decNumberSquareRoot(decNumber *, const decNumber *, decContext *);
 162   decNumber * decNumberSubtract(decNumber *, const decNumber *, const decNumber *, decContext *);
 163   decNumber * decNumberToIntegralExact(decNumber *, const decNumber *, decContext *);
 164   decNumber * decNumberToIntegralValue(decNumber *, const decNumber *, decContext *);
 165   decNumber * decNumberXor(decNumber *, const decNumber *, const decNumber *, decContext *);
 166
 167   /* Utilities                                                        */
 168   enum decClass decNumberClass(const decNumber *, decContext *);
 169   const char * decNumberClassToString(enum decClass);
 170   decNumber  * decNumberCopy(decNumber *, const decNumber *);
 171   decNumber  * decNumberCopyAbs(decNumber *, const decNumber *);
 172   decNumber  * decNumberCopyNegate(decNumber *, const decNumber *);
 173   decNumber  * decNumberCopySign(decNumber *, const decNumber *, const decNumber *);
 174   decNumber  * decNumberNextMinus(decNumber *, const decNumber *, decContext *);
 175   decNumber  * decNumberNextPlus(decNumber *, const decNumber *, decContext *);
 176   decNumber  * decNumberNextToward(decNumber *, const decNumber *, const decNumber *, decContext *);
 177   decNumber  * decNumberTrim(decNumber *);
 178   const char * decNumberVersion(void);
 179   decNumber  * decNumberZero(decNumber *);
 180
 181   /* Functions for testing decNumbers (normality depends on context)  */
 182   int32_t decNumberIsNormal(const decNumber *, decContext *);
 183   int32_t decNumberIsSubnormal(const decNumber *, decContext *);
 184
 185   /* Macros for testing decNumber *dn                                 */
 186   #define decNumberIsCanonical(dn) (1)  /* All decNumbers are saintly */
 187   #define decNumberIsFinite(dn)    (((dn)->bits&DECSPECIAL)==0)
 188   #define decNumberIsInfinite(dn)  (((dn)->bits&DECINF)!=0)
 189   #define decNumberIsNaN(dn)       (((dn)->bits&(DECNAN|DECSNAN))!=0)
 190   #define decNumberIsNegative(dn)  (((dn)->bits&DECNEG)!=0)
 191   #define decNumberIsQNaN(dn)      (((dn)->bits&(DECNAN))!=0)
 192   #define decNumberIsSNaN(dn)      (((dn)->bits&(DECSNAN))!=0)
 193   #define decNumberIsSpecial(dn)   (((dn)->bits&DECSPECIAL)!=0)
 194   #define decNumberIsZero(dn)      (*(dn)->lsu==0 \
 195                                     && (dn)->digits==1 \
 196                                     && (((dn)->bits&DECSPECIAL)==0))
 197   #define decNumberRadix(dn)       (10)
 198
 199   #ifdef __cplusplus
 200   }
 201   #endif
 202
 203 #endif