Deprecate Grisu?

[jw3126]

Can we have a depwarn for Grisu instead of removing it straight? I assumed it was part of the public API, since it is documented?

help?> Base.Grisu.grisu
  (len, point, neg) = Grisu.grisu(v::AbstractFloat, mode, requested_digits, [buffer], [bignums])

...

It is a dependency of Showoff, which breaks plotting on master for me.

[KristofferC]

I assumed it was part of the public API, since it is documented?

Where was it documented?

[DilumAluthge]

The docstring is here:

julia/base/grisu/grisu.jl

Lines 40 to 61 in 10f5a05

	"""
	(len, point, neg) = Grisu.grisu(v::AbstractFloat, mode, requested_digits, [buffer], [bignums])
	Convert the number `v` to decimal using the Grisu algorithm.
	`mode` can be one of:
	- `Grisu.SHORTEST`: convert to the shortest decimal representation which can be "round-tripped" back to `v`.
	- `Grisu.FIXED`: round to `requested_digits` digits.
	- `Grisu.PRECISION`: round to `requested_digits` significant digits.
	The characters are written as bytes to `buffer`, with a terminating NUL byte, and `bignums` are used internally as part of the correction step. You can call `Grisu.getbuf()` to obtain a suitable task-local buffer.
	The returned tuple contains:
	- `len`: the number of digits written to `buffer` (excluding NUL)
	- `point`: the location of the radix point relative to the start of the array (e.g. if
	`point == 3`, then the radix point should be inserted between the 3rd and 4th
	digit). Note that this can be negative (for very small values), or greater than `len`
	(for very large values).
	- `neg`: the signbit of `v` (see [`signbit`](@ref)).
	"""
	function grisu(v::AbstractFloat,mode,requested_digits,buffer=DIGITSs[Threads.threadid()],bignums=BIGNUMSs[Threads.threadid()])

The tricky part is: I didn't think that something is part of the public API just because it's documented? I thought something is part of the public API only if at least one of the following criteria is satisfied:

1. It is exported from Base
2. The docstring explicitly says that it is part of the public API

[KristofferC]

I thought something is part of the public API only if at least one of the following criteria is satisfied:

Rather, if it is in the manual or exported.

But yeah, internal docstrings are not considered public API.

[jw3126]

Ok got it, it is not part of the stable API, so its lawful to just remove it. Can we still have a depwarn? It is de facto used by people. Also the files are still present in the repo just not included? https://github.com/JuliaLang/julia/tree/master/base/grisu

[KristofferC]

That's one file and looks like it was just forgotten to be deleted.

[quinnj]

Removing the remaining grisu files here: 73c4890

[quinnj]

I commented on the Showoff issue that it should be much easier to do what they were trying there by "dynamically" formatting float values; there's a new Printf.format(fmt::Printf.Format, args...) function that allows constructing/passing in a Printf.Format object and formatting the result as a string (or passing an io as the 1st argument will print the result directly).