reference/pgsql/functions/pg-convert.xml
39bb8a868935a56cfce438b0169e13c02c93211c
...
...
@@ -1,43 +1,41 @@
1
1
<?xml version="1.0" encoding="utf-8"?>
2
2
<!-- $Revision$ -->
3
3
<!-- splitted from ./en/functions/pgsql.xml, last change in rev 1.80 -->
4
-
<refentry xml:id='function.pg-convert' xmlns="http://docbook.org/ns/docbook">
4
+
<refentry xml:id="function.pg-convert" xmlns="http://docbook.org/ns/docbook">
5
5
<refnamediv>
6
6
<refname>pg_convert</refname>
7
7
<refpurpose>
8
-
Convert associative array values into suitable for SQL statement
8
+
Convert associative array values into forms suitable for SQL statements
9
9
</refpurpose>
10
10
</refnamediv>
11
11

12
12
<refsect1 role="description">
13
13
&reftitle.description;
14
14
<methodsynopsis>
15
-
<type>array</type><methodname>pg_convert</methodname>
16
-
<methodparam><type>resource</type><parameter>connection</parameter></methodparam>
15
+
<type class="union"><type>array</type><type>false</type></type><methodname>pg_convert</methodname>
16
+
<methodparam><type>PgSql\Connection</type><parameter>connection</parameter></methodparam>
17
17
<methodparam><type>string</type><parameter>table_name</parameter></methodparam>
18
-
<methodparam><type>array</type><parameter>assoc_array</parameter></methodparam>
19
-
<methodparam choice="opt"><type>int</type><parameter>options</parameter><initializer>0</initializer></methodparam>
18
+
<methodparam><type>array</type><parameter>values</parameter></methodparam>
19
+
<methodparam choice="opt"><type>int</type><parameter>flags</parameter><initializer>0</initializer></methodparam>
20
20
</methodsynopsis>
21
21
<para>
22
22
<function>pg_convert</function> checks and converts the values in
23
-
<parameter>assoc_array</parameter> into suitable values for use in an SQL
23
+
<parameter>values</parameter> into suitable values for use in an SQL
24
24
statement. Precondition for <function>pg_convert</function> is the
25
25
existence of a table <parameter>table_name</parameter> which has at least
26
-
as many columns as <parameter>assoc_array</parameter> has elements. The
26
+
as many columns as <parameter>values</parameter> has elements. The
27
27
fieldnames in <parameter>table_name</parameter> must match the indices in
28
-
<parameter>assoc_array</parameter> and the corresponding datatypes must be
28
+
<parameter>values</parameter> and the corresponding datatypes must be
29
29
compatible. Returns an array with the converted values on success, &false;
30
30
otherwise.
31
31
</para>
32
32
<note>
33
33
<para>
34
-
If there are boolean fields in <parameter>table_name</parameter> don't
35
-
use the constant &true; in <parameter>assoc_array</parameter>. It will be
36
-
converted to the string 'TRUE' which is no valid entry for boolean fields
37
-
in PostgreSQL. Use one of t, true, 1, y, yes instead.
34
+
Boolean values are accepted and converted to PostgreSQL booleans.
35
+
String representations of boolean values are also supported. &null; is
36
+
converted to PostgreSQL NULL.
38
37
</para>
39
38
</note>
40
-
&warn.experimental.func;
41
39
</refsect1>
42
40

43
41
<refsect1 role="parameters">
...
...
@@ -47,9 +45,7 @@
47
45
<varlistentry>
48
46
<term><parameter>connection</parameter></term>
49
47
<listitem>
50
-
<para>
51
-
PostgreSQL database connection resource.
52
-
</para>
48
+
&pgsql.parameter.connection;
53
49
</listitem>
54
50
</varlistentry>
55
51
<varlistentry>
...
...
@@ -61,7 +57,7 @@
61
57
</listitem>
62
58
</varlistentry>
63
59
<varlistentry>
64
-
<term><parameter>assoc_array</parameter></term>
60
+
<term><parameter>values</parameter></term>
65
61
<listitem>
66
62
<para>
67
63
Data to be converted.
...
...
@@ -69,7 +65,7 @@
69
65
</listitem>
70
66
</varlistentry>
71
67
<varlistentry>
72
-
<term><parameter>options</parameter></term>
68
+
<term><parameter>flags</parameter></term>
73
69
<listitem>
74
70
<para>
75
71
Any number of <constant>PGSQL_CONV_IGNORE_DEFAULT</constant>,
...
...
@@ -85,10 +81,43 @@
85
81
<refsect1 role="returnvalues">
86
82
&reftitle.returnvalues;
87
83
<para>
88
-
An <type>array</type> of converted values, or &false; on error.
84
+
An <type>array</type> of converted values, &return.falseforfailure;.
89
85
</para>
90
86
</refsect1>
91
87

88
+
<refsect1 role="errors">
89
+
&reftitle.errors;
90
+
<para>
91
+
A <classname>ValueError</classname> or <classname>TypeError</classname> is thrown
92
+
when the value or type of field does not match properly with a PostgreSQL's type.
93
+
</para>
94
+
</refsect1>
95
+

96
+
<refsect1 role="changelog">
97
+
&reftitle.changelog;
98
+
<informaltable>
99
+
<tgroup cols="2">
100
+
<thead>
101
+
<row>
102
+
<entry>&Version;</entry>
103
+
<entry>&Description;</entry>
104
+
</row>
105
+
</thead>
106
+
<tbody>
107
+
<row>
108
+
<entry>8.3.0</entry>
109
+
<entry>
110
+
Now throws a <classname>ValueError</classname> or <classname>TypeError</classname> error
111
+
when the value or type of field does not match properly with a PostgreSQL's type;
112
+
previously an <constant>E_WARNING</constant> was emitted.
113
+
</entry>
114
+
</row>
115
+
&pgsql.changelog.connection-object;
116
+
</tbody>
117
+
</tgroup>
118
+
</informaltable>
119
+
</refsect1>
120
+

92
121
<refsect1 role="examples">
93
122
&reftitle.examples;
94
123
<para>
...
...
@@ -118,11 +147,14 @@
118
147
<para>
119
148
<simplelist>
120
149
<member><function>pg_meta_data</function></member>
150
+
<member><function>pg_insert</function></member>
151
+
<member><function>pg_select</function></member>
152
+
<member><function>pg_update</function></member>
153
+
<member><function>pg_delete</function></member>
121
154
</simplelist>
122
155
</para>
123
156
</refsect1>
124
157
</refentry>
125
-

126
158
<!-- Keep this comment at the end of the file
127
159
Local variables:
128
160
mode: sgml
129
161



Tools (Chinese (Simplified) Manual)