reference/strings/functions/str-getcsv.xml
45042fef652f1b4e904e809fcbfcf31f6c60670b
45042fef652f1b4e904e809fcbfcf31f6c60670b
...
...
@@ -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" xmlns:xi="http://www.w3.org/2001/XInclude">
4
4
<refnamediv>
5
5
<refname>str_getcsv</refname>
6
6
<refpurpose>
...
...
@@ -12,22 +12,18 @@
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
+
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('function.fgetcsv')/db:refsect1[@role='description']//db:note/.)">
25
+
<xi:fallback/>
26
+
</xi:include>
31
27
</refsect1>
32
28
33
29
<refsect1 role="parameters">
...
...
@@ -35,53 +31,25 @@
35
31
<para>
36
32
<variablelist>
37
33
<varlistentry>
38
-
<term><parameter>input</parameter></term>
34
+
<term><parameter>string</parameter></term>
39
35
<listitem>
40
36
<para>
41
37
The string to parse.
42
38
</para>
43
39
</listitem>
44
40
</varlistentry>
45
-
<varlistentry>
46
-
<term><parameter>delimiter</parameter></term>
47
-
<listitem>
48
-
<para>
49
-
Set the field delimiter (one character only).
50
-
</para>
51
-
</listitem>
52
-
</varlistentry>
53
-
<varlistentry>
54
-
<term><parameter>enclosure</parameter></term>
55
-
<listitem>
56
-
<para>
57
-
Set the field enclosure character (one character only).
58
-
</para>
59
-
</listitem>
60
-
</varlistentry>
61
-
<varlistentry>
62
-
<term><parameter>escape</parameter></term>
63
-
<listitem>
64
-
<para>
65
-
Set the escape character (at most one character). Defaults as a backslash
66
-
(<literal>\</literal>)
67
-
An empty string (<literal>""</literal>) disables the proprietary escape mechanism.
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>
81
-
</listitem>
82
-
</varlistentry>
41
+
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('function.fgetcsv')/db:refsect1[@role='parameters']//db:varlistentry[db:term[db:parameter[text()='separator']]]/.)">
42
+
<xi:fallback/>
43
+
</xi:include>
44
+
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('function.fgetcsv')/db:refsect1[@role='parameters']//db:varlistentry[db:term[db:parameter[text()='enclosure']]]/.)">
45
+
<xi:fallback/>
46
+
</xi:include>
47
+
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('function.fgetcsv')/db:refsect1[@role='parameters']//db:varlistentry[db:term[db:parameter[text()='escape']]]/.)">
48
+
<xi:fallback/>
49
+
</xi:include>
83
50
</variablelist>
84
51
</para>
52
+
&warning.csv.escape-parameter;
85
53
</refsect1>
86
54
87
55
<refsect1 role="returnvalues">
...
...
@@ -91,6 +59,10 @@
91
59
</para>
92
60
</refsect1>
93
61
62
+
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('function.fgetcsv')/db:refsect1[@role='errors']/.)">
63
+
<xi:fallback/>
64
+
</xi:include>
65
+
94
66
<refsect1 role="changelog">
95
67
&reftitle.changelog;
96
68
<para>
...
...
@@ -103,6 +75,22 @@
103
75
</row>
104
76
</thead>
105
77
<tbody>
78
+
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('function.fgetcsv')/db:refsect1[@role='changelog']//db:row[db:entry[text()='8.4.0']]/.)">
79
+
<xi:fallback/>
80
+
</xi:include>
81
+
<row>
82
+
<entry>8.4.0</entry>
83
+
<entry>
84
+
Now throws a <exceptionname>ValueError</exceptionname> if
85
+
<parameter>separator</parameter>, <parameter>enclosure</parameter>,
86
+
or <parameter>escape</parameter> is invalid.
87
+
This mimics the behavior of <function>fgetcsv</function> and
88
+
<function>fputcsv</function>.
89
+
</entry>
90
+
</row>
91
+
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('function.fgetcsv')/db:refsect1[@role='changelog']//db:row[db:entry[text()='8.3.0']]/.)">
92
+
<xi:fallback/>
93
+
</xi:include>
106
94
<row>
107
95
<entry>7.4.0</entry>
108
96
<entry>
...
...
@@ -117,16 +105,86 @@
117
105
</para>
118
106
</refsect1>
119
107
120
-
<refsect1 role="seealso">
121
-
&reftitle.seealso;
108
+
<refsect1 role="examples">
109
+
&reftitle.examples;
110
+
<para>
111
+
<example>
112
+
<title><function>str_getcsv</function> example</title>
113
+
<programlisting role="php">
114
+
<![CDATA[
115
+
<?php
116
+
117
+
$string = 'PHP,Java,Python,Kotlin,Swift';
118
+
$data = str_getcsv($string, escape: '\\');
119
+
120
+
var_dump($data);
121
+
?>
122
+
]]>
123
+
</programlisting>
124
+
&example.outputs;
125
+
<screen>
126
+
<![CDATA[
127
+
array(5) {
128
+
[0]=>
129
+
string(3) "PHP"
130
+
[1]=>
131
+
string(4) "Java"
132
+
[2]=>
133
+
string(6) "Python"
134
+
[3]=>
135
+
string(6) "Kotlin"
136
+
[4]=>
137
+
string(5) "Swift"
138
+
}
139
+
]]>
140
+
</screen>
141
+
</example>
142
+
</para>
122
143
<para>
123
-
<simplelist>
124
-
<member><function>fgetcsv</function></member>
125
-
</simplelist>
144
+
<example>
145
+
<title><function>str_getcsv</function> example with an empty string</title>
146
+
<caution>
147
+
<simpara>
148
+
On an empty string this function returns the value <code>[null]</code>
149
+
instead of an empty array.
150
+
</simpara>
151
+
</caution>
152
+
<programlisting role="php">
153
+
<![CDATA[
154
+
<?php
155
+
156
+
$string = '';
157
+
$data = str_getcsv($string, escape: '\\');
158
+
159
+
var_dump($data);
160
+
?>
161
+
]]>
162
+
</programlisting>
163
+
&example.outputs;
164
+
<screen>
165
+
<![CDATA[
166
+
array(1) {
167
+
[0]=>
168
+
NULL
169
+
}
170
+
]]>
171
+
</screen>
172
+
</example>
126
173
</para>
127
174
</refsect1>
128
-
</refentry>
129
175
176
+
<refsect1 role="seealso">
177
+
&reftitle.seealso;
178
+
<simplelist>
179
+
<member><function>fputcsv</function></member>
180
+
<member><function>fgetcsv</function></member>
181
+
<member><methodname>SplFileObject::fgetcsv</methodname></member>
182
+
<member><methodname>SplFileObject::fputcsv</methodname></member>
183
+
<member><methodname>SplFileObject::setCsvControl</methodname></member>
184
+
<member><methodname>SplFileObject::getCsvControl</methodname></member>
185
+
</simplelist>
186
+
</refsect1>
187
+
</refentry>
130
188
<!-- Keep this comment at the end of the file
131
189
Local variables:
132
190
mode: sgml
133
191