/************************************************************** * * Licensed to the Apache Software Foundation (ASF) under one * or more contributor license agreements. See the NOTICE file * distributed with this work for additional information * regarding copyright ownership. The ASF licenses this file * to you under the Apache License, Version 2.0 (the * "License"); you may not use this file except in compliance * with the License. You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, * software distributed under the License is distributed on an * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY * KIND, either express or implied. See the License for the * specific language governing permissions and limitations * under the License. * *************************************************************/ #if !defined INCLUDED_RTL_MATH_H #define INCLUDED_RTL_MATH_H #include "rtl/ustring.h" #include "sal/types.h" #if defined __cplusplus extern "C" { #endif /* __cplusplus */ /** Formatting modes for rtl_math_doubleToString and rtl_math_doubleToUString and rtl_math_doubleToUStringBuffer. */ enum rtl_math_StringFormat { /** Like sprintf() %E. */ rtl_math_StringFormat_E, /** Like sprintf() %f. */ rtl_math_StringFormat_F, /** Like sprintf() %G, 'F' or 'E' format is used depending on which one is more compact. */ rtl_math_StringFormat_G, /** Automatic, 'F' or 'E' format is used depending on the numeric value to be formatted. */ rtl_math_StringFormat_Automatic, /** @internal */ rtl_math_StringFormat_FORCE_EQUAL_SIZE = SAL_MAX_ENUM }; /** Status for rtl_math_stringToDouble and rtl_math_uStringToDouble. */ enum rtl_math_ConversionStatus { /** Conversion was successful. */ rtl_math_ConversionStatus_Ok, /** Conversion caused overflow or underflow. */ rtl_math_ConversionStatus_OutOfRange, /** @internal */ rtl_math_ConversionStatus_FORCE_EQUAL_SIZE = SAL_MAX_ENUM }; /** Rounding modes for rtl_math_round. */ enum rtl_math_RoundingMode { /** Like HalfUp, but corrects roundoff errors, preferred. */ rtl_math_RoundingMode_Corrected, /** Floor of absolute value, signed return (commercial). */ rtl_math_RoundingMode_Down, /** Ceil of absolute value, signed return (commercial). */ rtl_math_RoundingMode_Up, /** Floor of signed value. */ rtl_math_RoundingMode_Floor, /** Ceil of signed value. */ rtl_math_RoundingMode_Ceiling, /** Frac <= 0.5 ? floor of abs : ceil of abs, signed return. */ rtl_math_RoundingMode_HalfDown, /** Frac < 0.5 ? floor of abs : ceil of abs, signed return (mathematical). */ rtl_math_RoundingMode_HalfUp, /** IEEE rounding mode (statistical). */ rtl_math_RoundingMode_HalfEven, /** @internal */ rtl_math_RoundingMode_FORCE_EQUAL_SIZE = SAL_MAX_ENUM }; /** Special decimal places constants for rtl_math_doubleToString and rtl_math_doubleToUString and rtl_math_doubleToUStringBuffer. */ enum rtl_math_DecimalPlaces { /** Value to be used with rtl_math_StringFormat_Automatic. */ rtl_math_DecimalPlaces_Max = 0x7ffffff, /** 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_DecimalPlaces_DefaultSignificance = 0x7ffffff }; /** Conversions analogous to sprintf() using internal rounding. +/-HUGE_VAL are converted to "INF" and "-INF", NAN values are converted to "NaN". @param pResult Returns the resulting byte string. Must itself not be null, and must point to either null or a valid string. @param 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. @param 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. @param fValue The value to convert. @param eFormat The format to use, one of rtl_math_StringFormat. @param 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. @param cDecSeparator The decimal separator. @param 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}. @param cGroupSeparator The group separator. Ignored if pGroups is null. @param bEraseTrailingDecZeros Trailing zeros in decimal places are erased. */ void SAL_CALL rtl_math_doubleToString(rtl_String ** pResult, sal_Int32 * pResultCapacity, sal_Int32 nResultOffset, double fValue, enum rtl_math_StringFormat eFormat, sal_Int32 nDecPlaces, sal_Char cDecSeparator, sal_Int32 const * pGroups, sal_Char cGroupSeparator, sal_Bool bEraseTrailingDecZeros) SAL_THROW_EXTERN_C(); /** Conversions analogous to sprintf() using internal rounding. +/-HUGE_VAL are converted to "INF" and "-INF", NAN values are converted to "NaN". @param pResult Returns the resulting Unicode string. Must itself not be null, and must point to either null or a valid string. @param 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. @param 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. @param fValue The value to convert. @param eFormat The format to use, one of rtl_math_StringFormat. @param 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. @param cDecSeparator The decimal separator. @param 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}. @param cGroupSeparator The group separator. Ignored if pGroups is null. @param bEraseTrailingDecZeros Trailing zeros in decimal places are erased. */ void SAL_CALL 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(); /** 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. @param pBegin Points to the start of the byte string to convert. Must not be null. @param pEnd Points one past the end of the byte string to convert. The condition pEnd >= pBegin must hold. @param cDecSeparator The decimal separator. @param cGroupSeparator The group (aka thousands) separator. @param pStatus If non-null, returns the status of the conversion. @param 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. */ double SAL_CALL rtl_math_stringToDouble( sal_Char const * pBegin, sal_Char const * pEnd, sal_Char cDecSeparator, sal_Char cGroupSeparator, enum rtl_math_ConversionStatus * pStatus, sal_Char const ** pParsedEnd) SAL_THROW_EXTERN_C(); /** 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. @param pBegin Points to the start of the Unicode string to convert. Must not be null. @param pEnd Points one past the end of the Unicode string to convert. The condition pEnd >= pBegin must hold. @param cDecSeparator The decimal separator. @param cGroupSeparator The group (aka thousands) separator. @param pStatus If non-null, returns the status of the conversion. @param 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. */ double SAL_CALL 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(); /** Rounds a double value. @param fValue Specifies the value to be rounded. @param 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. @param eMode Specifies the rounding mode. */ double SAL_CALL rtl_math_round(double fValue, int nDecPlaces, enum rtl_math_RoundingMode eMode) 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. @param fValue The value to be raised. @param nExp The exponent. @return fVal * pow(10.0, nExp) */ double SAL_CALL rtl_math_pow10Exp(double fValue, int nExp) SAL_THROW_EXTERN_C(); /** Rounds value to 15 significant decimal digits. @param fValue The value to be rounded. */ double SAL_CALL rtl_math_approxValue(double fValue) SAL_THROW_EXTERN_C(); /** 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. @param fValue The value x in the term e^x-1. */ double SAL_CALL rtl_math_expm1(double fValue) SAL_THROW_EXTERN_C(); /** 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. @param fValue The value x in the term log(1+x). */ double SAL_CALL rtl_math_log1p(double fValue) SAL_THROW_EXTERN_C(); /** 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. @param fValue The value x in the term atanh(x). */ double SAL_CALL rtl_math_atanh(double fValue) SAL_THROW_EXTERN_C(); /** Returns values of the Errorfunction erf. erf is part of the C99 standard, but not provided by some compilers. @param fValue The value x in the term erf(x). */ double SAL_CALL rtl_math_erf(double fValue) SAL_THROW_EXTERN_C(); /** Returns values of the complement Errorfunction erfc. erfc is part of the C99 standard, but not provided by some compilers. @param fValue The value x in the term erfc(x). */ double SAL_CALL rtl_math_erfc(double fValue) SAL_THROW_EXTERN_C(); /** Returns values of the inverse hyperbolic sine. asinh is part of the C99 standard, but not provided by some compilers. @param fValue The value x in the term asinh(x). */ double SAL_CALL rtl_math_asinh(double fValue) SAL_THROW_EXTERN_C(); /** Returns values of the inverse hyperbolic cosine. acosh is part of the C99 standard, but not provided by some compilers. @param fValue The value x in the term acosh(x). */ double SAL_CALL rtl_math_acosh(double fValue) SAL_THROW_EXTERN_C(); #if defined __cplusplus } #endif /* __cplusplus */ #endif /* INCLUDED_RTL_MATH_H */