[RFC] Implement mb_str_pad()

[nielsdos]

RFC: https://wiki.php.net/rfc/mb_str_pad
Implements GH-10203.

[nielsdos]

@alexdowad The RFC is accepted, and I have rebased this PR onto the latest master branch. This PR is now ready for review.
I would be grateful if you could review this sometime in the near future. Thanks :)

[alexdowad]

@nielsdos Congrats on successfully going through the RFC process.

[alexdowad]

@nielsdos Just read through the code. I'm not sure about the spec for the new function, but I trust that was already fully discussed during the RFC process and the new tests reflect whatever was agreed. Aside from that, the implementation looks great. You write beautiful code. It reads very, very well.

[alexdowad]

CI failure on MacOS is spurious.

[nielsdos]

Thank you!

In general, the behaviour is the same as with str_pad, but instead of working on bytes it works on character codepoints like the other mbstring functions.
The behaviour regarding edge cases, uneven pad lengths, exceptions, ... are all the same as for str_pad.

[sneycampos]

@nielsdos sorry for tagging you but i have a question: when i try to use mb_str_pad with a null value it throws an error, since the str_pad doesn't thrown an error when a null value is passed as value, this is expected or may be considered breaking change?

E.g:

$value = null;
str_pad(null, 4, '0', STR_PAD_LEFT)
// returns 0000

$value = null;
mb_str_pad(0, 4, '0', STR_PAD_LEFT);
//TypeError mb_str_pad(): Argument #1 ($string) must be of type string, null given

[nielsdos]

@sneycampos I'm not sure I understand you code sample, you pass 0 as first argument of mb_str_pad, but even if I pass null it just throws a deprecation: https://3v4l.org/vYaqp This is the same behaviour as for str_pad.
Under strict mode both str_pad and mb_str_pad will throw an exception: https://3v4l.org/i6Fkl

[sneycampos]

Sorry, the zero was a typo. And i just noticed right now that i am not using php 8.3 for this tests, i'm using php 8.2 in a Laravel Project and this function call comes from symfony's polyfill 80, not from php 8.3 sc.

Thanks anyway and sorry for bothering you.