lib/ftoastr.h

   1 /* floating point to accurate string
   2
   3    Copyright (C) 2010-2024 Free Software Foundation, Inc.
   4
   5    This program is free software: you can redistribute it and/or modify
   6    it under the terms of the GNU General Public License as published by
   7    the Free Software Foundation, either version 3 of the License, or
   8    (at your option) any later version.
   9
  10    This program is distributed in the hope that it will be useful,
  11    but WITHOUT ANY WARRANTY; without even the implied warranty of
  12    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13    GNU General Public License for more details.
  14
  15    You should have received a copy of the GNU General Public License
  16    along with this program.  If not, see <https://www.gnu.org/licenses/>.  */
  17
  18 /* Written by Paul Eggert.  */
  19
  20 #ifndef _GL_FTOASTR_H
  21 #define _GL_FTOASTR_H
  22
  23 #include "intprops.h"
  24 #include <float.h>
  25 #include <stddef.h>
  26
  27 #ifdef __cplusplus
  28 extern "C" {
  29 #endif
  30
  31
  32 /* Store into BUF (of size BUFSIZE) an accurate minimal-precision
  33    string representation of a floating point number.  FLAGS affect the
  34    formatting of the number.  Pad the output string with spaces as
  35    necessary to width WIDTH bytes, in the style of printf.  WIDTH must
  36    be nonnegative.  X is the floating-point number to be converted.
  37
  38    Return the number of bytes stored into BUF, not counting the
  39    terminating null.  However, do not overrun BUF: if BUF is too
  40    small, return a fairly tight (but not necessarily exact) upper
  41    bound on the value that would have been returned if BUF had been
  42    big enough.  If SIZE is zero, BUF may be a null pointer.  On error
  43    (e.g., returned value would exceed INT_MAX), return -1 and set
  44    errno.
  45
  46    Example:
  47
  48      char buf[DBL_BUFSIZE_BOUND];
  49      int r = dtoastr (buf, sizeof buf, 0, 0, 0.1);
  50
  51    In the C locale, this sets R to 3 and stores "0.1" into BUF.  */
  52
  53 int  ftoastr (char *buf, size_t bufsize, int flags, int width,       float x);
  54 int  dtoastr (char *buf, size_t bufsize, int flags, int width,      double x);
  55 int ldtoastr (char *buf, size_t bufsize, int flags, int width, long double x);
  56
  57 /* The last two functions except that the formatting takes place in
  58    the C locale.  */
  59 int  c_dtoastr (char *buf, size_t bufsize, int flags, int width,      double x);
  60 int c_ldtoastr (char *buf, size_t bufsize, int flags, int width, long double x);
  61
  62
  63 /* Flag values for ftoastr etc.  These can be ORed together.  */
  64 enum
  65   {
  66     /* Left justify within the width; the default is right justification.  */
  67     FTOASTR_LEFT_JUSTIFY = 1,
  68
  69     /* Output "+" before positive numbers; the default outputs nothing.  */
  70     FTOASTR_ALWAYS_SIGNED = 2,
  71
  72     /* Output " " before positive numbers; ignored if
  73        FTOASTR_ALWAYS_SIGNED is also given.  */
  74     FTOASTR_SPACE_POSITIVE = 4,
  75
  76     /* Pad with zeros instead of spaces; ignored if FTOASTR_LEFT_JUSTIFY
  77        is also given.  */
  78     FTOASTR_ZERO_PAD = 8,
  79
  80     /* Use 'E' instead of 'e' before the exponent.  */
  81     FTOASTR_UPPER_E = 16
  82   };
  83
  84
  85 /* _GL_FLT_PREC_BOUND is an upper bound on the precision needed to
  86    represent a float value without losing information.  Likewise for
  87    _GL_DBL_PREC_BOUND and double, and _GL_LDBL_PREC_BOUND and long double.
  88    These are macros, not enums, to work around a bug in IBM xlc 12.1.  */
  89
  90 #if FLT_RADIX == 10 /* decimal floating point */
  91 # define  _GL_FLT_PREC_BOUND  FLT_MANT_DIG
  92 # define  _GL_DBL_PREC_BOUND  DBL_MANT_DIG
  93 # define _GL_LDBL_PREC_BOUND LDBL_MANT_DIG
  94 #else
  95
  96 /* An upper bound on the number of bits needed to represent a single
  97    digit in a floating-point fraction.  */
  98 # if FLT_RADIX == 2 /* IEEE 754 floating point, VAX floating point, etc. */
  99 #  define _GL_FLOAT_DIG_BITS_BOUND 1
 100 # elif FLT_RADIX <= 16 /* IBM hex floating point has FLT_RADIX == 16.  */
 101 #  define _GL_FLOAT_DIG_BITS_BOUND 4
 102 # else /* no machine is this bad, but let's be complete */
 103 #  define _GL_FLOAT_DIG_BITS_BOUND ((int) TYPE_WIDTH (int) - 1)
 104 # endif
 105
 106 /* An upper bound on the number of decimal digits needed to represent
 107    a floating point number accurately, assuming a fraction contains
 108    DIG digits.  For why the "+ 1" is needed, see "Binary to Decimal
 109    Conversion" in David Goldberg's paper "What Every Computer
 110    Scientist Should Know About Floating-Point Arithmetic"
 111    <https://docs.oracle.com/cd/E19957-01/806-3568/ncg_goldberg.html>.  */
 112 # define _GL_FLOAT_PREC_BOUND(dig) \
 113    (INT_BITS_STRLEN_BOUND ((dig) * _GL_FLOAT_DIG_BITS_BOUND) + 1)
 114
 115 # define  _GL_FLT_PREC_BOUND _GL_FLOAT_PREC_BOUND ( FLT_MANT_DIG)
 116 # define  _GL_DBL_PREC_BOUND _GL_FLOAT_PREC_BOUND ( DBL_MANT_DIG)
 117 # define _GL_LDBL_PREC_BOUND _GL_FLOAT_PREC_BOUND (LDBL_MANT_DIG)
 118 #endif
 119
 120
 121 /* Bound on the number of bytes printed for an exponent in the range
 122    MIN..MAX, where MIN < 0 < MAX; printf always prints a sign and at
 123    least 2 digits.  Although the maximum known exponent is 4932 for
 124    IEEE 754 binary128, support tight bounds for exponents up to a
 125    million, just in case.  */
 126 #define _GL_FLOAT_EXPONENT_STRLEN_BOUND(min, max)  \
 127   (      -100 < (min) && (max) <     100 ? 3       \
 128    :    -1000 < (min) && (max) <    1000 ? 4       \
 129    :   -10000 < (min) && (max) <   10000 ? 5       \
 130    :  -100000 < (min) && (max) <  100000 ? 6       \
 131    : -1000000 < (min) && (max) < 1000000 ? 7       \
 132    : INT_STRLEN_BOUND (int) /* not a tight bound */)
 133
 134 /* A reasonably tight bound on the length of a type-T floating value
 135    formatted with ftoastr etc.  Room is needed for sign, fraction
 136    digits, decimal point, "e", and exponent.  POINTLEN should be a
 137    reasonably tight bound on the string length of the decimal
 138    point.  */
 139 #define _GL_FLOAT_STRLEN_BOUND_L(t, pointlen)                          \
 140   (1 + _GL_##t##_PREC_BOUND + pointlen + 1                             \
 141    + _GL_FLOAT_EXPONENT_STRLEN_BOUND (t##_MIN_10_EXP, t##_MAX_10_EXP))
 142 #define  FLT_STRLEN_BOUND_L(pointlen) _GL_FLOAT_STRLEN_BOUND_L ( FLT, pointlen)
 143 #define  DBL_STRLEN_BOUND_L(pointlen) _GL_FLOAT_STRLEN_BOUND_L ( DBL, pointlen)
 144 #define LDBL_STRLEN_BOUND_L(pointlen) _GL_FLOAT_STRLEN_BOUND_L (LDBL, pointlen)
 145
 146 /* Looser bounds that are locale-independent and are integral constant
 147    expressions.  */
 148 #define  FLT_STRLEN_BOUND  FLT_STRLEN_BOUND_L (MB_LEN_MAX)
 149 #define  DBL_STRLEN_BOUND  DBL_STRLEN_BOUND_L (MB_LEN_MAX)
 150 #define LDBL_STRLEN_BOUND LDBL_STRLEN_BOUND_L (MB_LEN_MAX)
 151
 152 /* Looser, locale-independent bounds that include the trailing null byte.  */
 153 #define  FLT_BUFSIZE_BOUND ( FLT_STRLEN_BOUND + 1)
 154 #define  DBL_BUFSIZE_BOUND ( DBL_STRLEN_BOUND + 1)
 155 #define LDBL_BUFSIZE_BOUND (LDBL_STRLEN_BOUND + 1)
 156
 157
 158 #ifdef __cplusplus
 159 }
 160 #endif
 161
 162 #endif /* _GL_FTOASTR_H */