Document str_increment() and str_decrement()

[Girgias]

Part of #2796

[saundefined]

Looks good, thanks!

[TimWolla]

When is that? At "0"?

[mumumu]

When is that? At "0"?

Seems to At "1".
ValueError is thrown if we try to decrement "1".

<?php

$a = 'a5';
for ($i = 0; $i < 1000; $i++) {
    var_dump("decrementing $a");
    $a = str_decrement($a);
    var_dump($a);
}

sapi/cli/php test.php
string(15) "decrementing a1"
string(2) "a0"
string(15) "decrementing a0"
string(1) "9"
string(14) "decrementing 9"
string(1) "8"
string(14) "decrementing 8"
string(1) "7"
string(14) "decrementing 7"
string(1) "6"
string(14) "decrementing 6"
string(1) "5"
string(14) "decrementing 5"
string(1) "4"
string(14) "decrementing 4"
string(1) "3"
string(14) "decrementing 3"
string(1) "2"
string(14) "decrementing 2"
string(1) "1"
string(14) "decrementing 1"

Fatal error: Uncaught ValueError: str_decrement(): Argument #1 ($string) "1" is out of decrement range in /home/mumumu/build/php-src/test.php:6

[mumumu]

It may be better to describe the decrement range by example. @Girgias

[Girgias]

I might need to ask @iluuu1994 as he changed the decrement function after merging the RFC PR.

[iluuu1994]

Right, "1" erroring is a bug. The fix is here: php/php-src#12339

This error occurs when there's a remaining carry after all digits have been decremented. This can occur for string like "000", "0a", etc. The leading digit is also removed if it is a 0 (e.g. when going from "10" to "09"). However, I have not considered the case of "1" going to "0", with only a single digit, which does not need to be removed.