1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
|
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="function.iconv-substr" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>iconv_substr</refname>
<refpurpose>Cut out part of a string</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type class="union"><type>string</type><type>false</type></type><methodname>iconv_substr</methodname>
<methodparam><type>string</type><parameter>string</parameter></methodparam>
<methodparam><type>int</type><parameter>offset</parameter></methodparam>
<methodparam choice="opt"><type class="union"><type>int</type><type>null</type></type><parameter>length</parameter><initializer>&null;</initializer></methodparam>
<methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>encoding</parameter><initializer>&null;</initializer></methodparam>
</methodsynopsis>
<para>
Cuts a portion of <parameter>string</parameter> specified by the
<parameter>offset</parameter> and <parameter>length</parameter> parameters.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>string</parameter></term>
<listitem>
<para>
The original string.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>offset</parameter></term>
<listitem>
<para>
If <parameter>offset</parameter> is non-negative,
<function>iconv_substr</function> cuts the portion out of
<parameter>string</parameter> beginning at <parameter>offset</parameter>'th
character, counting from zero.
</para>
<para>
If <parameter>offset</parameter> is negative,
<function>iconv_substr</function> cuts out the portion beginning
at the position, <parameter>offset</parameter> characters
away from the end of <parameter>string</parameter>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>length</parameter></term>
<listitem>
<para>
If <parameter>length</parameter> is given and is positive, the return
value will contain at most <parameter>length</parameter> characters
of the portion that begins at <parameter>offset</parameter>
(depending on the length of <parameter>string</parameter>).
</para>
<para>
If negative <parameter>length</parameter> is passed,
<function>iconv_substr</function> cuts the portion out of
<parameter>string</parameter> from the <parameter>offset</parameter>'th
character up to the character that is
<parameter>length</parameter> characters away from the end of the string.
In case <parameter>offset</parameter> is also negative, the start position
is calculated beforehand according to the rule explained above.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>encoding</parameter></term>
<listitem>
<para>
If <parameter>encoding</parameter> parameter is omitted or &null;,
<parameter>string</parameter> are assumed to be encoded in
<link linkend="iconv.configuration">iconv.internal_encoding</link>.
</para>
<para>
Note that <parameter>offset</parameter> and <parameter>length</parameter>
parameters are always deemed to represent offsets that are
calculated on the basis of the character set determined by
<parameter>encoding</parameter>, whilst the counterpart
<function>substr</function> always takes these for byte offsets.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns the portion of <parameter>string</parameter> specified by the
<parameter>offset</parameter> and <parameter>length</parameter> parameters.
</para>
<para>
If <parameter>string</parameter> is shorter than <parameter>offset</parameter>
characters long, &false; will be returned.
If <parameter>string</parameter> is exactly <parameter>offset</parameter>
characters long, an empty string will be returned.
</para>
</refsect1>
<refsect1 role="changelog">
&reftitle.changelog;
<para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>&Version;</entry>
<entry>&Description;</entry>
</row>
</thead>
<tbody>
<row>
<entry>8.0.0</entry>
<entry>
<parameter>length</parameter> and <parameter>encoding</parameter> are nullable now.
</entry>
</row>
<row>
<entry>7.0.11</entry>
<entry>
If <parameter>string</parameter> is equal to
<parameter>offset</parameter> characters long, an empty string will be
returned. Prior to this version, &false; was returned in this case.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>substr</function></member>
<member><function>mb_substr</function></member>
<member><function>mb_strcut</function></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
-->
|
