reference/intl/grapheme/grapheme-extract.xml
2245ff665ae4b3037728ee52c247b409ad75de35
2245ff665ae4b3037728ee52c247b409ad75de35
...
...
@@ -3,18 +3,18 @@
3
3
<refentry xml:id="function.grapheme-extract" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
4
4
<refnamediv>
5
5
<refname>grapheme_extract</refname>
6
-
<refpurpose>Function to extract a sequence of default grapheme clusters from a text buffer, which must be encoded in UTF-8.</refpurpose>
6
+
<refpurpose>Function to extract a sequence of default grapheme clusters from a text buffer, which must be encoded in UTF-8</refpurpose>
7
7
</refnamediv>
8
8
<refsect1 role="description">
9
9
&reftitle.description;
10
10
<para>&style.procedural;</para>
11
11
<methodsynopsis>
12
-
<type>string</type><methodname>grapheme_extract</methodname>
12
+
<type class="union"><type>string</type><type>false</type></type><methodname>grapheme_extract</methodname>
13
13
<methodparam><type>string</type><parameter>haystack</parameter></methodparam>
14
14
<methodparam><type>int</type><parameter>size</parameter></methodparam>
15
-
<methodparam choice="opt"><type>int</type><parameter>extract_type</parameter></methodparam>
16
-
<methodparam choice="opt"><type>int</type><parameter>start</parameter><initializer>0</initializer></methodparam>
17
-
<methodparam choice="opt"><type>int</type><parameter role="reference">next</parameter></methodparam>
15
+
<methodparam choice="opt"><type>int</type><parameter>type</parameter><initializer><constant>GRAPHEME_EXTR_COUNT</constant></initializer></methodparam>
16
+
<methodparam choice="opt"><type>int</type><parameter>offset</parameter><initializer>0</initializer></methodparam>
17
+
<methodparam choice="opt"><type>int</type><parameter role="reference">next</parameter><initializer>&null;</initializer></methodparam>
18
18
</methodsynopsis>
19
19
<para>
20
20
Function to extract a sequence of default grapheme clusters from a text buffer, which must be encoded in UTF-8.
...
...
@@ -37,35 +37,36 @@
37
37
<term><parameter>size</parameter></term>
38
38
<listitem>
39
39
<para>
40
-
Maximum number items - based on the $extract_type - to return.
40
+
Maximum number items - based on the <parameter>type</parameter> - to return.
41
41
</para>
42
42
</listitem>
43
43
</varlistentry>
44
44
<varlistentry>
45
-
<term><parameter>extract_type</parameter></term>
45
+
<term><parameter>type</parameter></term>
46
46
<listitem>
47
47
<para>
48
-
Defines the type of units referred to by the $size parameter:
48
+
Defines the type of units referred to by the <parameter>size</parameter> parameter:
49
49
</para>
50
50
<para>
51
51
<simplelist>
52
-
<member>GRAPHEME_EXTR_COUNT (default) - $size is the number of default
52
+
<member>GRAPHEME_EXTR_COUNT (default) -<parameter>size</parameter> is the number of default
53
53
grapheme clusters to extract.</member>
54
-
<member>GRAPHEME_EXTR_MAXBYTES - $size is the maximum number of bytes
54
+
<member>GRAPHEME_EXTR_MAXBYTES -<parameter>size</parameter> is the maximum number of bytes
55
55
returned.</member>
56
-
<member>GRAPHEME_EXTR_MAXCHARS - $size is the maximum number of UTF-8
56
+
<member>GRAPHEME_EXTR_MAXCHARS - <parameter>size</parameter> is the maximum number of UTF-8
57
57
characters returned.</member>
58
58
</simplelist>
59
59
</para>
60
60
</listitem>
61
61
</varlistentry>
62
62
<varlistentry>
63
-
<term><parameter>start</parameter></term>
63
+
<term><parameter>offset</parameter></term>
64
64
<listitem>
65
65
<para>
66
-
Starting position in $haystack in bytes - if given, it must be zero or a
67
-
positive value that is less than or equal to the length of $haystack in
68
-
bytes. If $start does not point to the first byte of a UTF-8
66
+
Starting position in <parameter>haystack</parameter> in bytes - if given, it must be zero or a
67
+
positive value that is less than or equal to the length of <parameter>haystack</parameter> in
68
+
bytes, or a negative value that counts from the end of <parameter>haystack</parameter>.
69
+
If <parameter>offset</parameter> does not point to the first byte of a UTF-8
69
70
character, the start position is moved to the next character boundary.
70
71
</para>
71
72
</listitem>
...
...
@@ -88,11 +89,34 @@
88
89
<refsect1 role="returnvalues">
89
90
&reftitle.returnvalues;
90
91
<para>
91
-
A string starting at offset $start and ending on a default grapheme cluster
92
-
boundary that conforms to the $size and $extract_type specified.
92
+
A string starting at offset <parameter>offset</parameter> and ending on a default grapheme cluster
93
+
boundary that conforms to the <parameter>size</parameter> and <parameter>type</parameter> specified,
94
+
&return.falseforfailure;.
93
95
</para>
94
96
</refsect1>
95
97
98
+
<refsect1 role="changelog">
99
+
&reftitle.changelog;
100
+
<informaltable>
101
+
<tgroup cols="2">
102
+
<thead>
103
+
<row>
104
+
<entry>&Version;</entry>
105
+
<entry>&Description;</entry>
106
+
</row>
107
+
</thead>
108
+
<tbody>
109
+
<row>
110
+
<entry>7.1.0</entry>
111
+
<entry>
112
+
Support for negative <parameter>offset</parameter>s has been added.
113
+
</entry>
114
+
</row>
115
+
</tbody>
116
+
</tgroup>
117
+
</informaltable>
118
+
</refsect1>
119
+
96
120
<refsect1 role="examples">
97
121
&reftitle.examples;
98
122
<example>
...
...
@@ -132,7 +156,6 @@ o%CC%88
132
156
</para>
133
157
</refsect1>
134
158
</refentry>
135
-
136
159
<!-- Keep this comment at the end of the file
137
160
Local variables:
138
161
mode: sgml
139
162