Skip to content
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.

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

[PHP 8.4] Add manual for grapheme_str_split function #3956

Merged
merged 9 commits into from
Oct 30, 2024
99 changes: 99 additions & 0 deletions reference/intl/grapheme/grapheme-str-split.xml
Original file line number Diff line number Diff line change
@@ -0,0 +1,99 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="function.grapheme-str-split" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>grapheme_str_split</refname>
<refpurpose>Split a string into an array</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type class="union"><type>array</type><type>false</type></type><methodname>grapheme_str_split</methodname>
<methodparam><type>string</type><parameter>string</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>length</parameter><initializer>1</initializer></methodparam>
</methodsynopsis>
<para>
This function will return an array of strings,
it is a version of <function>str_split</function>
with support for grapheme cluster byte characters.
If the <parameter>length</parameter> parameter is specified,
the string is broken down into chunks of the specified length
in grapheme clusters (not bytes).
</para>
</refsect1>

<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>string</parameter></term>
<listitem>
<para>
The <type>string</type> to split into grapheme clusters or chunks.
<parameter>string</parameter> must be valid UTF-8.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>length</parameter></term>
<listitem>
<para>
Each element of the returned array will be composed of <parameter>length</parameter> grapheme clusters.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>

<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
<function>grapheme_str_split</function> returns an array of strings, &return.falseforfailure;.
</para>
</refsect1>

<refsect1 role="errors">
&reftitle.errors;
<para>
If <parameter>length</parameter> is less than <literal>1</literal>,
a <classname>ValueError</classname> will be thrown.
</para>
</refsect1>

<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>str_split</function></member>
<member><function>mb_str_split</function></member>
<member>
<link xlink:href="&uri.unicode.graphemes;">
Unicode Text Segmentation: Grapheme Cluster Boundaries
</link>
youkidearitai marked this conversation as resolved.
Show resolved Hide resolved
</member>
</simplelist>
</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/intl/versions.xml
Original file line number Diff line number Diff line change
Expand Up @@ -392,6 +392,7 @@
<function name="grapheme_strstr" from="PHP 5 &gt;= 5.3.0, PHP 7, PHP 8, PECL intl &gt;= 1.0.0"/>
<function name="grapheme_stristr" from="PHP 5 &gt;= 5.3.0, PHP 7, PHP 8, PECL intl &gt;= 1.0.0"/>
<function name="grapheme_extract" from="PHP 5 &gt;= 5.3.0, PHP 7, PHP 8, PECL intl &gt;= 1.0.0"/>
<function name="grapheme_str_split" from="PHP 8 &gt;= 8.4.0"/>
<function name="intl_get_error_code" from="PHP 5 &gt;= 5.3.0, PHP 7, PHP 8, PECL intl &gt;= 1.0.0"/>
<function name="intl_get_error_message" from="PHP 5 &gt;= 5.3.0, PHP 7, PHP 8, PECL intl &gt;= 1.0.0"/>
<function name="intl_is_failure" from="PHP 5 &gt;= 5.3.0, PHP 7, PHP 8, PECL intl &gt;= 1.0.0"/>
Expand Down
1 change: 1 addition & 0 deletions reference/mbstring/functions/mb-str-split.xml
Original file line number Diff line number Diff line change
Expand Up @@ -89,6 +89,7 @@
<para>
<simplelist>
<member><function>str_split</function></member>
<member><function>grapheme_str_split</function></member>
</simplelist>
</para>
</refsect1>
Expand Down
4 changes: 3 additions & 1 deletion reference/strings/functions/str-split.xml
Original file line number Diff line number Diff line change
Expand Up @@ -150,7 +150,8 @@ Array
<note>
<para>
<function>str_split</function> will split into bytes, rather than characters when dealing with a multi-byte encoded string.
Use <function>mb_str_split</function> to split the string into code points.
<function>mb_str_split</function> can be used to split the string into code points.
<function>grapheme_str_split</function> can be used to split the string into grapheme clusters.
</para>
</note>
</refsect1>
Expand All @@ -160,6 +161,7 @@ Array
<para>
<simplelist>
<member><function>mb_str_split</function></member>
<member><function>grapheme_str_split</function></member>
<member><function>chunk_split</function></member>
<member><function>preg_split</function></member>
<member><function>explode</function></member>
Expand Down