Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Commit8a25ec8

Browse files
committed
Improve documentation about array I/O representation.
1 parent0f2fbbb commit8a25ec8

File tree

1 file changed

+58
-13
lines changed

1 file changed

+58
-13
lines changed

‎doc/src/sgml/array.sgml‎

Lines changed: 58 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/array.sgml,v 1.19 2002/01/20 22:19:55 petere Exp $ -->
1+
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/array.sgml,v 1.20 2002/03/1719:59:57 tgl Exp $ -->
22

33
<chapter id="arrays">
44
<title>Arrays</title>
@@ -22,8 +22,9 @@ CREATE TABLE sal_emp (
2222
As shown, an array data type is named by appending square brackets
2323
(<literal>[]</>) to the data type name of the array elements.
2424
The above query will create a table named
25-
<structname>sal_emp</structname> with a <type>text</type> string
26-
(<structfield>name</structfield>), a one-dimensional array of type
25+
<structname>sal_emp</structname> with columns including
26+
a <type>text</type> string (<structfield>name</structfield>),
27+
a one-dimensional array of type
2728
<type>integer</type> (<structfield>pay_by_quarter</structfield>),
2829
which represents the employee's salary by quarter, and a
2930
two-dimensional array of <type>text</type>
@@ -35,7 +36,7 @@ CREATE TABLE sal_emp (
3536
Now we do some <command>INSERT</command>s. Observe that to write an array
3637
value, we enclose the element values within curly braces and separate them
3738
by commas. If you know C, this is not unlike the syntax for
38-
initializing structures.
39+
initializing structures. (More details appear below.)
3940

4041
<programlisting>
4142
INSERT INTO sal_emp
@@ -66,7 +67,7 @@ SELECT name FROM sal_emp WHERE pay_by_quarter[1] &lt;&gt; pay_by_quarter[2];
6667
</programlisting>
6768

6869
The array subscript numbers are written within square brackets.
69-
<productname>PostgreSQL</productname> uses the
70+
By default<productname>PostgreSQL</productname> uses the
7071
<quote>one-based</quote> numbering convention for arrays, that is,
7172
an array of <replaceable>n</> elements starts with <literal>array[1]</literal> and
7273
ends with <literal>array[<replaceable>n</>]</literal>.
@@ -99,7 +100,7 @@ SELECT schedule[1:2][1:1] FROM sal_emp WHERE name = 'Bill';
99100

100101
schedule
101102
--------------------
102-
{{"meeting"},{""}}
103+
{{meeting},{""}}
103104
(1 row)
104105
</programlisting>
105106

@@ -144,11 +145,17 @@ UPDATE sal_emp SET pay_by_quarter[1:2] = '{27000,27000}'
144145
those already present, or by assigning to a slice that is adjacent
145146
to or overlaps the data already present. For example, if an array
146147
value currently has 4 elements, it will have five elements after an
147-
update that assigns to array[5]. Currently, enlargement in this
148-
fashion is only allowed for one-dimensional arrays, not
148+
update that assigns to<literal>array[5]</>. Currently, enlargement in
149+
thisfashion is only allowed for one-dimensional arrays, not
149150
multidimensional arrays.
150151
</para>
151152

153+
<para>
154+
Array slice assignment allows creation of arrays that do not use one-based
155+
subscripts. For example one might assign to <literal>array[-2:7]</> to
156+
create an array with subscript values running from -2 to 7.
157+
</para>
158+
152159
<para>
153160
The syntax for <command>CREATE TABLE</command> allows fixed-length
154161
arrays to be defined:
@@ -168,7 +175,9 @@ CREATE TABLE tictactoe (
168175
Actually, the current implementation does not enforce the declared
169176
number of dimensions either. Arrays of a particular element type are
170177
all considered to be of the same type, regardless of size or number
171-
of dimensions.
178+
of dimensions. So, declaring number of dimensions or sizes in
179+
<command>CREATE TABLE</command> is simply documentation, it does not
180+
affect runtime behavior.
172181
</para>
173182

174183
<para>
@@ -248,19 +257,55 @@ SELECT * FROM sal_emp WHERE pay_by_quarter **= 10000;
248257
</para>
249258
</note>
250259

260+
<formalpara>
261+
<title>Array input and output syntax.</title>
262+
<para>
263+
The external representation of an array value consists of items that
264+
are interpreted according to the I/O conversion rules for the array's
265+
element type, plus decoration that indicates the array structure.
266+
The decoration consists of curly braces (<literal>{</> and <literal>}</>)
267+
around the array value plus delimiter characters between adjacent items.
268+
The delimiter character is usually a comma (<literal>,</>) but can be
269+
something else: it is determined by the <literal>typdelim</> setting
270+
for the array's element type. (Among the standard datatypes provided
271+
in the <productname>PostgreSQL</productname> distribution, type
272+
<literal>box</> uses a semicolon (<literal>;</>) but all the others
273+
use comma.) In a multidimensional array, each dimension (row, plane,
274+
cube, etc.) gets its own level of curly braces, and delimiters
275+
must be written between adjacent curly-braced entities of the same level.
276+
You may write whitespace before a left brace, after a right
277+
brace, or before any individual item string. Whitespace after an item
278+
is not ignored, however: after skipping leading whitespace, everything
279+
up to the next right brace or delimiter is taken as the item value.
280+
</para>
281+
</formalpara>
282+
251283
<formalpara>
252284
<title>Quoting array elements.</title>
253285
<para>
254-
As shown above, when writing an arrayliteralvalue you may write double
286+
As shown above, when writing an array value you may write double
255287
quotes around any individual array
256288
element. You <emphasis>must</> do so if the element value would otherwise
257289
confuse the array-value parser. For example, elements containing curly
258-
braces, commas, double quotes, backslashes, or white space must be
259-
double-quoted. To put a double quote or backslash in an array element
260-
value, precede it with a backslash.
290+
braces, commas (or whatever the delimiter character is), double quotes,
291+
backslashes, or leading white space must be double-quoted. To put a double
292+
quote or backslash in an array element value, precede it with a backslash.
293+
Alternatively, you can use backslash-escaping to protect all data characters
294+
that would otherwise be taken as array syntax or ignorable white space.
261295
</para>
262296
</formalpara>
263297

298+
<para>
299+
The array output routine will put double quotes around element values
300+
if they are empty strings or contain curly braces, delimiter characters,
301+
double quotes, backslashes, or white space. Double quotes and backslashes
302+
embedded in element values will be backslash-escaped. For numeric
303+
datatypes it is safe to assume that double quotes will never appear, but
304+
for textual datatypes one should be prepared to cope with either presence
305+
or absence of quotes. (This is a change in behavior from pre-7.2
306+
<productname>PostgreSQL</productname> releases.)
307+
</para>
308+
264309
<tip>
265310
<para>
266311
Remember that what you write in an SQL query will first be interpreted

0 commit comments

Comments
 (0)
[8]ページ先頭
©2009-2025 Movatter.jp