reference/strings/functions/str-getcsv.xml
272838c8815f95572a60d30e39dfb1feba3e497c
...
...
@@ -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-getcsv">
3
+
<refentry xml:id="function.str-getcsv" xmlns="http://docbook.org/ns/docbook">
4
4
<refnamediv>
5
5
<refname>str_getcsv</refname>
6
6
<refpurpose>
...
...
@@ -12,15 +12,22 @@
12
12
&reftitle.description;
13
13
<methodsynopsis>
14
14
<type>array</type><methodname>str_getcsv</methodname>
15
-
<methodparam><type>string</type><parameter>input</parameter></methodparam>
16
-
<methodparam choice="opt"><type>string</type><parameter>delimiter</parameter><initializer>","</initializer></methodparam>
17
-
<methodparam choice="opt"><type>string</type><parameter>enclosure</parameter><initializer>'"'</initializer></methodparam>
15
+
<methodparam><type>string</type><parameter>string</parameter></methodparam>
16
+
<methodparam choice="opt"><type>string</type><parameter>separator</parameter><initializer>","</initializer></methodparam>
17
+
<methodparam choice="opt"><type>string</type><parameter>enclosure</parameter><initializer>"\""</initializer></methodparam>
18
18
<methodparam choice="opt"><type>string</type><parameter>escape</parameter><initializer>"\\"</initializer></methodparam>
19
19
</methodsynopsis>
20
20
<para>
21
21
Parses a string input for fields in <acronym>CSV</acronym> format
22
22
and returns an array containing the fields read.
23
23
</para>
24
+
<note>
25
+
<para>
26
+
The locale settings are taken into account by this function. If
27
+
<literal>LC_CTYPE</literal> is e.g. <literal>en_US.UTF-8</literal>, strings in
28
+
one-byte encodings may be read wrongly by this function.
29
+
</para>
30
+
</note>
24
31
</refsect1>
25
32

26
33
<refsect1 role="parameters">
...
...
@@ -28,7 +35,7 @@
28
35
<para>
29
36
<variablelist>
30
37
<varlistentry>
31
-
<term><parameter>input</parameter></term>
38
+
<term><parameter>string</parameter></term>
32
39
<listitem>
33
40
<para>
34
41
The string to parse.
...
...
@@ -36,10 +43,10 @@
36
43
</listitem>
37
44
</varlistentry>
38
45
<varlistentry>
39
-
<term><parameter>delimiter</parameter></term>
46
+
<term><parameter>separator</parameter></term>
40
47
<listitem>
41
48
<para>
42
-
Set the field delimiter (one character only).
49
+
Set the field delimiter (one single-byte character only).
43
50
</para>
44
51
</listitem>
45
52
</varlistentry>
...
...
@@ -47,7 +54,7 @@
47
54
<term><parameter>enclosure</parameter></term>
48
55
<listitem>
49
56
<para>
50
-
Set the field enclosure character (one character only).
57
+
Set the field enclosure character (one single-byte character only).
51
58
</para>
52
59
</listitem>
53
60
</varlistentry>
...
...
@@ -55,9 +62,22 @@
55
62
<term><parameter>escape</parameter></term>
56
63
<listitem>
57
64
<para>
58
-
Set the escape character (one character only). Defaults as a backslash
65
+
Set the escape character (at most one single-byte character). Defaults as a backslash
59
66
(<literal>\</literal>)
67
+
An empty string (<literal>""</literal>) disables the proprietary escape mechanism.
60
68
</para>
69
+
<note>
70
+
<simpara>
71
+
Usually an <parameter>enclosure</parameter> character is escaped inside
72
+
a field by doubling it; however, the <parameter>escape</parameter>
73
+
character can be used as an alternative. So for the default parameter
74
+
values <literal>""</literal> and <literal>\"</literal> have the same
75
+
meaning. Other than allowing to escape the
76
+
<parameter>enclosure</parameter> character the
77
+
<parameter>escape</parameter> character has no special meaning; it isn't
78
+
even meant to escape itself.
79
+
</simpara>
80
+
</note>
61
81
</listitem>
62
82
</varlistentry>
63
83
</variablelist>
...
...
@@ -71,6 +91,100 @@
71
91
</para>
72
92
</refsect1>
73
93

94
+
<refsect1 role="changelog">
95
+
&reftitle.changelog;
96
+
<para>
97
+
<informaltable>
98
+
<tgroup cols="2">
99
+
<thead>
100
+
<row>
101
+
<entry>&Version;</entry>
102
+
<entry>&Description;</entry>
103
+
</row>
104
+
</thead>
105
+
<tbody>
106
+
<row>
107
+
<entry>7.4.0</entry>
108
+
<entry>
109
+
The <parameter>escape</parameter> parameter now interprets an empty
110
+
string as signal to disable the proprietary escape mechanism. Formerly,
111
+
an empty string was treated like the default parameter value.
112
+
</entry>
113
+
</row>
114
+
</tbody>
115
+
</tgroup>
116
+
</informaltable>
117
+
</para>
118
+
</refsect1>
119
+

120
+
<refsect1 role="examples">
121
+
&reftitle.examples;
122
+
<para>
123
+
<example>
124
+
<title><function>str_getcsv</function> example</title>
125
+
<programlisting role="php">
126
+
<![CDATA[
127
+
<?php
128
+

129
+
$string = 'PHP,Java,Python,Kotlin,Swift';
130
+
$data = str_getcsv($string);
131
+

132
+
var_dump($data);
133
+
?>
134
+
]]>
135
+
</programlisting>
136
+
&example.outputs;
137
+
<screen>
138
+
<![CDATA[
139
+
array(5) {
140
+
[0]=>
141
+
string(3) "PHP"
142
+
[1]=>
143
+
string(4) "Java"
144
+
[2]=>
145
+
string(6) "Python"
146
+
[3]=>
147
+
string(6) "Kotlin"
148
+
[4]=>
149
+
string(5) "Swift"
150
+
}
151
+
]]>
152
+
</screen>
153
+
</example>
154
+
</para>
155
+
<para>
156
+
<example>
157
+
<title><function>str_getcsv</function> example with an empty string</title>
158
+
<caution>
159
+
<simpara>
160
+
On an empty string this function returns the value <code>[null]</code>
161
+
instead of an empty array.
162
+
</simpara>
163
+
</caution>
164
+
<programlisting role="php">
165
+
<![CDATA[
166
+
<?php
167
+

168
+
$string = '';
169
+
$data = str_getcsv($string);
170
+

171
+
var_dump($data);
172
+
?>
173
+
]]>
174
+
</programlisting>
175
+
&example.outputs;
176
+
<screen>
177
+
<![CDATA[
178
+
array(1) {
179
+
[0]=>
180
+
NULL
181
+
}
182
+
]]>
183
+
</screen>
184
+
</example>
185
+
</para>
186
+
</refsect1>
187
+

74
188
<refsect1 role="seealso">
75
189
&reftitle.seealso;
76
190
<para>
...
...
@@ -80,7 +194,6 @@
80
194
</para>
81
195
</refsect1>
82
196
</refentry>
83
-

84
197
<!-- Keep this comment at the end of the file
85
198
Local variables:
86
199
mode: sgml
87
200