/*

 * Copyright (c) Meta Platforms, Inc. and affiliates.

 *

 * This source code is licensed under the MIT license found in the

 * LICENSE file in the root directory of this source tree.

 */

// dtoa doesn't provide a header file so this simple one was created.

#ifndef HERMES_DTOA_DTOA_H

#define HERMES_DTOA_DTOA_H

#ifdef __cplusplus

extern "C" {

#endif

/// dtoa functions need to allocate memory and that job is handled by the dtoa

/// allocator. \c dtoa_alloc is an opaque struct representing the allocator. It

/// is created by calling \c dtoa_alloc_init() with a pointer to a memory

/// buffer declared with \c DECL_DTOA_ALLOC_MEM(name, size).

///

/// The allocator metadata itself is placed in that memory buffer and the rest

/// of it is used to satisfy memory allocations. If it is not enough, additional

/// allocations are made in the regular heap with malloc()/free(). So, the

/// larger the buffer declared by \c DECL_DTOA_ALLOC_MEM(), the less probability

/// there that a heap allocation will be needed.

///

/// The allocator is not thread safe, so we must guarantee that it is used only

/// by one thread a time. Usually we just create it on the stack (which is very

/// fast), but it could live in other places, as long as the single thread

/// requirement is satisfied.

///

/// The allocator metadata itself is less than 128 bytes - the rest is the

/// "allocation buffer". The dtoa documentation states that 2304 byte allocation

/// buffer is sufficient for most cases except the unusual ones, and a 7400 byte

/// allocation buffer is sufficient for all cases.

///

/// We don't need to avoid heap allocation at all costs, so we have chosen a

/// total allocator size of 1200 bytes, which seems to avoid heap allocations

/// for "normal" cases.

typedef struct dtoa_alloc dtoa_alloc;

/// The minimal size of the dtoa allocator memory buffer. The metadata is less

/// than 128 bytes and the rest is available to satisfy dtoa allocations.

#define DTOA_ALLOC_MIN_SIZE 256

/// The default size of the dtoa allocator memory buffer, which we use when

/// declaring it on the stack. The value attempts to find balance between

/// excessive stack consumption and avoiding allocations for "normal" cases.

#define DTOA_ALLOC_DEFAULT_SIZE 1200

/// This macro is used to declare a memory buffer for the dtoa allocator. Most

/// of all it ensures that the memory is properly aligned. The variable declared

/// by this macro is then passed to \c dtoa_alloc_init().

#define DECL_DTOA_ALLOC_MEM(name, bytelen) \

  union {                                  \

    void *p;                               \

    double d;                              \

    long long l;                           \

    char mem[(bytelen)];                   \

  } name

/// Initialize an allocator using the specified memory buffer, and return a

/// pointer to the allocator. Note that this does not stipulate that the

/// returned pointer will equal \c mem.

dtoa_alloc *dtoa_alloc_init(void *mem, int bytelen);

/// Destroy the previously initialized allocator. Primarily, this call frees

/// any heap allocations in the allocator.

void dtoa_alloc_done(dtoa_alloc *dalloc);

/// Converts double into ascii string.

/// \param dd the double to convert.

/// \param mode the rounding mode, 0 for default.<ul>

///     <li>0 ==> shortest string that yields d when read in

///             and rounded to nearest.

///     <li>1 ==> like 0, but with Steele & White stopping rule;

///             e.g. with IEEE P754 arithmetic , mode 0 gives

///             1e23 whereas mode 1 gives 9.999999999999999e22.

///     <li>2 ==> max(1,ndigits) significant digits.  This gives a

///             return value similar to that of ecvt, except

///             that trailing zeros are suppressed.

///     <li>3 ==> through ndigits past the decimal point.  This

///             gives a return value similar to that from fcvt,

///             except that trailing zeros are suppressed, and

///             ndigits can be negative.

///     <li>4,5 ==> similar to 2 and 3, respectively, but (in

///             round-nearest mode) with the tests of mode 0 to

///             possibly return a shorter string that rounds to d.

///             With IEEE arithmetic and compilation with

///             -DHonor_FLT_ROUNDS, modes 4 and 5 behave the same

///             as modes 2 and 3 when FLT_ROUNDS != 1.

///     <li>6-9 ==> Debugging modes similar to mode - 4:  don't try

///             fast floating-point estimate (if applicable).

///     <li>Values of mode other than 0-9 are treated as mode 0.

/// </ul>

/// \param ndigits number of digits of precision, 0 for default.

/// \param decpt where to store position of the decimal. (n in ES5.1 9.8.1)

/// \param sign location to store 1 if negative number, 0 if positive number.

/// \param rve location to store pointer to the end of the returned string.

/// \return string representation of s in ES5.1 9.8.1

char *g_dtoa(

    dtoa_alloc *dalloc,

    double dd,

    int mode,

    int ndigits,

    int *decpt,

    int *sign,

    char **rve);

/// Same as dtoa, but #defines ROUND_BIASED, which enables the mode which is

/// used for getting results with a fixed number of digits after the decimal.

/// It also modifies a check in dtoa (see the NOTE in dtoa_fixed.c),

/// which ensures that 0.5 does not get flushed to 0, but rather rounds up to 1.

/// A separate function is necessary because dtoa needs compilation flags

/// to change options and provides no runtime means of doing so,

/// and modification of the code was needed to ensure correctly biased rounding.

char *dtoa_fixedpoint(

    dtoa_alloc *dalloc,

    double dd,

    int mode,

    int ndigits,

    int *decpt,

    int *sign,

    char **rve);

/// Free the result of \c g_dtoa() and \c dtoa_fixedpoint().

void g_freedtoa(dtoa_alloc *dalloc, char *);

char *g_fmt(char *, double);

double hermes_g_strtod(const char *s00, char **se);

#ifdef __cplusplus

}

#endif

#ifdef __cplusplus

/// A convenience RAII wrapper around a dtoa allocator. The usage should be

/// self-explanatory. Declare it on the stack (or as a class member), supplying

/// the memory buffer size, and pass it to the dtoa functions.

template <int bytelen = DTOA_ALLOC_DEFAULT_SIZE>

class DtoaAllocator {

 public:

  DtoaAllocator(const DtoaAllocator &) = delete;

  void operator=(const DtoaAllocator &) = delete;

  DtoaAllocator() {

    dalloc_ = dtoa_alloc_init(&mem_, bytelen);

  }

  ~DtoaAllocator() {

    dtoa_alloc_done(dalloc_);

  }

  operator dtoa_alloc *() {

    return dalloc_;

  }

 private:

  DECL_DTOA_ALLOC_MEM(mem_, bytelen);

  dtoa_alloc *dalloc_;

};

#endif

#endif // HERMES_DTOA_DTOA_H