Skip to content

Copy and modify mb_str_pad from str_pad #2750

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Girgias merged 8 commits into from
Oct 5, 2023
Merged

Copy and modify mb_str_pad from str_pad #2750

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
b17c366
Copy and modify mb_str_pad from str_pad
youkidearitai Sep 7, 2023
bdb3efe
Add new examples with emoji
youkidearitai Sep 7, 2023
4946c56
remove whitespace
youkidearitai Sep 7, 2023
2cf72c9
remove blank line at EOF
youkidearitai Sep 7, 2023
2c95be9
Update suggested changes from nielsdos-san. thanks.
youkidearitai Sep 8, 2023
af6cd0c
Remove aliases.
youkidearitai Sep 8, 2023
29e825b
Fix parameter description
youkidearitai Sep 8, 2023
b13ccc0
add version infomation
youkidearitai Sep 8, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
133 changes: 133 additions & 0 deletions reference/mbstring/functions/mb-str-pad.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,133 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="function.mb-str-pad" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>mb_str_pad</refname>
<refpurpose>Pad a multibyte string to a certain length with another multibyte string</refpurpose>
</refnamediv>

<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>string</type><methodname>mb_str_pad</methodname>
<methodparam><type>string</type><parameter>string</parameter></methodparam>
<methodparam><type>int</type><parameter>length</parameter></methodparam>
<methodparam choice="opt"><type>string</type><parameter>pad_string</parameter><initializer>" "</initializer></methodparam>
<methodparam choice="opt"><type>int</type><parameter>pad_type</parameter><initializer><constant>STR_PAD_RIGHT</constant></initializer></methodparam>
<methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>encoding</parameter><initializer>&null;</initializer></methodparam>
</methodsynopsis>
<para>
This function returns the <parameter>string</parameter>
padded on the left, the right, or both sides to the specified
padding length, where the length is measured in Unicode codepoints. If the optional argument
<parameter>pad_string</parameter> is not supplied, the
<parameter>string</parameter> is padded with spaces, otherwise it
is padded with characters from <parameter>pad_string</parameter>
up to the limit.
</para>
</refsect1>

<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>string</parameter></term>
<listitem>
<para>
The input string.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>length</parameter></term>
<listitem>
<para>
If the value of <parameter>length</parameter> is negative,
Copy link
Copy Markdown
Member

@Girgias Girgias Sep 8, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is no ValueError emitted for negative lengths?

Copy link
Copy Markdown
Contributor Author

@youkidearitai youkidearitai Sep 8, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, no ValueError throws.

$ sapi/cli/php -r 'var_dump(mb_str_pad("あいうえお", -333, "🎉", STR_PAD_BOTH));'
string(15) "あいうえお"

Copy link
Copy Markdown
Member

@Girgias Girgias Sep 8, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

sad :(

less than, or equal to the length of the input string, no padding
takes place, and <parameter>string</parameter> will be returned.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>pad_string</parameter></term>
<listitem>
<note>
<para>
The <parameter>pad_string</parameter> may be truncated if the
required number of padding characters can't be evenly divided by the
<parameter>pad_string</parameter>'s length.
</para>
</note>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>pad_type</parameter></term>
<listitem>
<para>
Optional argument <parameter>pad_type</parameter> can be
<constant>STR_PAD_RIGHT</constant>, <constant>STR_PAD_LEFT</constant>,
or <constant>STR_PAD_BOTH</constant>.
By default <constant>STR_PAD_RIGHT</constant>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>encoding</parameter></term>
<listitem>
&mbstring.encoding.parameter;
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>

<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns the padded string.
</para>
</refsect1>


<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>mb_str_pad</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
var_dump(mb_str_pad('▶▶', 6, '❤❓❇', STR_PAD_RIGHT)); // string(18) "▶▶❤❓❇❤"
var_dump(mb_str_pad('▶▶', 6, '❤❓❇', STR_PAD_LEFT)); // string(18) "❤❓❇❤▶▶"
var_dump(mb_str_pad('▶▶', 6, '❤❓❇', STR_PAD_BOTH)); // string(18) "❤❓▶▶❤❓"

var_dump(mb_str_pad("🎉", 3, "祝", STR_PAD_LEFT))); // string(10) "祝祝🎉"
?>
]]>
</programlisting>
</example>
</para>
</refsect1>

</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
1 change: 1 addition & 0 deletions reference/mbstring/versions.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,7 @@
<function name="mb_scrub" from="PHP 7 &gt;= 7.2.0, PHP 8"/>
<function name="mb_send_mail" from="PHP 4 &gt;= 4.0.6, PHP 5, PHP 7, PHP 8"/>
<function name="mb_split" from="PHP 4 &gt;= 4.2.0, PHP 5, PHP 7, PHP 8"/>
<function name="mb_str_pad" from="PHP 8 &gt;= PHP 8.3.0"/>
<function name="mb_strcut" from="PHP 4 &gt;= 4.0.6, PHP 5, PHP 7, PHP 8"/>
<function name="mb_strimwidth" from="PHP 4 &gt;= 4.0.6, PHP 5, PHP 7, PHP 8"/>
<function name="mb_stripos" from="PHP 5 &gt;= 5.2.0, PHP 7, PHP 8"/>
Expand Down