@stof I'm not sure what you're pointing here. The documentation or the implementation? Your use case seems handled (see this [test](https://github.com/symfony/symfony/pull/6111/files#L5R400)).

Anyway you're right, the internal documentation of the method is bad & need to be rewritten. But before that, I would like to get feedback about the implementation as the previous one relies heavily on `array_search`, `array_slice` and `array_merge` which are expensive operations as pointed by @bschussek