include/rtl/math.h

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19
  20 #ifndef INCLUDED_RTL_MATH_H
  21 #define INCLUDED_RTL_MATH_H
  22
  23 #include "sal/config.h"
  24
  25 #include "rtl/ustring.h"
  26 #include "sal/saldllapi.h"
  27 #include "sal/types.h"
  28
  29 #if defined __cplusplus
  30 extern "C" {
  31 #endif /* __cplusplus */
  32
  33 /** Formatting modes for rtl_math_doubleToString and rtl_math_doubleToUString
  34     and rtl_math_doubleToUStringBuffer.
  35  */
  36 enum rtl_math_StringFormat
  37 {
  38     /** Like sprintf() %E.
  39      */
  40     rtl_math_StringFormat_E,
  41
  42     /** Like sprintf() %f.
  43      */
  44     rtl_math_StringFormat_F,
  45
  46     /** Like sprintf() %G, 'F' or 'E' format is used depending on which one is
  47         more compact.
  48     */
  49     rtl_math_StringFormat_G,
  50
  51     /** Automatic, 'F' or 'E' format is used depending on the numeric value to
  52         be formatted.
  53      */
  54     rtl_math_StringFormat_Automatic,
  55
  56     /** Same 'E', but with only 1 minimum digits in exponent.
  57         @since LibreOffice 5.0
  58      */
  59     rtl_math_StringFormat_E1,
  60
  61     /** Same 'E', but with only 2 minimum digits in exponent.
  62         @since LibreOffice 5.0
  63      */
  64     rtl_math_StringFormat_E2,
  65
  66     /** Same 'G', but with only 1 minimum digits in exponent.
  67         @since LibreOffice 5.0
  68      */
  69     rtl_math_StringFormat_G1,
  70
  71     /** Same 'G', but with only 2 minimum digits in exponent.
  72         @since LibreOffice 5.0
  73      */
  74     rtl_math_StringFormat_G2,
  75
  76     /** @cond INTERNAL */
  77     rtl_math_StringFormat_FORCE_EQUAL_SIZE = SAL_MAX_ENUM
  78     /** @endcond */
  79 };
  80
  81 /** Status for rtl_math_stringToDouble and rtl_math_uStringToDouble.
  82  */
  83 enum rtl_math_ConversionStatus
  84 {
  85     /** Conversion was successful.
  86      */
  87     rtl_math_ConversionStatus_Ok,
  88
  89     /** Conversion caused overflow or underflow.
  90      */
  91     rtl_math_ConversionStatus_OutOfRange,
  92
  93     /** @cond INTERNAL */
  94     rtl_math_ConversionStatus_FORCE_EQUAL_SIZE = SAL_MAX_ENUM
  95     /** @endcond */
  96 };
  97
  98 /** Rounding modes for rtl_math_round.
  99  */
 100 enum rtl_math_RoundingMode
 101 {
 102     /** Like HalfUp, but corrects roundoff errors, preferred.
 103      */
 104     rtl_math_RoundingMode_Corrected,
 105
 106     /** Floor of absolute value, signed return (commercial).
 107      */
 108     rtl_math_RoundingMode_Down,
 109
 110     /** Ceil of absolute value, signed return (commercial).
 111      */
 112     rtl_math_RoundingMode_Up,
 113
 114     /** Floor of signed value.
 115      */
 116     rtl_math_RoundingMode_Floor,
 117
 118     /** Ceil of signed value.
 119      */
 120     rtl_math_RoundingMode_Ceiling,
 121
 122     /** Frac <= 0.5 ? floor of abs : ceil of abs, signed return.
 123      */
 124     rtl_math_RoundingMode_HalfDown,
 125
 126     /** Frac < 0.5 ? floor of abs : ceil of abs, signed return (mathematical).
 127      */
 128     rtl_math_RoundingMode_HalfUp,
 129
 130     /** IEEE rounding mode (statistical).
 131      */
 132     rtl_math_RoundingMode_HalfEven,
 133
 134     /** @cond INTERNAL */
 135     rtl_math_RoundingMode_FORCE_EQUAL_SIZE = SAL_MAX_ENUM
 136     /** @endcond */
 137 };
 138
 139 /** Special decimal places constants for rtl_math_doubleToString and
 140     rtl_math_doubleToUString and rtl_math_doubleToUStringBuffer.
 141  */
 142 enum rtl_math_DecimalPlaces
 143 {
 144     /** Value to be used with rtl_math_StringFormat_Automatic.
 145      */
 146     rtl_math_DecimalPlaces_Max = 0x7ffffff,
 147
 148     /** Value to be used with rtl_math_StringFormat_G.
 149         In fact the same value as rtl_math_DecimalPlaces_Max, just an alias for
 150         better understanding.
 151      */
 152     rtl_math_DecimalPlaces_DefaultSignificance = rtl_math_DecimalPlaces_Max
 153 };
 154
 155
 156 /** Conversions analogous to sprintf() using internal rounding.
 157
 158     +/-HUGE_VAL are converted to "INF" and "-INF", NAN values are
 159     converted to "NaN".
 160
 161     @param pResult
 162     Returns the resulting byte string.  Must itself not be null, and must point
 163     to either null or a valid string.
 164
 165     @param pResultCapacity
 166     If null, pResult is considered to point to immutable strings, and a new
 167     string will be allocated in pResult.
 168     If non-null, it points to the current capacity of pResult, which is
 169     considered to point to a string buffer (pResult must not itself be null in
 170     this case, and must point to a string that has room for the given capacity).
 171     The string representation of the given double value is inserted into pResult
 172     at position nResultOffset.  If pResult's current capacity is too small, a
 173     new string buffer will be allocated in pResult as necessary, and
 174     pResultCapacity will contain the new capacity on return.
 175
 176     @param nResultOffset
 177     If pResult is used as a string buffer (i.e., pResultCapacity is non-null),
 178     nResultOffset specifies the insertion offset within the buffer.  Ignored
 179     otherwise.
 180
 181     @param fValue
 182     The value to convert.
 183
 184     @param eFormat
 185     The format to use, one of rtl_math_StringFormat.
 186
 187     @param nDecPlaces
 188     The number of decimals to be generated.  Effectively fValue is rounded at
 189     this position, specifying nDecPlaces <= 0 accordingly rounds the value
 190     before the decimal point and fills with zeros.
 191     If eFormat == rtl_math_StringFormat_Automatic and nDecPlaces ==
 192     rtl_math_DecimalPlaces_Max, the highest number of significant decimals
 193     possible is generated.
 194     If eFormat == rtl_math_StringFormat_G, nDecPlaces specifies the number of
 195     significant digits instead.  If nDecPlaces ==
 196     rtl_math_DecimalPlaces_DefaultSignificance, the default number (currently 6
 197     as implemented by most libraries) of significant digits is generated.
 198     According to the ANSI C90 standard the E style will be used only if the
 199     exponent resulting from the conversion is less than -4 or greater than or
 200     equal to the precision.  However, as opposed to the ANSI standard, trailing
 201     zeros are not necessarily removed from the fractional portion of the result
 202     unless bEraseTrailingDecZeros == true was specified.
 203
 204     @param cDecSeparator
 205     The decimal separator.
 206
 207     @param pGroups
 208     Either null (no grouping is used), or a null-terminated list of group
 209     lengths.  Each group length must be strictly positive.  If the number of
 210     digits in a conversion exceeds the specified range, the last (highest) group
 211     length is repeated as needed.  Values are applied from right to left, for a
 212     grouping of 1,00,00,000 you'd have to specify pGroups={3,2,0}.
 213
 214     @param cGroupSeparator
 215     The group separator.  Ignored if pGroups is null.
 216
 217     @param bEraseTrailingDecZeros
 218     Trailing zeros in decimal places are erased.
 219  */
 220 SAL_DLLPUBLIC void SAL_CALL rtl_math_doubleToString(rtl_String ** pResult,
 221                                       sal_Int32 * pResultCapacity,
 222                                       sal_Int32 nResultOffset, double fValue,
 223                                       enum rtl_math_StringFormat eFormat,
 224                                       sal_Int32 nDecPlaces,
 225                                       sal_Char cDecSeparator,
 226                                       sal_Int32 const * pGroups,
 227                                       sal_Char cGroupSeparator,
 228                                       sal_Bool bEraseTrailingDecZeros)
 229     SAL_THROW_EXTERN_C();
 230
 231 /** Conversions analogous to sprintf() using internal rounding.
 232
 233     +/-HUGE_VAL are converted to "INF" and "-INF", NAN values are
 234     converted to "NaN".
 235
 236     @param pResult
 237     Returns the resulting Unicode string.  Must itself not be null, and must
 238     point to either null or a valid string.
 239
 240     @param pResultCapacity
 241     If null, pResult is considered to point to immutable strings, and a new
 242     string will be allocated in pResult.
 243     If non-null, it points to the current capacity of pResult, which is
 244     considered to point to a string buffer (pResult must not itself be null in
 245     this case, and must point to a string that has room for the given capacity).
 246     The string representation of the given double value is inserted into pResult
 247     at position nResultOffset.  If pResult's current capacity is too small, a
 248     new string buffer will be allocated in pResult as necessary, and
 249     pResultCapacity will contain the new capacity on return.
 250
 251     @param nResultOffset
 252     If pResult is used as a string buffer (i.e., pResultCapacity is non-null),
 253     nResultOffset specifies the insertion offset within the buffer.  Ignored
 254     otherwise.
 255
 256     @param fValue
 257     The value to convert.
 258
 259     @param eFormat
 260     The format to use, one of rtl_math_StringFormat.
 261
 262     @param nDecPlaces
 263     The number of decimals to be generated.  Effectively fValue is rounded at
 264     this position, specifying nDecPlaces <= 0 accordingly rounds the value
 265     before the decimal point and fills with zeros.
 266     If eFormat == rtl_math_StringFormat_Automatic and nDecPlaces ==
 267     rtl_math_DecimalPlaces_Max, the highest number of significant decimals
 268     possible is generated.
 269     If eFormat == rtl_math_StringFormat_G, nDecPlaces specifies the number of
 270     significant digits instead.  If nDecPlaces ==
 271     rtl_math_DecimalPlaces_DefaultSignificance, the default number (currently 6
 272     as implemented by most libraries) of significant digits is generated.
 273     According to the ANSI C90 standard the E style will be used only if the
 274     exponent resulting from the conversion is less than -4 or greater than or
 275     equal to the precision.  However, as opposed to the ANSI standard, trailing
 276     zeros are not necessarily removed from the fractional portion of the result
 277     unless bEraseTrailingDecZeros == true was specified.
 278
 279     @param cDecSeparator
 280     The decimal separator.
 281
 282     @param pGroups
 283     Either null (no grouping is used), or a null-terminated list of group
 284     lengths.  Each group length must be strictly positive.  If the number of
 285     digits in a conversion exceeds the specified range, the last (highest) group
 286     length is repeated as needed.  Values are applied from right to left, for a
 287     grouping of 1,00,00,000 you'd have to specify pGroups={3,2,0}.
 288
 289     @param cGroupSeparator
 290     The group separator.  Ignored if pGroups is null.
 291
 292     @param bEraseTrailingDecZeros
 293     Trailing zeros in decimal places are erased.
 294  */
 295 SAL_DLLPUBLIC void SAL_CALL rtl_math_doubleToUString(rtl_uString ** pResult,
 296                                        sal_Int32 * pResultCapacity,
 297                                        sal_Int32 nResultOffset, double fValue,
 298                                        enum rtl_math_StringFormat eFormat,
 299                                        sal_Int32 nDecPlaces,
 300                                        sal_Unicode cDecSeparator,
 301                                        sal_Int32 const * pGroups,
 302                                        sal_Unicode cGroupSeparator,
 303                                        sal_Bool bEraseTrailingDecZeros)
 304     SAL_THROW_EXTERN_C();
 305
 306 /** Conversion analogous to strtod(), convert a string representing a
 307     decimal number into a double value.
 308
 309     Leading tabs (0x09) and spaces (0x20) are eaten.  Overflow returns
 310     +/-HUGE_VAL, underflow 0.  In both cases pStatus is set to
 311     rtl_math_ConversionStatus_OutOfRange, otherwise to
 312     rtl_math_ConversionStatus_Ok.  "INF", "-INF" and "+/-1.#INF" are
 313     recognized as +/-HUGE_VAL, pStatus is set to
 314     rtl_math_ConversionStatus_OutOfRange.  "NaN" and "+/-1.#NAN" are
 315     recognized and the value is set to +/-NAN, pStatus is set to
 316     rtl_math_ConversionStatus_Ok.
 317
 318     @param pBegin
 319     Points to the start of the byte string to convert.  Must not be null.
 320
 321     @param pEnd
 322     Points one past the end of the byte string to convert.  The condition
 323     pEnd >= pBegin must hold.
 324
 325     @param cDecSeparator
 326     The decimal separator.
 327
 328     @param cGroupSeparator
 329     The group (aka thousands) separator.
 330
 331     @param pStatus
 332     If non-null, returns the status of the conversion.
 333
 334     @param pParsedEnd
 335     If non-null, returns one past the position of the last character parsed
 336     away.  Thus if [pBegin..pEnd) only contains the numerical string to be
 337     parsed, *pParsedEnd == pEnd on return.  If no numerical (sub-)string is
 338     found, *pParsedEnd == pBegin on return, even if there was leading
 339     whitespace.
 340  */
 341 SAL_DLLPUBLIC double SAL_CALL rtl_math_stringToDouble(
 342     sal_Char const * pBegin, sal_Char const * pEnd, sal_Char cDecSeparator,
 343     sal_Char cGroupSeparator, enum rtl_math_ConversionStatus * pStatus,
 344     sal_Char const ** pParsedEnd) SAL_THROW_EXTERN_C();
 345
 346 /** Conversion analogous to strtod(), convert a string representing a
 347     decimal number into a double value.
 348
 349     Leading tabs (U+0009) and spaces (U+0020) are eaten.  Overflow returns
 350     +/-HUGE_VAL, underflow 0.  In both cases pStatus is set to
 351     rtl_math_ConversionStatus_OutOfRange, otherwise to
 352     rtl_math_ConversionStatus_Ok.  "INF", "-INF" and "+/-1.#INF" are
 353     recognized as +/-HUGE_VAL, pStatus is set to
 354     rtl_math_ConversionStatus_OutOfRange.  "NaN" and "+/-1.#NAN" are
 355     recognized and the value is set to +/-NAN, pStatus is set to
 356     rtl_math_ConversionStatus_Ok.
 357
 358     @param pBegin
 359     Points to the start of the Unicode string to convert.  Must not be null.
 360
 361     @param pEnd
 362     Points one past the end of the Unicode string to convert.  The condition
 363     pEnd >= pBegin must hold.
 364
 365     @param cDecSeparator
 366     The decimal separator.
 367
 368     @param cGroupSeparator
 369     The group (aka thousands) separator.
 370
 371     @param pStatus
 372     If non-null, returns the status of the conversion.
 373
 374     @param pParsedEnd
 375     If non-null, returns one past the position of the last character parsed
 376     away.  Thus if [pBegin..pEnd) only contains the numerical string to be
 377     parsed, *pParsedEnd == pEnd on return.  If no numerical (sub-)string is
 378     found, *pParsedEnd == pBegin on return, even if there was leading
 379     whitespace.
 380  */
 381 SAL_DLLPUBLIC double SAL_CALL rtl_math_uStringToDouble(
 382     sal_Unicode const * pBegin, sal_Unicode const * pEnd,
 383     sal_Unicode cDecSeparator, sal_Unicode cGroupSeparator,
 384     enum rtl_math_ConversionStatus * pStatus, sal_Unicode const ** pParsedEnd)
 385     SAL_THROW_EXTERN_C();
 386
 387 /** Rounds a double value.
 388
 389     @param fValue
 390     Specifies the value to be rounded.
 391
 392     @param nDecPlaces
 393     Specifies the decimal place where rounding occurs.  Must be in the range
 394     -20 to +20, inclusive.  Negative if rounding occurs before the decimal
 395     point.
 396
 397     @param eMode
 398     Specifies the rounding mode.
 399  */
 400 SAL_DLLPUBLIC double SAL_CALL rtl_math_round(double fValue, int nDecPlaces,
 401                                enum rtl_math_RoundingMode eMode)
 402     SAL_THROW_EXTERN_C();
 403
 404 /** Scales fVal to a power of 10 without calling pow() or div() for nExp values
 405     between -16 and +16, providing a faster method.
 406
 407     @param fValue
 408     The value to be raised.
 409
 410     @param nExp
 411     The exponent.
 412
 413     @return
 414     fVal * pow(10.0, nExp)
 415  */
 416 SAL_DLLPUBLIC double SAL_CALL rtl_math_pow10Exp(double fValue, int nExp) SAL_THROW_EXTERN_C();
 417
 418 /** Rounds value to 15 significant decimal digits.
 419
 420     @param fValue
 421     The value to be rounded.
 422   */
 423 SAL_DLLPUBLIC double SAL_CALL rtl_math_approxValue(double fValue) SAL_THROW_EXTERN_C();
 424
 425 /** Test equality of two values with an accuracy of the magnitude of the
 426     given values scaled by 2^-48 (4 bits roundoff stripped).
 427
 428     @attention
 429     approxEqual( value!=0.0, 0.0 ) _never_ yields true.
 430
 431     @since LibreOffice 5.3
 432  */
 433 SAL_DLLPUBLIC bool SAL_CALL rtl_math_approxEqual(double a, double b) SAL_THROW_EXTERN_C();
 434
 435 /** Returns more accurate e^x-1 for x near 0 than calculating directly.
 436
 437     expm1 is part of the C99 standard, but not provided by some compilers.
 438
 439     @param fValue
 440     The value x in the term e^x-1.
 441   */
 442 SAL_DLLPUBLIC double SAL_CALL rtl_math_expm1(double fValue) SAL_THROW_EXTERN_C();
 443
 444 /** Returns more accurate log(1+x) for x near 0 than calculating directly.
 445
 446     log1p is part of the C99 standard, but not provided by some compilers.
 447
 448     @param fValue
 449     The value x in the term log(1+x).
 450   */
 451 SAL_DLLPUBLIC double SAL_CALL rtl_math_log1p(double fValue) SAL_THROW_EXTERN_C();
 452
 453 /** Returns more accurate atanh(x) for x near 0 than calculating
 454     0.5*log((1+x)/(1-x)).
 455
 456     atanh is part of the C99 standard, but not provided by some compilers.
 457
 458     @param fValue
 459     The value x in the term atanh(x).
 460   */
 461 SAL_DLLPUBLIC double SAL_CALL rtl_math_atanh(double fValue) SAL_THROW_EXTERN_C();
 462
 463 /** Returns values of the Errorfunction erf.
 464
 465     erf is part of the C99 standard, but not provided by some compilers.
 466
 467     @param fValue
 468     The value x in the term erf(x).
 469   */
 470 SAL_DLLPUBLIC double SAL_CALL rtl_math_erf(double fValue) SAL_THROW_EXTERN_C();
 471
 472 /** Returns values of the complement Errorfunction erfc.
 473
 474     erfc is part of the C99 standard, but not provided by some compilers.
 475
 476     @param fValue
 477     The value x in the term erfc(x).
 478   */
 479 SAL_DLLPUBLIC double SAL_CALL rtl_math_erfc(double fValue) SAL_THROW_EXTERN_C();
 480
 481 /** Returns values of the inverse hyperbolic sine.
 482
 483     asinh is part of the C99 standard, but not provided by some compilers.
 484
 485     @param fValue
 486     The value x in the term asinh(x).
 487   */
 488 SAL_DLLPUBLIC double SAL_CALL rtl_math_asinh(double fValue) SAL_THROW_EXTERN_C();
 489
 490 /** Returns values of the inverse hyperbolic cosine.
 491
 492     acosh is part of the C99 standard, but not provided by some compilers.
 493
 494     @param fValue
 495     The value x in the term acosh(x).
 496   */
 497 SAL_DLLPUBLIC double SAL_CALL rtl_math_acosh(double fValue) SAL_THROW_EXTERN_C();
 498
 499 #if defined __cplusplus
 500 }
 501 #endif /* __cplusplus */
 502
 503 #endif /* INCLUDED_RTL_MATH_H */
 504
 505 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */