[RFC]: add support for serializing a number to a string while avoiding exponential notation

[kgryte]

Description

This RFC proposes serializing a number to string while avoiding exponential notation.

The default behavior for JavaScript runtimes when serializing either very large (>=10^21) or very small (<10^-6) numbers to a string is to convert them to exponential notation. E.g.,

In [1]: (1 * base.pow(10,308)).toString()
Out[1]: '1e+308'

In [2]: (1 * base.pow(10,-323)).toString()
Out[2]: '1e-323'

However, in certain circumstances, you may want to avoid serializing to exponential notation and may prefer printing all digits (e.g., see discussion).

For example, the following may be desirable behavior

var str = serialize( 1e50 );
// returns '100000000000000000000000000000000000000000000000000'

This RFC proposes to add support for such behavior.

Package: @stdlib/number/to-string (?)
alias: number2string

Related Issues

No.

Questions

Built-in Number.prototype.toString( [radix] ) supports an optional radix argument. The proposed API would also support this argument, but also support an options object.

/**
* Serializes a number to a string.
*
* @param {(PositiveInteger|Options)} [options] - radix or options
* @param {PositiveInteger} [options.radix] - radix
* @param {boolean} [options.exponential=true] - boolean indicating whether to serialize very large and very small values to exponential notation
* @throws {TypeError} must provide either a positive integer or an options object
* @throws {TypeError} must provide valid options
* @throws {RangeError} radix must be a positive integer on the interval [2, 36]
* @returns {string} serialized number
*/
function number2string( options ) {
    // implementation...
}

Questions:

• Is overloading the existing built-in API desirable?
• Should serializing a number to a string in non-exponential format be a different package? If so, what would be that package's name?

Other

Prior art:

• SO

Checklist

• I have read and understood the Code of Conduct.
• Searched for existing issues and pull requests.
• The issue name begins with RFC:.

[WahyuFauzi]

I'm interested in working on this RFC and would be happy to be assigned the task.

[kgryte]

@Planeshifter Do you have opinions regarding the package name and whether overloading the built-in method is okay?

[kgryte]

@WahyuFauzi Before we okay someone working on this, we need to resolve the open questions discussed in the OP.

[WahyuFauzi]

Thanks for raising this, @kgryte. I agree it's important to address the open questions before moving forward.