sal/inc/rtl/math.h

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: math.h,v $
  10  * $Revision: 1.5 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30
  31 #if !defined INCLUDED_RTL_MATH_H
  32 #define INCLUDED_RTL_MATH_H
  33
  34 #include "rtl/ustring.h"
  35 #include "sal/types.h"
  36
  37 #if defined __cplusplus
  38 extern "C" {
  39 #endif /* __cplusplus */
  40
  41 /** Formatting modes for rtl_math_doubleToString and rtl_math_doubleToUString
  42     and rtl_math_doubleToUStringBuffer.
  43  */
  44 enum rtl_math_StringFormat
  45 {
  46     /** Like sprintf() %E.
  47      */
  48     rtl_math_StringFormat_E,
  49
  50     /** Like sprintf() %f.
  51      */
  52     rtl_math_StringFormat_F,
  53
  54     /** Like sprintf() %G, 'F' or 'E' format is used depending on which one is
  55         more compact.
  56     */
  57     rtl_math_StringFormat_G,
  58
  59     /** Automatic, 'F' or 'E' format is used depending on the numeric value to
  60         be formatted.
  61      */
  62     rtl_math_StringFormat_Automatic,
  63
  64     /** @internal
  65      */
  66     rtl_math_StringFormat_FORCE_EQUAL_SIZE = SAL_MAX_ENUM
  67 };
  68
  69 /** Status for rtl_math_stringToDouble and rtl_math_uStringToDouble.
  70  */
  71 enum rtl_math_ConversionStatus
  72 {
  73     /** Conversion was successful.
  74      */
  75     rtl_math_ConversionStatus_Ok,
  76
  77     /** Conversion caused overflow or underflow.
  78      */
  79     rtl_math_ConversionStatus_OutOfRange,
  80
  81     /** @internal
  82      */
  83     rtl_math_ConversionStatus_FORCE_EQUAL_SIZE = SAL_MAX_ENUM
  84 };
  85
  86 /** Rounding modes for rtl_math_round.
  87  */
  88 enum rtl_math_RoundingMode
  89 {
  90     /** Like HalfUp, but corrects roundoff errors, preferred.
  91      */
  92     rtl_math_RoundingMode_Corrected,
  93
  94     /** Floor of absolute value, signed return (commercial).
  95      */
  96     rtl_math_RoundingMode_Down,
  97
  98     /** Ceil of absolute value, signed return (commercial).
  99      */
 100     rtl_math_RoundingMode_Up,
 101
 102     /** Floor of signed value.
 103      */
 104     rtl_math_RoundingMode_Floor,
 105
 106     /** Ceil of signed value.
 107      */
 108     rtl_math_RoundingMode_Ceiling,
 109
 110     /** Frac <= 0.5 ? floor of abs : ceil of abs, signed return.
 111      */
 112     rtl_math_RoundingMode_HalfDown,
 113
 114     /** Frac < 0.5 ? floor of abs : ceil of abs, signed return (mathematical).
 115      */
 116     rtl_math_RoundingMode_HalfUp,
 117
 118     /** IEEE rounding mode (statistical).
 119      */
 120     rtl_math_RoundingMode_HalfEven,
 121
 122     /** @internal
 123      */
 124     rtl_math_RoundingMode_FORCE_EQUAL_SIZE = SAL_MAX_ENUM
 125 };
 126
 127 /** Special decimal places constants for rtl_math_doubleToString and
 128     rtl_math_doubleToUString and rtl_math_doubleToUStringBuffer.
 129  */
 130 enum rtl_math_DecimalPlaces
 131 {
 132     /** Value to be used with rtl_math_StringFormat_Automatic.
 133      */
 134     rtl_math_DecimalPlaces_Max = 0x7ffffff,
 135
 136     /** Value to be used with rtl_math_StringFormat_G.
 137         In fact the same value as rtl_math_DecimalPlaces_Max, just an alias for
 138         better understanding.
 139      */
 140     rtl_math_DecimalPlaces_DefaultSignificance = 0x7ffffff
 141 };
 142
 143
 144 /** Conversions analogous to sprintf() using internal rounding.
 145
 146     +/-HUGE_VAL are converted to "1.#INF" and "-1.#INF", NAN values are
 147     converted to "1.#NAN" and "-1.#NAN", of course using cDecSeparator instead
 148     of '.'.
 149
 150     @param pResult
 151     Returns the resulting byte string.  Must itself not be null, and must point
 152     to either null or a valid string.
 153
 154     @param pResultCapacity
 155     If null, pResult is considered to point to immutable strings, and a new
 156     string will be allocated in pResult.
 157     If non-null, it points to the current capacity of pResult, which is
 158     considered to point to a string buffer (pResult must not itself be null in
 159     this case, and must point to a string that has room for the given capacity).
 160     The string representation of the given double value is inserted into pResult
 161     at position nResultOffset.  If pResult's current capacity is too small, a
 162     new string buffer will be allocated in pResult as necessary, and
 163     pResultCapacity will contain the new capacity on return.
 164
 165     @param nResultOffset
 166     If pResult is used as a string buffer (i.e., pResultCapacity is non-null),
 167     nResultOffset specifies the insertion offset within the buffer.  Ignored
 168     otherwise.
 169
 170     @param fValue
 171     The value to convert.
 172
 173     @param eFormat
 174     The format to use, one of rtl_math_StringFormat.
 175
 176     @param nDecPlaces
 177     The number of decimals to be generated.  Effectively fValue is rounded at
 178     this position, specifying nDecPlaces <= 0 accordingly rounds the value
 179     before the decimal point and fills with zeros.
 180     If eFormat == rtl_math_StringFormat_Automatic and nDecPlaces ==
 181     rtl_math_DecimalPlaces_Max, the highest number of significant decimals
 182     possible is generated.
 183     If eFormat == rtl_math_StringFormat_G, nDecPlaces specifies the number of
 184     significant digits instead.  If nDecPlaces ==
 185     rtl_math_DecimalPlaces_DefaultSignificance, the default number (currently 6
 186     as implemented by most libraries) of significant digits is generated.
 187     According to the ANSI C90 standard the E style will be used only if the
 188     exponent resulting from the conversion is less than -4 or greater than or
 189     equal to the precision.  However, as opposed to the ANSI standard, trailing
 190     zeros are not necessarily removed from the fractional portion of the result
 191     unless bEraseTrailingDecZeros == true was specified.
 192
 193     @param cDecSeparator
 194     The decimal separator.
 195
 196     @param pGroups
 197     Either null (no grouping is used), or a null-terminated list of group
 198     lengths.  Each group length must be strictly positive.  If the number of
 199     digits in a conversion exceeds the specified range, the last (highest) group
 200     length is repeated as needed.  Values are applied from right to left, for a
 201     grouping of 1,00,00,000 you'd have to specify pGroups={3,2,0}.
 202
 203     @param cGroupSeparator
 204     The group separator.  Ignored if pGroups is null.
 205
 206     @param bEraseTrailingDecZeros
 207     Trailing zeros in decimal places are erased.
 208  */
 209 void SAL_CALL rtl_math_doubleToString(rtl_String ** pResult,
 210                                       sal_Int32 * pResultCapacity,
 211                                       sal_Int32 nResultOffset, double fValue,
 212                                       enum rtl_math_StringFormat eFormat,
 213                                       sal_Int32 nDecPlaces,
 214                                       sal_Char cDecSeparator,
 215                                       sal_Int32 const * pGroups,
 216                                       sal_Char cGroupSeparator,
 217                                       sal_Bool bEraseTrailingDecZeros)
 218     SAL_THROW_EXTERN_C();
 219
 220 /** Conversions analogous to sprintf() using internal rounding.
 221
 222     +/-HUGE_VAL are converted to "1.#INF" and "-1.#INF", NAN values are
 223     converted to "1.#NAN" and "-1.#NAN", of course using cDecSeparator instead
 224     of '.'.
 225
 226     @param pResult
 227     Returns the resulting Unicode string.  Must itself not be null, and must
 228     point to either null or a valid string.
 229
 230     @param pResultCapacity
 231     If null, pResult is considered to point to immutable strings, and a new
 232     string will be allocated in pResult.
 233     If non-null, it points to the current capacity of pResult, which is
 234     considered to point to a string buffer (pResult must not itself be null in
 235     this case, and must point to a string that has room for the given capacity).
 236     The string representation of the given double value is inserted into pResult
 237     at position nResultOffset.  If pResult's current capacity is too small, a
 238     new string buffer will be allocated in pResult as necessary, and
 239     pResultCapacity will contain the new capacity on return.
 240
 241     @param nResultOffset
 242     If pResult is used as a string buffer (i.e., pResultCapacity is non-null),
 243     nResultOffset specifies the insertion offset within the buffer.  Ignored
 244     otherwise.
 245
 246     @param fValue
 247     The value to convert.
 248
 249     @param eFormat
 250     The format to use, one of rtl_math_StringFormat.
 251
 252     @param nDecPlaces
 253     The number of decimals to be generated.  Effectively fValue is rounded at
 254     this position, specifying nDecPlaces <= 0 accordingly rounds the value
 255     before the decimal point and fills with zeros.
 256     If eFormat == rtl_math_StringFormat_Automatic and nDecPlaces ==
 257     rtl_math_DecimalPlaces_Max, the highest number of significant decimals
 258     possible is generated.
 259     If eFormat == rtl_math_StringFormat_G, nDecPlaces specifies the number of
 260     significant digits instead.  If nDecPlaces ==
 261     rtl_math_DecimalPlaces_DefaultSignificance, the default number (currently 6
 262     as implemented by most libraries) of significant digits is generated.
 263     According to the ANSI C90 standard the E style will be used only if the
 264     exponent resulting from the conversion is less than -4 or greater than or
 265     equal to the precision.  However, as opposed to the ANSI standard, trailing
 266     zeros are not necessarily removed from the fractional portion of the result
 267     unless bEraseTrailingDecZeros == true was specified.
 268
 269     @param cDecSeparator
 270     The decimal separator.
 271
 272     @param pGroups
 273     Either null (no grouping is used), or a null-terminated list of group
 274     lengths.  Each group length must be strictly positive.  If the number of
 275     digits in a conversion exceeds the specified range, the last (highest) group
 276     length is repeated as needed.  Values are applied from right to left, for a
 277     grouping of 1,00,00,000 you'd have to specify pGroups={3,2,0}.
 278
 279     @param cGroupSeparator
 280     The group separator.  Ignored if pGroups is null.
 281
 282     @param bEraseTrailingDecZeros
 283     Trailing zeros in decimal places are erased.
 284  */
 285 void SAL_CALL rtl_math_doubleToUString(rtl_uString ** pResult,
 286                                        sal_Int32 * pResultCapacity,
 287                                        sal_Int32 nResultOffset, double fValue,
 288                                        enum rtl_math_StringFormat eFormat,
 289                                        sal_Int32 nDecPlaces,
 290                                        sal_Unicode cDecSeparator,
 291                                        sal_Int32 const * pGroups,
 292                                        sal_Unicode cGroupSeparator,
 293                                        sal_Bool bEraseTrailingDecZeros)
 294     SAL_THROW_EXTERN_C();
 295
 296 /** Conversion analogous to strtod(), convert a string representing a
 297     decimal number into a double value.
 298
 299     Leading tabs (0x09) and spaces (0x20) are eaten.  Overflow returns
 300     +/-HUGE_VAL, underflow 0.  In both cases pStatus is set to
 301     rtl_math_ConversionStatus_OutOfRange, otherwise to
 302     rtl_math_ConversionStatus_Ok.  "+/-1.#INF" is recognized as +/-HUGE_VAL,
 303     pStatus is set to rtl_math_ConversionStatus_OutOfRange.  "+/-1.#NAN" is
 304     recognized and the value is set to +/-NAN, pStatus is set to
 305     rtl_math_ConversionStatus_Ok.
 306
 307     @param pBegin
 308     Points to the start of the byte string to convert.  Must not be null.
 309
 310     @param pEnd
 311     Points one past the end of the byte string to convert.  The condition
 312     pEnd >= pBegin must hold.
 313
 314     @param cDecSeparator
 315     The decimal separator.
 316
 317     @param cGroupSeparator
 318     The group (aka thousands) separator.
 319
 320     @param pStatus
 321     If non-null, returns the status of the conversion.
 322
 323     @param pParsedEnd
 324     If non-null, returns one past the position of the last character parsed
 325     away.  Thus if [pBegin..pEnd) only contains the numerical string to be
 326     parsed, *pParsedEnd == pEnd on return.
 327  */
 328 double SAL_CALL rtl_math_stringToDouble(
 329     sal_Char const * pBegin, sal_Char const * pEnd, sal_Char cDecSeparator,
 330     sal_Char cGroupSeparator, enum rtl_math_ConversionStatus * pStatus,
 331     sal_Char const ** pParsedEnd) SAL_THROW_EXTERN_C();
 332
 333 /** Conversion analogous to strtod(), convert a string representing a
 334     decimal number into a double value.
 335
 336     Leading tabs (U+0009) and spaces (U+0020) are eaten.  Overflow returns
 337     +/-HUGE_VAL, underflow 0.  In both cases pStatus is set to
 338     rtl_math_ConversionStatus_OutOfRange, otherwise to
 339     rtl_math_ConversionStatus_Ok.  "+/-1.#INF" is recognized as +/-HUGE_VAL,
 340     pStatus is set to rtl_math_ConversionStatus_OutOfRange.  "+/-1.#NAN" is
 341     recognized and the value is set to +/-NAN, pStatus is set to
 342     rtl_math_ConversionStatus_Ok.
 343
 344     @param pBegin
 345     Points to the start of the Unicode string to convert.  Must not be null.
 346
 347     @param pEnd
 348     Points one past the end of the Unicode string to convert.  The condition
 349     pEnd >= pBegin must hold.
 350
 351     @param cDecSeparator
 352     The decimal separator.
 353
 354     @param cGroupSeparator
 355     The group (aka thousands) separator.
 356
 357     @param pStatus
 358     If non-null, returns the status of the conversion.
 359
 360     @param pParsedEnd
 361     If non-null, returns one past the position of the last character parsed
 362     away.  Thus if [pBegin..pEnd) only contains the numerical string to be
 363     parsed, *pParsedEnd == pEnd on return.
 364  */
 365 double SAL_CALL rtl_math_uStringToDouble(
 366     sal_Unicode const * pBegin, sal_Unicode const * pEnd,
 367     sal_Unicode cDecSeparator, sal_Unicode cGroupSeparator,
 368     enum rtl_math_ConversionStatus * pStatus, sal_Unicode const ** pParsedEnd)
 369     SAL_THROW_EXTERN_C();
 370
 371 /** Rounds a double value.
 372
 373     @param fValue
 374     Specifies the value to be rounded.
 375
 376     @param nDecPlaces
 377     Specifies the decimal place where rounding occurs.  Must be in the range
 378     -20 to +20, inclusive.  Negative if rounding occurs before the decimal
 379     point.
 380
 381     @param eMode
 382     Specifies the rounding mode.
 383  */
 384 double SAL_CALL rtl_math_round(double fValue, int nDecPlaces,
 385                                enum rtl_math_RoundingMode eMode)
 386     SAL_THROW_EXTERN_C();
 387
 388 /** Scales fVal to a power of 10 without calling pow() or div() for nExp values
 389     between -16 and +16, providing a faster method.
 390
 391     @param fValue
 392     The value to be raised.
 393
 394     @param nExp
 395     The exponent.
 396
 397     @return
 398     fVal * pow(10.0, nExp)
 399  */
 400 double SAL_CALL rtl_math_pow10Exp(double fValue, int nExp) SAL_THROW_EXTERN_C();
 401
 402 /** Rounds value to 15 significant decimal digits.
 403
 404     @param fValue
 405     The value to be rounded.
 406   */
 407 double SAL_CALL rtl_math_approxValue(double fValue) SAL_THROW_EXTERN_C();
 408
 409 /** Returns more accurate e^x-1 for x near 0 than calculating directly.
 410
 411     expm1 is part of the C99 standard, but not provided by some compilers.
 412
 413     @param fValue
 414     The value x in the term e^x-1.
 415   */
 416 double SAL_CALL rtl_math_expm1(double fValue) SAL_THROW_EXTERN_C();
 417
 418 /** Returns more accurate log(1+x) for x near 0 than calculating directly.
 419
 420     log1p is part of the C99 standard, but not provided by some compilers.
 421
 422     @param fValue
 423     The value x in the term log(1+x).
 424   */
 425 double SAL_CALL rtl_math_log1p(double fValue) SAL_THROW_EXTERN_C();
 426
 427 /** Returns more accurate atanh(x) for x near 0 than calculating
 428     0.5*log((1+x)/(1-x)).
 429
 430     atanh is part of the C99 standard, but not provided by some compilers.
 431
 432     @param fValue
 433     The value x in the term atanh(x).
 434   */
 435 double SAL_CALL rtl_math_atanh(double fValue) SAL_THROW_EXTERN_C();
 436
 437 #if defined __cplusplus
 438 }
 439 #endif /* __cplusplus */
 440
 441 #endif /* INCLUDED_RTL_MATH_H */