POC Tokens::insertSlices

[keradus]

ref #4221
cc @kubawerlos , this is what we discussed in priv

[keradus]

This, unchanged Tokens collection is size of 20.
The fixer has to add 3 new tokens to this collection.

original code has to run offsetSet 45 times, as it has to move all tokens from strlen, then middle strlen, then from json_encode - which means that last strlen was moved 3 times!
my proposal has to run offsetSet only 20 times, as it has to move one token no more than once

Basically, this gives the possibility to reduce O(n) of calling offsetSet
from O(x*y)
to O(x+y)
where x is number of existing tokens and y is number of new tokens to insert

[keradus]

why I believe this is a good idea?
I pushed a fix for #3996 to this PR
see the time difference without and with this PR:
#3996 (comment)

[kubawerlos]

Is the name insertSlices fitting situation? Quite often (if not most times) we will use this to insert array of tokens. Wouldn't insertMultiple (or insertMany) better describe what the function is doing?

[dmvdbrugge]

Functionality seems good, just some minor points, up to you if you want to fix them.

[mvorisek]

Any progress on this?

Before merging check if the tests files can be reduced, I think the issue is not related to the overall length, so all keys/values can be probably changed to single char like 0 (zero) or '' (empty string).

[keradus]

@julienfalque , @SpacePossum , what do you think about the proposal in this PR? especially do we want to promote new method as new "best practice" or not?
https://github.com/FriendsOfPHP/PHP-CS-Fixer/pull/4250/files#diff-0ae0077906c99aaf35085e05c46cefd3R284

I think the issue is not related to the overall length, so all keys/values can be probably changed to single char like 0 (zero) or '' (empty string).

it can, i was just too lazy to modify example provided by original reporter.

[keradus]

Is the name insertSlices fitting situation? Quite often (if not most times) we will use this to insert array of tokens. Wouldn't insertMultiple (or insertMany) better describe what the function is doing?

for me, insertMultiple/insertMany is more fitting actual behaviour of insertAt, where we are pointing a single index, and adding multiple tokens to it:

$tokens->insertAt(15, $tokensCollection)
$tokens->insertAt(10, [$tokenA, $tokenB]);
$tokens->insertAt(5, $tokenC);

I'm trying to express that we are inserting different slices to different indexes at single call:

$tokens->insertSlices([
    5 => $tokenC,
    10 => [$tokenA, $tokenB],
    15 => $tokensCollection,
]);

---

we can always change the name later, as it's marked as internal

[coveralls]

Coverage increased (+0.006%) to 91.929% when pulling 07cf8b0 on keradus:2.12_insert_multi into be542fb on FriendsOfPHP:2.18.