LibreOffice: rtl/math.h File Reference

LibreOffice LibreOffice 7.3 SDK C/C++ API Reference

Enumerations | Functions
math.h File Reference
`#include "sal/config.h"`
`#include "rtl/ustring.h"`
`#include "sal/saldllapi.h"`
`#include "sal/types.h"`

Go to the source code of this file.

## Enumerations
enum | rtl_math_StringFormat { rtl_math_StringFormat_E , rtl_math_StringFormat_F , rtl_math_StringFormat_G , rtl_math_StringFormat_Automatic , rtl_math_StringFormat_E1 , rtl_math_StringFormat_E2 , rtl_math_StringFormat_G1 , rtl_math_StringFormat_G2 }
| Formatting modes for rtl_math_doubleToString and rtl_math_doubleToUString and rtl_math_doubleToUStringBuffer. More...
enum | rtl_math_ConversionStatus { rtl_math_ConversionStatus_Ok , rtl_math_ConversionStatus_OutOfRange }
| Status for rtl_math_stringToDouble and rtl_math_uStringToDouble. More...
enum | rtl_math_RoundingMode { rtl_math_RoundingMode_Corrected , rtl_math_RoundingMode_Down , rtl_math_RoundingMode_Up , rtl_math_RoundingMode_Floor , rtl_math_RoundingMode_Ceiling , rtl_math_RoundingMode_HalfDown , rtl_math_RoundingMode_HalfUp , rtl_math_RoundingMode_HalfEven }
| Rounding modes for rtl_math_round. More...
enum | rtl_math_DecimalPlaces { rtl_math_DecimalPlaces_Max = 0x7ffffff , rtl_math_DecimalPlaces_DefaultSignificance = rtl_math_DecimalPlaces_Max }
| Special decimal places constants for rtl_math_doubleToString and rtl_math_doubleToUString and rtl_math_doubleToUStringBuffer. More...

## Functions
SAL_DLLPUBLIC void | rtl_math_doubleToString (rtl_String **pResult, sal_Int32 *pResultCapacity, sal_Int32 nResultOffset, double fValue, enum rtl_math_StringFormat eFormat, sal_Int32 nDecPlaces, char cDecSeparator, sal_Int32 const *pGroups, char cGroupSeparator, sal_Bool bEraseTrailingDecZeros) SAL_THROW_EXTERN_C()
| Conversions analogous to sprintf() using internal rounding. More...
SAL_DLLPUBLIC void | rtl_math_doubleToUString (rtl_uString **pResult, sal_Int32 *pResultCapacity, sal_Int32 nResultOffset, double fValue, enum rtl_math_StringFormat eFormat, sal_Int32 nDecPlaces, sal_Unicode cDecSeparator, sal_Int32 const *pGroups, sal_Unicode cGroupSeparator, sal_Bool bEraseTrailingDecZeros) SAL_THROW_EXTERN_C()
| Conversions analogous to sprintf() using internal rounding. More...
SAL_DLLPUBLIC double | rtl_math_stringToDouble (char const *pBegin, char const *pEnd, char cDecSeparator, char cGroupSeparator, enum rtl_math_ConversionStatus *pStatus, char const **pParsedEnd) SAL_THROW_EXTERN_C()
| Conversion analogous to strtod(), convert a string representing a decimal number into a double value. More...
SAL_DLLPUBLIC double | rtl_math_uStringToDouble (sal_Unicode const *pBegin, sal_Unicode const *pEnd, sal_Unicode cDecSeparator, sal_Unicode cGroupSeparator, enum rtl_math_ConversionStatus *pStatus, sal_Unicode const **pParsedEnd) SAL_THROW_EXTERN_C()
| Conversion analogous to strtod(), convert a string representing a decimal number into a double value. More...
SAL_DLLPUBLIC double | rtl_math_round (double fValue, int nDecPlaces, enum rtl_math_RoundingMode eMode) SAL_THROW_EXTERN_C()
| Rounds a double value. More...
SAL_DLLPUBLIC double | rtl_math_pow10Exp (double fValue, int nExp) SAL_THROW_EXTERN_C()
| Scales fVal to a power of 10 without calling pow() or div() for nExp values between -16 and +16, providing a faster method. More...
SAL_DLLPUBLIC double | rtl_math_approxValue (double fValue) SAL_THROW_EXTERN_C()
| Rounds value to 15 significant decimal digits. More...
SAL_DLLPUBLIC bool | rtl_math_approxEqual (double a, double b) SAL_THROW_EXTERN_C()
| Test equality of two values with an accuracy of the magnitude of the given values scaled by 2^-48 (4 bits roundoff stripped). More...
SAL_DLLPUBLIC double | rtl_math_expm1 (double fValue) SAL_THROW_EXTERN_C()
| Returns more accurate e^x-1 for x near 0 than calculating directly. More...
SAL_DLLPUBLIC double | rtl_math_log1p (double fValue) SAL_THROW_EXTERN_C()
| Returns more accurate log(1+x) for x near 0 than calculating directly. More...
SAL_DLLPUBLIC double | rtl_math_atanh (double fValue) SAL_THROW_EXTERN_C()
| Returns more accurate atanh(x) for x near 0 than calculating 0.5*log((1+x)/(1-x)). More...
SAL_DLLPUBLIC double | rtl_math_erf (double fValue) SAL_THROW_EXTERN_C()
| Returns values of the Errorfunction erf. More...
SAL_DLLPUBLIC double | rtl_math_erfc (double fValue) SAL_THROW_EXTERN_C()
| Returns values of the complement Errorfunction erfc. More...
SAL_DLLPUBLIC double | rtl_math_asinh (double fValue) SAL_THROW_EXTERN_C()
| Returns values of the inverse hyperbolic sine. More...
SAL_DLLPUBLIC double | rtl_math_acosh (double fValue) SAL_THROW_EXTERN_C()
| Returns values of the inverse hyperbolic cosine. More...

## Enumeration Type Documentation

## ◆ rtl_math_ConversionStatus

enum rtl_math_ConversionStatus

Status for rtl_math_stringToDouble and rtl_math_uStringToDouble.

Enumerator
rtl_math_ConversionStatus_Ok | Conversion was successful.
rtl_math_ConversionStatus_OutOfRange | Conversion caused overflow or underflow.

## ◆ rtl_math_DecimalPlaces

enum rtl_math_DecimalPlaces

Special decimal places constants for rtl_math_doubleToString and rtl_math_doubleToUString and rtl_math_doubleToUStringBuffer.

Enumerator
rtl_math_DecimalPlaces_Max | Value to be used with rtl_math_StringFormat_Automatic.
rtl_math_DecimalPlaces_DefaultSignificance | Value to be used with rtl_math_StringFormat_G. In fact the same value as rtl_math_DecimalPlaces_Max, just an alias for better understanding.

## ◆ rtl_math_RoundingMode

enum rtl_math_RoundingMode

Rounding modes for rtl_math_round.

Enumerator
rtl_math_RoundingMode_Corrected | Like HalfUp, but corrects roundoff errors, preferred.
rtl_math_RoundingMode_Down | Floor of absolute value, signed return (commercial).
rtl_math_RoundingMode_Up | Ceil of absolute value, signed return (commercial).
rtl_math_RoundingMode_Floor | Floor of signed value.
rtl_math_RoundingMode_Ceiling | Ceil of signed value.
rtl_math_RoundingMode_HalfDown | Frac <= 0.5 ? floor of abs : ceil of abs, signed return.
rtl_math_RoundingMode_HalfUp | Frac < 0.5 ? floor of abs : ceil of abs, signed return (mathematical).
rtl_math_RoundingMode_HalfEven | IEEE rounding mode (statistical).

## ◆ rtl_math_StringFormat

enum rtl_math_StringFormat

Formatting modes for rtl_math_doubleToString and rtl_math_doubleToUString and rtl_math_doubleToUStringBuffer.

Enumerator
rtl_math_StringFormat_E | Like sprintf() E.
rtl_math_StringFormat_F | Like sprintf() f.
rtl_math_StringFormat_G | Like sprintf() G, 'F' or 'E' format is used depending on which one is more compact.
rtl_math_StringFormat_Automatic | Automatic, 'F' or 'E' format is used depending on the numeric value to be formatted.
rtl_math_StringFormat_E1 | Same 'E', but with only 1 minimum digits in exponent. Since LibreOffice 5.0
rtl_math_StringFormat_E2 | Same 'E', but with only 2 minimum digits in exponent. Since LibreOffice 5.0
rtl_math_StringFormat_G1 | Same 'G', but with only 1 minimum digits in exponent. Since LibreOffice 5.0
rtl_math_StringFormat_G2 | Same 'G', but with only 2 minimum digits in exponent. Since LibreOffice 5.0

## Function Documentation

## ◆ rtl_math_acosh()

SAL_DLLPUBLIC double rtl_math_acosh | ( | double | fValue | ) |

Returns values of the inverse hyperbolic cosine.

acosh is part of the C99 standard, but not provided by some compilers.

Parameters

  fValue | The value x in the term acosh(x).

## ◆ rtl_math_approxEqual()

SAL_DLLPUBLIC bool rtl_math_approxEqual | ( | double | a,
|  | double | b
| ) |  |

Test equality of two values with an accuracy of the magnitude of the given values scaled by 2^-48 (4 bits roundoff stripped).

Attention
  approxEqual( value!=0.0, 0.0 ) never yields true.

Since
  LibreOffice 5.3

## ◆ rtl_math_approxValue()

SAL_DLLPUBLIC double rtl_math_approxValue | ( | double | fValue | ) |

Rounds value to 15 significant decimal digits.

Parameters

  fValue | The value to be rounded.

## ◆ rtl_math_asinh()

SAL_DLLPUBLIC double rtl_math_asinh | ( | double | fValue | ) |

Returns values of the inverse hyperbolic sine.

asinh is part of the C99 standard, but not provided by some compilers.

Parameters

  fValue | The value x in the term asinh(x).

## ◆ rtl_math_atanh()

SAL_DLLPUBLIC double rtl_math_atanh | ( | double | fValue | ) |

Returns more accurate atanh(x) for x near 0 than calculating 0.5*log((1+x)/(1-x)).

atanh is part of the C99 standard, but not provided by some compilers.

Parameters

  fValue | The value x in the term atanh(x).

## ◆ rtl_math_doubleToString()

SAL_DLLPUBLIC void rtl_math_doubleToString | ( | rtl_String ** | pResult,
|  | sal_Int32 * | pResultCapacity,
|  | sal_Int32 | nResultOffset,
|  | double | fValue,
|  | enum rtl_math_StringFormat | eFormat,
|  | sal_Int32 | nDecPlaces,
|  | char | cDecSeparator,
|  | sal_Int32 const * | pGroups,
|  | char | cGroupSeparator,
|  | sal_Bool | bEraseTrailingDecZeros
| ) |  |

Conversions analogous to sprintf() using internal rounding.

+/-HUGE_VAL are converted to "INF" and "-INF", NAN values are converted to "NaN".

Parameters

  pResult | Returns the resulting byte string. Must itself not be null, and must point to either null or a valid string.
  pResultCapacity | If null, pResult is considered to point to immutable strings, and a new string will be allocated in pResult. If non-null, it points to the current capacity of pResult, which is considered to point to a string buffer (pResult must not itself be null in this case, and must point to a string that has room for the given capacity). The string representation of the given double value is inserted into pResult at position nResultOffset. If pResult's current capacity is too small, a new string buffer will be allocated in pResult as necessary, and pResultCapacity will contain the new capacity on return.
  nResultOffset | If pResult is used as a string buffer (i.e., pResultCapacity is non-null), nResultOffset specifies the insertion offset within the buffer. Ignored otherwise.
  fValue | The value to convert.
  eFormat | The format to use, one of rtl_math_StringFormat.
  nDecPlaces | The number of decimals to be generated. Effectively fValue is rounded at this position, specifying nDecPlaces <= 0 accordingly rounds the value before the decimal point and fills with zeros. If eFormat == rtl_math_StringFormat_Automatic and nDecPlaces == rtl_math_DecimalPlaces_Max, the highest number of significant decimals possible is generated. If eFormat == rtl_math_StringFormat_G, nDecPlaces specifies the number of significant digits instead. If nDecPlaces == rtl_math_DecimalPlaces_DefaultSignificance, the default number (currently 6 as implemented by most libraries) of significant digits is generated. According to the ANSI C90 standard the E style will be used only if the exponent resulting from the conversion is less than -4 or greater than or equal to the precision. However, as opposed to the ANSI standard, trailing zeros are not necessarily removed from the fractional portion of the result unless bEraseTrailingDecZeros == true was specified.
  cDecSeparator | The decimal separator.
  pGroups | Either null (no grouping is used), or a null-terminated list of group lengths. Each group length must be strictly positive. If the number of digits in a conversion exceeds the specified range, the last (highest) group length is repeated as needed. Values are applied from right to left, for a grouping of 1,00,00,000 you'd have to specify pGroups={3,2,0}.
  cGroupSeparator | The group separator. Ignored if pGroups is null.
  bEraseTrailingDecZeros | Trailing zeros in decimal places are erased.

## ◆ rtl_math_doubleToUString()

SAL_DLLPUBLIC void rtl_math_doubleToUString | ( | rtl_uString ** | pResult,
|  | sal_Int32 * | pResultCapacity,
|  | sal_Int32 | nResultOffset,
|  | double | fValue,
|  | enum rtl_math_StringFormat | eFormat,
|  | sal_Int32 | nDecPlaces,
|  | sal_Unicode | cDecSeparator,
|  | sal_Int32 const * | pGroups,
|  | sal_Unicode | cGroupSeparator,
|  | sal_Bool | bEraseTrailingDecZeros
| ) |  |

Conversions analogous to sprintf() using internal rounding.

+/-HUGE_VAL are converted to "INF" and "-INF", NAN values are converted to "NaN".

Parameters

  pResult | Returns the resulting Unicode string. Must itself not be null, and must point to either null or a valid string.
  pResultCapacity | If null, pResult is considered to point to immutable strings, and a new string will be allocated in pResult. If non-null, it points to the current capacity of pResult, which is considered to point to a string buffer (pResult must not itself be null in this case, and must point to a string that has room for the given capacity). The string representation of the given double value is inserted into pResult at position nResultOffset. If pResult's current capacity is too small, a new string buffer will be allocated in pResult as necessary, and pResultCapacity will contain the new capacity on return.
  nResultOffset | If pResult is used as a string buffer (i.e., pResultCapacity is non-null), nResultOffset specifies the insertion offset within the buffer. Ignored otherwise.
  fValue | The value to convert.
  eFormat | The format to use, one of rtl_math_StringFormat.
  nDecPlaces | The number of decimals to be generated. Effectively fValue is rounded at this position, specifying nDecPlaces <= 0 accordingly rounds the value before the decimal point and fills with zeros. If eFormat == rtl_math_StringFormat_Automatic and nDecPlaces == rtl_math_DecimalPlaces_Max, the highest number of significant decimals possible is generated. If eFormat == rtl_math_StringFormat_G, nDecPlaces specifies the number of significant digits instead. If nDecPlaces == rtl_math_DecimalPlaces_DefaultSignificance, the default number (currently 6 as implemented by most libraries) of significant digits is generated. According to the ANSI C90 standard the E style will be used only if the exponent resulting from the conversion is less than -4 or greater than or equal to the precision. However, as opposed to the ANSI standard, trailing zeros are not necessarily removed from the fractional portion of the result unless bEraseTrailingDecZeros == true was specified.
  cDecSeparator | The decimal separator.
  pGroups | Either null (no grouping is used), or a null-terminated list of group lengths. Each group length must be strictly positive. If the number of digits in a conversion exceeds the specified range, the last (highest) group length is repeated as needed. Values are applied from right to left, for a grouping of 1,00,00,000 you'd have to specify pGroups={3,2,0}.
  cGroupSeparator | The group separator. Ignored if pGroups is null.
  bEraseTrailingDecZeros | Trailing zeros in decimal places are erased.

## ◆ rtl_math_erf()

SAL_DLLPUBLIC double rtl_math_erf | ( | double | fValue | ) |

Returns values of the Errorfunction erf.

erf is part of the C99 standard, but not provided by some compilers.

Parameters

  fValue | The value x in the term erf(x).

## ◆ rtl_math_erfc()

SAL_DLLPUBLIC double rtl_math_erfc | ( | double | fValue | ) |

Returns values of the complement Errorfunction erfc.

erfc is part of the C99 standard, but not provided by some compilers.

Parameters

  fValue | The value x in the term erfc(x).

## ◆ rtl_math_expm1()

SAL_DLLPUBLIC double rtl_math_expm1 | ( | double | fValue | ) |

Returns more accurate e^x-1 for x near 0 than calculating directly.

expm1 is part of the C99 standard, but not provided by some compilers.

Parameters

  fValue | The value x in the term e^x-1.

## ◆ rtl_math_log1p()

SAL_DLLPUBLIC double rtl_math_log1p | ( | double | fValue | ) |

Returns more accurate log(1+x) for x near 0 than calculating directly.

log1p is part of the C99 standard, but not provided by some compilers.

Parameters

  fValue | The value x in the term log(1+x).

## ◆ rtl_math_pow10Exp()

SAL_DLLPUBLIC double rtl_math_pow10Exp | ( | double | fValue,
|  | int | nExp
| ) |  |

Scales fVal to a power of 10 without calling pow() or div() for nExp values between -16 and +16, providing a faster method.

Parameters

  fValue | The value to be raised.
  nExp | The exponent.

Returns
  fVal * pow(10.0, nExp)

## ◆ rtl_math_round()

SAL_DLLPUBLIC double rtl_math_round | ( | double | fValue,
|  | int | nDecPlaces,
|  | enum rtl_math_RoundingMode | eMode
| ) |  |

Rounds a double value.

Parameters

  fValue | Specifies the value to be rounded.
  nDecPlaces | Specifies the decimal place where rounding occurs. Must be in the range -20 to +20, inclusive. Negative if rounding occurs before the decimal point.
  eMode | Specifies the rounding mode.

## ◆ rtl_math_stringToDouble()

SAL_DLLPUBLIC double rtl_math_stringToDouble | ( | char const * | pBegin,
|  | char const * | pEnd,
|  | char | cDecSeparator,
|  | char | cGroupSeparator,
|  | enum rtl_math_ConversionStatus * | pStatus,
|  | char const ** | pParsedEnd
| ) |  |

Conversion analogous to strtod(), convert a string representing a decimal number into a double value.

Leading tabs (0x09) and spaces (0x20) are eaten. Overflow returns +/-HUGE_VAL, underflow 0. In both cases pStatus is set to rtl_math_ConversionStatus_OutOfRange, otherwise to rtl_math_ConversionStatus_Ok. "INF", "-INF" and "+/-1.#INF" are recognized as +/-HUGE_VAL, pStatus is set to rtl_math_ConversionStatus_OutOfRange. "NaN" and "+/-1.#NAN" are recognized and the value is set to +/-NAN, pStatus is set to rtl_math_ConversionStatus_Ok.

Parameters

  pBegin | Points to the start of the byte string to convert. Must not be null.
  pEnd | Points one past the end of the byte string to convert. The condition pEnd >= pBegin must hold.
  cDecSeparator | The decimal separator.
  cGroupSeparator | The group (aka thousands) separator.
  pStatus | If non-null, returns the status of the conversion.
  pParsedEnd | If non-null, returns one past the position of the last character parsed away. Thus if [pBegin..pEnd) only contains the numerical string to be parsed, *pParsedEnd == pEnd on return. If no numerical (sub-)string is found, *pParsedEnd == pBegin on return, even if there was leading whitespace.

## ◆ rtl_math_uStringToDouble()

SAL_DLLPUBLIC double rtl_math_uStringToDouble | ( | sal_Unicode const * | pBegin,
|  | sal_Unicode const * | pEnd,
|  | sal_Unicode | cDecSeparator,
|  | sal_Unicode | cGroupSeparator,
|  | enum rtl_math_ConversionStatus * | pStatus,
|  | sal_Unicode const ** | pParsedEnd
| ) |  |

Conversion analogous to strtod(), convert a string representing a decimal number into a double value.

Leading tabs (U+0009) and spaces (U+0020) are eaten. Overflow returns +/-HUGE_VAL, underflow 0. In both cases pStatus is set to rtl_math_ConversionStatus_OutOfRange, otherwise to rtl_math_ConversionStatus_Ok. "INF", "-INF" and "+/-1.#INF" are recognized as +/-HUGE_VAL, pStatus is set to rtl_math_ConversionStatus_OutOfRange. "NaN" and "+/-1.#NAN" are recognized and the value is set to +/-NAN, pStatus is set to rtl_math_ConversionStatus_Ok.

Parameters

  pBegin | Points to the start of the Unicode string to convert. Must not be null.
  pEnd | Points one past the end of the Unicode string to convert. The condition pEnd >= pBegin must hold.
  cDecSeparator | The decimal separator.
  cGroupSeparator | The group (aka thousands) separator.
  pStatus | If non-null, returns the status of the conversion.
  pParsedEnd | If non-null, returns one past the position of the last character parsed away. Thus if [pBegin..pEnd) only contains the numerical string to be parsed, *pParsedEnd == pEnd on return. If no numerical (sub-)string is found, *pParsedEnd == pBegin on return, even if there was leading whitespace.