reference/strings/functions/str-split.xml
e1621b408bdd443153611090847023aa39829bb0
e1621b408bdd443153611090847023aa39829bb0
...
...
@@ -1,6 +1,6 @@
1
1
<?xml version="1.0" encoding="utf-8"?>
2
2
<!-- $Revision$ -->
3
-
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.str-split">
3
+
<refentry xml:id="function.str-split" xmlns="http://docbook.org/ns/docbook">
4
4
<refnamediv>
5
5
<refname>str_split</refname>
6
6
<refpurpose>Convert a string to an array</refpurpose>
...
...
@@ -11,7 +11,7 @@
11
11
<methodsynopsis>
12
12
<type>array</type><methodname>str_split</methodname>
13
13
<methodparam><type>string</type><parameter>string</parameter></methodparam>
14
-
<methodparam choice="opt"><type>int</type><parameter>split_length</parameter><initializer>1</initializer></methodparam>
14
+
<methodparam choice="opt"><type>int</type><parameter>length</parameter><initializer>1</initializer></methodparam>
15
15
</methodsynopsis>
16
16
<para>
17
17
Converts a string to an array.
...
...
@@ -31,7 +31,7 @@
31
31
</listitem>
32
32
</varlistentry>
33
33
<varlistentry>
34
-
<term><parameter>split_length</parameter></term>
34
+
<term><parameter>length</parameter></term>
35
35
<listitem>
36
36
<para>
37
37
Maximum length of the chunk.
...
...
@@ -45,19 +45,54 @@
45
45
<refsect1 role="returnvalues">
46
46
&reftitle.returnvalues;
47
47
<para>
48
-
If the optional <parameter>split_length</parameter> parameter is
48
+
If the optional <parameter>length</parameter> parameter is
49
49
specified, the returned array will be broken down into chunks with each
50
-
being <parameter>split_length</parameter> in length, otherwise each chunk
51
-
will be one character in length.
50
+
being <parameter>length</parameter> in length, except the final chunk
51
+
which may be shorter if the string does not divide evenly. The default
52
+
<parameter>length</parameter> is <literal>1</literal>, meaning every chunk will be one byte in size.
52
53
</para>
54
+
</refsect1>
55
+
56
+
<refsect1 role="errors">
57
+
&reftitle.errors;
53
58
<para>
54
-
&false; is returned if <parameter>split_length</parameter> is less than 1.
55
-
If the <parameter>split_length</parameter> length exceeds the length of
56
-
<parameter>string</parameter>, the entire string is returned as the first
57
-
(and only) array element.
59
+
If <parameter>length</parameter> is less than <literal>1</literal>,
60
+
a <classname>ValueError</classname> will be thrown.
58
61
</para>
59
62
</refsect1>
60
63
64
+
<refsect1 role="changelog">
65
+
&reftitle.changelog;
66
+
<informaltable>
67
+
<tgroup cols="2">
68
+
<thead>
69
+
<row>
70
+
<entry>&Version;</entry>
71
+
<entry>&Description;</entry>
72
+
</row>
73
+
</thead>
74
+
<tbody>
75
+
<row>
76
+
<entry>8.2.0</entry>
77
+
<entry>
78
+
If <parameter>string</parameter> is empty an empty &array; is now returned.
79
+
Previously an &array; containing a single empty string was returned.
80
+
</entry>
81
+
</row>
82
+
<row>
83
+
<entry>8.0.0</entry>
84
+
<entry>
85
+
If <parameter>length</parameter> is less than <literal>1</literal>,
86
+
a <classname>ValueError</classname> will be thrown now;
87
+
previously, an error of level <constant>E_WARNING</constant>
88
+
has been raised instead, and the function returned &false;.
89
+
</entry>
90
+
</row>
91
+
</tbody>
92
+
</tgroup>
93
+
</informaltable>
94
+
</refsect1>
95
+
61
96
<refsect1 role="examples">
62
97
&reftitle.examples;
63
98
<para>
...
...
@@ -115,6 +150,7 @@ Array
115
150
<note>
116
151
<para>
117
152
<function>str_split</function> will split into bytes, rather than characters when dealing with a multi-byte encoded string.
153
+
Use <function>mb_str_split</function> to split the string into code points.
118
154
</para>
119
155
</note>
120
156
</refsect1>
...
...
@@ -123,6 +159,7 @@ Array
123
159
&reftitle.seealso;
124
160
<para>
125
161
<simplelist>
162
+
<member><function>mb_str_split</function></member>
126
163
<member><function>chunk_split</function></member>
127
164
<member><function>preg_split</function></member>
128
165
<member><function>explode</function></member>
...
...
@@ -134,7 +171,6 @@ Array
134
171
</refsect1>
135
172
136
173
</refentry>
137
-
138
174
<!-- Keep this comment at the end of the file
139
175
Local variables:
140
176
mode: sgml
141
177