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