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