Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:121327
Message-ID: <c4b40b7a-aa8b-470f-ae07-1485c010d907@bastelstu.be>
Date: Sun, 15 Oct 2023 19:24:47 +0200
MIME-Version: 1.0
To: David Grudl <david@grudl.com>, internals@lists.php.net
References: <CAL-Ucw7H4zcbnhUJHHPi9=KX9NtPEVKiCOyNz+TTJfdwkzLRTw@mail.gmail.com>
Content-Language: en-US
In-Reply-To: <CAL-Ucw7H4zcbnhUJHHPi9=KX9NtPEVKiCOyNz+TTJfdwkzLRTw@mail.gmail.com>
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 8bit
Subject: Re: [PHP-DEV] Better name for method Randomizer::nextFloat()
From: tim@bastelstu.be (=?UTF-8?Q?Tim_D=C3=BCsterhus?=)

Hi

On 10/14/23 19:47, David Grudl wrote:
> random number in the interval 0...1, so it does the same thing as
> getFloat(0, 1).  See
> https://wiki.php.net/rfc/randomizer_additions#nextfloat

For the record: That is correct.

> B) When trying to think of a more appropriate name (e.g.
> `getFloat01()` ?), I find that the simple `getFloat(0, 1) is concise
> and succinct enough. If it were really useful to have a method that
> returns numbers in this interval, wouldn't it be better to give the
> $min and $max parameters the default values of 0 and 1, and thus call
> `getFloat()` directly?

Yes, the right-open interval [0, 1) is useful to have as a special case, 
because it directly maps onto percentages, allowing you to easily 
generate booleans with a specific chance.

Making those default values of getFloat() wouldn't be better, though. It 
is not meaningful to only provide *one* of the boundaries (specifically 
$min), but PHP does not support overloaded signatures without 
func_num_args() trickery and this was banned for internal functions as 
of this RFC:

https://wiki.php.net/rfc/deprecate_functions_with_overloaded_signatures#policy_about_new_functions

Making getFloat(float $min = 0.0, float $max = 1.0, IntervalBoundary 
$boundary = IntervalBoundary::ClosedOpen) would seemingly make it legal 
to call ->getFloat(0.5), which I consider to be worse than nextFloat().

Side note: The implementation of nextFloat() is much more efficient than 
that of getFloat(0.0, 1.0) and the output will differ even for the same 
seeded engine. The domain of legal return values is identical.

> C) PHP 8.3 is still in testing and this change can be made. If it is
> not done now, it will never be done and programmers will have to use
> and also read unintuitive APIs for years. Similarly, in the days
> before PHP 8.0 was released, I suggested changing PhpToken::getAll()
> to today's tokenize() and there was no problem with that
> https://bugs.php.net/bug.php?id=80328

The release managers would need to decide whether a change would be 
legal at this point in the release process, but I strongly doubt it, 
especially since naming is inherently bike-shedding territory and since 
the method name is already in various blog articles and in the 
documentation.

For the same reason I'm not sure if comparing this to PhpToken::getAll() 
/ tokenize() is a useful comparison, since the tokenizer is a very 
specialized feature that only few developers will care about. Making a 
breaking change late in the release process will have a much smaller 
impact to existing documentation / blog articles / feature videos / etc.

Best regards
Tim Düsterhus