From 6889537c484189da95b6a43741b677fe7ceec225 Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Sat, 8 Jan 2005 05:19:18 +0000 Subject: [PATCH] Some small docs improvements motivated by reading the comments for the 7.4 7.4 interactive docs. --- doc/src/sgml/datatype.sgml | 88 ++- doc/src/sgml/func.sgml | 1506 ++++++++++++++++++------------------ 2 files changed, 814 insertions(+), 780 deletions(-) diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml index 759177ad38..f515108d50 100644 --- a/doc/src/sgml/datatype.sgml +++ b/doc/src/sgml/datatype.sgml @@ -1,5 +1,5 @@ @@ -446,9 +446,9 @@ $PostgreSQL: pgsql/doc/src/sgml/datatype.sgml,v 1.152 2004/12/23 05:37:39 tgl Ex The type numeric can store numbers with up to 1000 digits of precision and perform calculations exactly. It is especially recommended for storing monetary amounts and other - quantities where exactness is required. However, the - numeric type is very slow compared to the - floating-point types described in the next section. + quantities where exactness is required. However, arithmetic on + numeric values is very slow compared to the integer + types, or to the floating-point types described in the next section. @@ -464,7 +464,8 @@ $PostgreSQL: pgsql/doc/src/sgml/datatype.sgml,v 1.152 2004/12/23 05:37:39 tgl Ex - Both the precision and the scale of the numeric type can be + Both the maximum precision and the maximum scale of a + numeric column can be configured. To declare a column of type numeric use the syntax @@ -492,10 +493,19 @@ NUMERIC - If the precision or scale of a value is greater than the declared - precision or scale of a column, the system will attempt to round - the value. If the value cannot be rounded so as to satisfy the - declared limits, an error is raised. + If the scale of a value to be stored is greater than the declared + scale of the column, the system will round the value to the specified + number of fractional digits. Then, if the number of digits to the + left of the decimal point exceeds the declared precision minus the + declared scale, an error is raised. + + + + Numeric values are physically stored without any extra leading or + trailing zeroes. Thus, the declared precision and scale of a column + are maximums, not fixed allocations. (In this sense the numeric + type is more akin to varchar(n) + than to char(n).) @@ -1089,13 +1099,18 @@ SELECT b, char_length(b) FROM test2; A binary string is a sequence of octets (or bytes). Binary - strings are distinguished from characters strings by two + strings are distinguished from character strings by two characteristics: First, binary strings specifically allow storing octets of value zero and other non-printable - octets (defined as octets outside the range 32 to 126). + octets (usually, octets outside the range 32 to 126). + Character strings disallow zero octets, and also disallow any + other octet values and sequences of octet values that are invalid + according to the database's selected character set encoding. Second, operations on binary strings process the actual bytes, - whereas the encoding and processing of character strings depends - on locale settings. + whereas the processing of character strings depends on locale settings. + In short, binary strings are appropriate for storing data that the + programmer thinks of as raw bytes, whereas character + strings are appropriate for storing text. @@ -1254,7 +1269,7 @@ SELECT b, char_length(b) FROM test2; The SQL standard defines a different binary string type, called BLOB or BINARY LARGE - OBJECT. The input format is different compared to + OBJECT. The input format is different from bytea, but the provided functions and operators are mostly the same. @@ -1295,7 +1310,9 @@ SELECT b, char_length(b) FROM test2; PostgreSQL supports the full set of SQL date and time types, shown in . + linkend="datatype-datetime-table">. The operations available + on these data types are described in + . @@ -1842,8 +1859,10 @@ January 8 04:05:06 1999 PST are specially represented inside the system and will be displayed the same way; but the others are simply notational shorthands that will be converted to ordinary date/time values when read. - All of these values are treated as normal constants and need to be - written in single quotes. + (In particular, now and related strings are converted + to a specific time value as soon as they are read.) + All of these values need to be written in single quotes when used + as constants in SQL commands.
@@ -1908,7 +1927,7 @@ January 8 04:05:06 1999 PST CURRENT_DATE, CURRENT_TIME, CURRENT_TIMESTAMP, LOCALTIME, LOCALTIMESTAMP. The latter four accept an - optional precision specification. (See also .) Note however that these are SQL functions and are not recognized as data input strings. @@ -2265,7 +2284,7 @@ SELECT * FROM test1 WHERE a; not work). This can be accomplished using the CASE expression: CASE WHEN boolval THEN 'value if true' ELSE - 'value if false' END. See also . See . @@ -2454,9 +2473,9 @@ SELECT * FROM test1 WHERE a; Paths are represented by lists of connected points. Paths can be open, where - the first and last points in the list are not connected, or + the first and last points in the list are not considered connected, or closed, - where the first and last points are connected. + where the first and last points are considered connected. @@ -2558,7 +2577,7 @@ SELECT * FROM test1 WHERE a; is preferable to use these types instead of plain text types to store network addresses, because these types offer input error checking and several specialized - operators and functions. + operators and functions (see ).
@@ -3006,12 +3025,25 @@ SELECT * FROM test; for specialized input and output routines. These routines are able to accept and display symbolic names for system objects, rather than the raw numeric value that type oid would use. The alias - types allow simplified lookup of OID values for objects: for example, - one may write 'mytable'::regclass to get the OID of table - mytable, rather than SELECT oid FROM pg_class WHERE - relname = 'mytable'. (In reality, a much more complicated SELECT would - be needed to deal with selecting the right OID when there are multiple - tables named mytable in different schemas.) + types allow simplified lookup of OID values for objects. For example, + to examine the pg_attribute rows related to a table + mytable, one could write + +SELECT * FROM pg_attribute WHERE attrelid = 'mytable'::regclass; + + rather than + +SELECT * FROM pg_attribute + WHERE attrelid = (SELECT oid FROM pg_class WHERE relname = 'mytable'); + + While that doesn't look all that bad by itself, it's still oversimplified. + A far more complicated sub-select would be needed to + select the right OID if there are multiple tables named + mytable in different schemas. + The regclass input converter handles the table lookup according + to the schema path setting, and so it does the right thing + automatically. Similarly, casting a table's OID to + regclass is handy for symbolic display of a numeric OID.
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index 96fc4ea698..759c67df31 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -1,5 +1,5 @@ @@ -1227,10 +1227,10 @@ PostgreSQL documentation text Return the given string suitably quoted to be used as an identifier - in an SQL statement string. - Quotes are added only if necessary (i.e., if the string contains - non-identifier characters or would be case-folded). - Embedded quotes are properly doubled. + in an SQL statement string. + Quotes are added only if necessary (i.e., if the string contains + non-identifier characters or would be case-folded). + Embedded quotes are properly doubled. quote_ident('Foo bar')"Foo bar" @@ -1241,8 +1241,8 @@ PostgreSQL documentation text Return the given string suitably quoted to be used as a string literal - in an SQL statement string. - Embedded quotes and backslashes are properly doubled. + in an SQL statement string. + Embedded quotes and backslashes are properly doubled. quote_literal( 'O\'Reilly')'O''Reilly' @@ -2302,12 +2302,12 @@ PostgreSQL documentation Length of binary string binary string - length + length length - of a binary string - binary strings, length + of a binary string + binary strings, length length('jo\\000se'::bytea) @@ -3999,61 +3999,61 @@ substring('foobar' from 'o(.)b') o - Function - Return Type - Description - Example + Function + Return Type + Description + Example - to_char(timestamp, text) - text - convert time stamp to string - to_char(current_timestamp, 'HH12:MI:SS') + to_char(timestamp, text) + text + convert time stamp to string + to_char(current_timestamp, 'HH12:MI:SS') - to_char(interval, text) - text - convert interval to string - to_char(interval '15h 2m 12s', 'HH24:MI:SS') + to_char(interval, text) + text + convert interval to string + to_char(interval '15h 2m 12s', 'HH24:MI:SS') - to_char(int, text) - text - convert integer to string - to_char(125, '999') + to_char(int, text) + text + convert integer to string + to_char(125, '999') - to_char(double precision, + to_char(double precision, text) - text - convert real/double precision to string - to_char(125.8::real, '999D9') + text + convert real/double precision to string + to_char(125.8::real, '999D9') - to_char(numeric, text) - text - convert numeric to string - to_char(-125.8, '999D99S') + to_char(numeric, text) + text + convert numeric to string + to_char(-125.8, '999D99S') - to_date(text, text) - date - convert string to date - to_date('05 Dec 2000', 'DD Mon YYYY') + to_date(text, text) + date + convert string to date + to_date('05 Dec 2000', 'DD Mon YYYY') - to_timestamp(text, text) - timestamp with time zone - convert string to time stamp - to_timestamp('05 Dec 2000', 'DD Mon YYYY') + to_timestamp(text, text) + timestamp with time zone + convert string to time stamp + to_timestamp('05 Dec 2000', 'DD Mon YYYY') - to_number(text, text) - numeric - convert string to numeric - to_number('12,454.8-', '99G999D9S') + to_number(text, text) + numeric + convert string to numeric + to_number('12,454.8-', '99G999D9S') @@ -4083,202 +4083,202 @@ substring('foobar' from 'o(.)b') o - Pattern - Description + Pattern + Description - HH - hour of day (01-12) + HH + hour of day (01-12) - HH12 - hour of day (01-12) + HH12 + hour of day (01-12) - HH24 - hour of day (00-23) + HH24 + hour of day (00-23) - MI - minute (00-59) + MI + minute (00-59) - SS - second (00-59) + SS + second (00-59) - MS - millisecond (000-999) + MS + millisecond (000-999) - US - microsecond (000000-999999) + US + microsecond (000000-999999) - SSSS - seconds past midnight (0-86399) + SSSS + seconds past midnight (0-86399) - AM or A.M. or - PM or P.M. - meridian indicator (uppercase) + AM or A.M. or + PM or P.M. + meridian indicator (uppercase) - am or a.m. or - pm or p.m. - meridian indicator (lowercase) + am or a.m. or + pm or p.m. + meridian indicator (lowercase) - Y,YYY - year (4 and more digits) with comma + Y,YYY + year (4 and more digits) with comma - YYYY - year (4 and more digits) + YYYY + year (4 and more digits) - YYY - last 3 digits of year + YYY + last 3 digits of year - YY - last 2 digits of year + YY + last 2 digits of year - Y - last digit of year + Y + last digit of year - IYYY - ISO year (4 and more digits) + IYYY + ISO year (4 and more digits) - IYY - last 3 digits of ISO year + IYY + last 3 digits of ISO year - IY - last 2 digits of ISO year + IY + last 2 digits of ISO year - I - last digits of ISO year + I + last digits of ISO year - BC or B.C. or - AD or A.D. - era indicator (uppercase) + BC or B.C. or + AD or A.D. + era indicator (uppercase) - bc or b.c. or - ad or a.d. - era indicator (lowercase) + bc or b.c. or + ad or a.d. + era indicator (lowercase) - MONTH - full uppercase month name (blank-padded to 9 chars) + MONTH + full uppercase month name (blank-padded to 9 chars) - Month - full mixed-case month name (blank-padded to 9 chars) + Month + full mixed-case month name (blank-padded to 9 chars) - month - full lowercase month name (blank-padded to 9 chars) + month + full lowercase month name (blank-padded to 9 chars) - MON - abbreviated uppercase month name (3 chars) + MON + abbreviated uppercase month name (3 chars) - Mon - abbreviated mixed-case month name (3 chars) + Mon + abbreviated mixed-case month name (3 chars) - mon - abbreviated lowercase month name (3 chars) + mon + abbreviated lowercase month name (3 chars) - MM - month number (01-12) + MM + month number (01-12) - DAY - full uppercase day name (blank-padded to 9 chars) + DAY + full uppercase day name (blank-padded to 9 chars) - Day - full mixed-case day name (blank-padded to 9 chars) + Day + full mixed-case day name (blank-padded to 9 chars) - day - full lowercase day name (blank-padded to 9 chars) + day + full lowercase day name (blank-padded to 9 chars) - DY - abbreviated uppercase day name (3 chars) + DY + abbreviated uppercase day name (3 chars) - Dy - abbreviated mixed-case day name (3 chars) + Dy + abbreviated mixed-case day name (3 chars) - dy - abbreviated lowercase day name (3 chars) + dy + abbreviated lowercase day name (3 chars) - DDD - day of year (001-366) + DDD + day of year (001-366) - DD - day of month (01-31) + DD + day of month (01-31) - D - day of week (1-7; Sunday is 1) + D + day of week (1-7; Sunday is 1) - W - week of month (1-5) (The first week starts on the first day of the month.) + W + week of month (1-5) (The first week starts on the first day of the month.) - WW - week number of year (1-53) (The first week starts on the first day of the year.) + WW + week number of year (1-53) (The first week starts on the first day of the year.) - IW - ISO week number of year (The first Thursday of the new year is in week 1.) + IW + ISO week number of year (The first Thursday of the new year is in week 1.) - CC - century (2 digits) + CC + century (2 digits) - J - Julian Day (days since January 1, 4712 BC) + J + Julian Day (days since January 1, 4712 BC) - Q - quarter + Q + quarter - RM - month in Roman numerals (I-XII; I=January) (uppercase) + RM + month in Roman numerals (I-XII; I=January) (uppercase) - rm - month in Roman numerals (i-xii; i=January) (lowercase) + rm + month in Roman numerals (i-xii; i=January) (lowercase) - TZ - time-zone name (uppercase) + TZ + time-zone name (uppercase) - tz - time-zone name (lowercase) + tz + time-zone name (lowercase) @@ -4298,36 +4298,36 @@ substring('foobar' from 'o(.)b') o - Modifier - Description - Example + Modifier + Description + Example - FM prefix - fill mode (suppress padding blanks and zeroes) - FMMonth + FM prefix + fill mode (suppress padding blanks and zeroes) + FMMonth - TH suffix - uppercase ordinal number suffix - DDTH - + TH suffix + uppercase ordinal number suffix + DDTH + - th suffix - lowercase ordinal number suffix - DDth + th suffix + lowercase ordinal number suffix + DDth - FX prefix - fixed format global option (see usage notes) - FX Month DD Day - + FX prefix + fixed format global option (see usage notes) + FX Month DD Day + - SP suffix - spell mode (not yet implemented) - DDSP + SP suffix + spell mode (not yet implemented) + DDSP @@ -4436,74 +4436,74 @@ substring('foobar' from 'o(.)b') o - Pattern - Description + Pattern + Description - 9 - value with the specified number of digits + 9 + value with the specified number of digits - 0 - value with leading zeros + 0 + value with leading zeros - . (period) - decimal point + . (period) + decimal point - , (comma) - group (thousand) separator + , (comma) + group (thousand) separator - PR - negative value in angle brackets + PR + negative value in angle brackets - S - sign anchored to number (uses locale) + S + sign anchored to number (uses locale) - L - currency symbol (uses locale) + L + currency symbol (uses locale) - D - decimal point (uses locale) + D + decimal point (uses locale) - G - group separator (uses locale) + G + group separator (uses locale) - MI - minus sign in specified position (if number < 0) + MI + minus sign in specified position (if number < 0) - PL - plus sign in specified position (if number > 0) + PL + plus sign in specified position (if number > 0) - SG - plus/minus sign in specified position + SG + plus/minus sign in specified position - RN - roman numeral (input between 1 and 3999) + RN + roman numeral (input between 1 and 3999) - TH or th - ordinal number suffix + TH or th + ordinal number suffix - V - shift specified number of digits (see notes) + V + shift specified number of digits (see notes) - EEEE - scientific notation (not implemented yet) + EEEE + scientific notation (not implemented yet) @@ -4575,8 +4575,8 @@ substring('foobar' from 'o(.)b') o - Expression - Result + Expression + Result @@ -4642,7 +4642,7 @@ substring('foobar' from 'o(.)b') o to_char(148.5, '999D999') - ' 148,500' + ' 148,500' to_char(3148.5, '9G999D999') @@ -4652,57 +4652,57 @@ substring('foobar' from 'o(.)b') o to_char(-485, '999S') '485-' - + to_char(-485, '999MI') - '485-' + '485-' to_char(485, '999MI') - '485 ' + '485 ' to_char(485, 'FM999MI') - '485' + '485' to_char(485, 'PL999') - '+485' + '+485' - + to_char(485, 'SG999') - '+485' + '+485' to_char(-485, 'SG999') - '-485' + '-485' to_char(-485, '9SG99') - '4-85' + '4-85' to_char(-485, '999PR') - '<485>' + '<485>' to_char(485, 'L999') - 'DM 485 + 'DM 485 - to_char(485, 'RN') + to_char(485, 'RN') '        CDLXXXV' - to_char(485, 'FMRN') + to_char(485, 'FMRN') 'CDLXXXV' to_char(5.2, 'FMRN') - 'V' + 'V' to_char(482, '999th') - ' 482nd' + ' 482nd' to_char(485, '"Good number:"999') @@ -4713,14 +4713,14 @@ substring('foobar' from 'o(.)b') o 'Pre: 485 Post: .800' - to_char(12, '99V999') + to_char(12, '99V999') ' 12000' to_char(12.4, '99V999') ' 12400' - + to_char(12.45, '99V9') ' 125' @@ -4879,39 +4879,39 @@ substring('foobar' from 'o(.)b') o - Function - Return Type - Description - Example - Result + Function + Return Type + Description + Example + Result - age(timestamp, timestamp) - interval - Subtract arguments, producing a symbolic result that - uses years and months - age(timestamp '2001-04-10', timestamp '1957-06-13') - 43 years 9 mons 27 days + age(timestamp, timestamp) + interval + Subtract arguments, producing a symbolic result that + uses years and months + age(timestamp '2001-04-10', timestamp '1957-06-13') + 43 years 9 mons 27 days - age(timestamp) - interval - Subtract from current_date - age(timestamp '1957-06-13') - 43 years 8 mons 3 days + age(timestamp) + interval + Subtract from current_date + age(timestamp '1957-06-13') + 43 years 8 mons 3 days - current_date - date - Today's date; see - - - + current_date + date + Today's date; see + + + @@ -4924,78 +4924,78 @@ substring('foobar' from 'o(.)b') o - current_timestamp - timestamp with time zone - Date and time; see - - - + current_timestamp + timestamp with time zone + Date and time; see + + + - date_part(text, timestamp) - double precision - Get subfield (equivalent to - extract); see + date_part(text, timestamp) + double precision + Get subfield (equivalent to + extract); see - date_part('hour', timestamp '2001-02-16 20:38:40') - 20 + date_part('hour', timestamp '2001-02-16 20:38:40') + 20 - date_part(text, interval) - double precision - Get subfield (equivalent to - extract); see + date_part(text, interval) + double precision + Get subfield (equivalent to + extract); see - date_part('month', interval '2 years 3 months') - 3 + date_part('month', interval '2 years 3 months') + 3 - date_trunc(text, timestamp) - timestamp - Truncate to specified precision; see also date_trunc(text, timestamp) + timestamp + Truncate to specified precision; see also - date_trunc('hour', timestamp '2001-02-16 20:38:40') - 2001-02-16 20:00:00 + date_trunc('hour', timestamp '2001-02-16 20:38:40') + 2001-02-16 20:00:00 - extract(field from + extract(field from timestamp) - double precision - Get subfield; see + double precision + Get subfield; see - extract(hour from timestamp '2001-02-16 20:38:40') - 20 + extract(hour from timestamp '2001-02-16 20:38:40') + 20 - extract(field from + extract(field from interval) - double precision - Get subfield; see + double precision + Get subfield; see - extract(month from interval '2 years 3 months') - 3 + extract(month from interval '2 years 3 months') + 3 - isfinite(timestamp) - boolean - Test for finite time stamp (not equal to infinity) - isfinite(timestamp '2001-02-16 21:28:30') - true + isfinite(timestamp) + boolean + Test for finite time stamp (not equal to infinity) + isfinite(timestamp '2001-02-16 21:28:30') + true - isfinite(interval) - boolean - Test for finite interval - isfinite(interval '4 hours') - true + isfinite(interval) + boolean + Test for finite interval + isfinite(interval '4 hours') + true @@ -5017,24 +5017,24 @@ substring('foobar' from 'o(.)b') o - now() - timestamp with time zone - Current date and time (equivalent to - current_timestamp); see now() + timestamp with time zone + Current date and time (equivalent to + current_timestamp); see - - - + + + - timeofday() - text - Current date and time; see timeofday() + text + Current date and time; see - - - + + + @@ -5185,7 +5185,7 @@ SELECT EXTRACT(DOY FROM TIMESTAMP '2001-02-16 20:38:40'); For date and timestamp values, the number of seconds since 1970-01-01 00:00:00-00 (can be negative); - for interval values, the total number + for interval values, the total number of seconds in the interval @@ -5203,7 +5203,7 @@ SELECT EXTRACT(EPOCH FROM INTERVAL '5 days 3 hours'); -SELECT TIMESTAMP WITH TIME ZONE 'epoch' + 982384720 * interval '1 second'; +SELECT TIMESTAMP WITH TIME ZONE 'epoch' + 982384720 * INTERVAL '1 second'; @@ -5351,8 +5351,8 @@ SELECT EXTRACT(SECOND FROM TIME '17:12:28.5'); The time zone offset from UTC, measured in seconds. Positive values - correspond to time zones east of UTC, negative values to - zones west of UTC. + correspond to time zones east of UTC, negative values to + zones west of UTC. @@ -5515,35 +5515,35 @@ SELECT date_trunc('year', TIMESTAMP '2001-02-16 20:38:40'); - Expression - Return Type - Description + Expression + Return Type + Description - - timestamp without time zone AT TIME ZONE zone - - timestamp with time zone - Convert local time in given time zone to UTC + + timestamp without time zone AT TIME ZONE zone + + timestamp with time zone + Convert local time in given time zone to UTC - - timestamp with time zone AT TIME ZONE zone - - timestamp without time zone - Convert UTC to local time in given time zone + + timestamp with time zone AT TIME ZONE zone + + timestamp without time zone + Convert UTC to local time in given time zone - - time with time zone AT TIME ZONE zone - - time with time zone - Convert local time across time zones + + time with time zone AT TIME ZONE zone + + time with time zone + Convert local time across time zones @@ -5737,146 +5737,146 @@ SELECT TIMESTAMP 'now'; - Operator - Description - Example + Operator + Description + Example - + - Translation - box '((0,0),(1,1))' + point '(2.0,0)' + + + Translation + box '((0,0),(1,1))' + point '(2.0,0)' - - - Translation - box '((0,0),(1,1))' - point '(2.0,0)' + - + Translation + box '((0,0),(1,1))' - point '(2.0,0)' - * - Scaling/rotation - box '((0,0),(1,1))' * point '(2.0,0)' + * + Scaling/rotation + box '((0,0),(1,1))' * point '(2.0,0)' - / - Scaling/rotation - box '((0,0),(2,2))' / point '(2.0,0)' + / + Scaling/rotation + box '((0,0),(2,2))' / point '(2.0,0)' - # - Point or box of intersection - '((1,-1),(-1,1))' # '((1,1),(-1,-1))' + # + Point or box of intersection + '((1,-1),(-1,1))' # '((1,1),(-1,-1))' - # - Number of points in path or polygon - # '((1,0),(0,1),(-1,0))' + # + Number of points in path or polygon + # '((1,0),(0,1),(-1,0))' - @-@ - Length or circumference - @-@ path '((0,0),(1,0))' + @-@ + Length or circumference + @-@ path '((0,0),(1,0))' - @@ - Center - @@ circle '((0,0),10)' + @@ + Center + @@ circle '((0,0),10)' - ## - Closest point to first operand on second operand - point '(0,0)' ## lseg '((2,0),(0,2))' + ## + Closest point to first operand on second operand + point '(0,0)' ## lseg '((2,0),(0,2))' - <-> - Distance between - circle '((0,0),1)' <-> circle '((5,0),1)' + <-> + Distance between + circle '((0,0),1)' <-> circle '((5,0),1)' - && - Overlaps? - box '((0,0),(1,1))' && box '((0,0),(2,2))' + && + Overlaps? + box '((0,0),(1,1))' && box '((0,0),(2,2))' - &< - Does not extend to the right of? - box '((0,0),(1,1))' &< box '((0,0),(2,2))' + &< + Does not extend to the right of? + box '((0,0),(1,1))' &< box '((0,0),(2,2))' - &> - Does not extend to the left of? - box '((0,0),(3,3))' &> box '((0,0),(2,2))' + &> + Does not extend to the left of? + box '((0,0),(3,3))' &> box '((0,0),(2,2))' - << - Is left of? - circle '((0,0),1)' << circle '((5,0),1)' + << + Is left of? + circle '((0,0),1)' << circle '((5,0),1)' - >> - Is right of? - circle '((5,0),1)' >> circle '((0,0),1)' + >> + Is right of? + circle '((5,0),1)' >> circle '((0,0),1)' - <^ - Is below? - circle '((0,0),1)' <^ circle '((0,5),1)' + <^ + Is below? + circle '((0,0),1)' <^ circle '((0,5),1)' - >^ - Is above? - circle '((0,5),1)' >^ circle '((0,0),1)' + >^ + Is above? + circle '((0,5),1)' >^ circle '((0,0),1)' - ?# - Intersects? - lseg '((-1,0),(1,0))' ?# box '((-2,-2),(2,2))' + ?# + Intersects? + lseg '((-1,0),(1,0))' ?# box '((-2,-2),(2,2))' - ?- - Is horizontal? - ?- lseg '((-1,0),(1,0))' + ?- + Is horizontal? + ?- lseg '((-1,0),(1,0))' - ?- - Are horizontally aligned? - point '(1,0)' ?- point '(0,0)' + ?- + Are horizontally aligned? + point '(1,0)' ?- point '(0,0)' - ?| - Is vertical? - ?| lseg '((-1,0),(1,0))' + ?| + Is vertical? + ?| lseg '((-1,0),(1,0))' - ?| - Are vertically aligned? - point '(0,1)' ?| point '(0,0)' + ?| + Are vertically aligned? + point '(0,1)' ?| point '(0,0)' - ?-| - Is perpendicular? - lseg '((0,0),(0,1))' ?-| lseg '((0,0),(1,0))' + ?-| + Is perpendicular? + lseg '((0,0),(0,1))' ?-| lseg '((0,0),(1,0))' - ?|| - Are parallel? - lseg '((-1,0),(1,0))' ?|| lseg '((-1,2),(1,2))' + ?|| + Are parallel? + lseg '((-1,0),(1,0))' ?|| lseg '((-1,2),(1,2))' - ~ - Contains? - circle '((0,0),2)' ~ point '(1,1)' + ~ + Contains? + circle '((0,0),2)' ~ point '(1,1)' - @ - Contained in or on? - point '(1,1)' @ circle '((0,0),2)' + @ + Contained in or on? + point '(1,1)' @ circle '((0,0),2)' - ~= - Same as? - polygon '((0,0),(1,1))' ~= polygon '((1,1),(0,0))' + ~= + Same as? + polygon '((0,0),(1,1))' ~= polygon '((1,1),(0,0))' @@ -5888,105 +5888,105 @@ SELECT TIMESTAMP 'now'; - Function - Return Type - Description - Example + Function + Return Type + Description + Example - area(object) - double precision - area - area(box '((0,0),(1,1))') + area(object) + double precision + area + area(box '((0,0),(1,1))') - box_intersect(box, box) - box - intersection box - box_intersect(box '((0,0),(1,1))',box '((0.5,0.5),(2,2))') + box_intersect(box, box) + box + intersection box + box_intersect(box '((0,0),(1,1))',box '((0.5,0.5),(2,2))') - center(object) - point - center - center(box '((0,0),(1,2))') + center(object) + point + center + center(box '((0,0),(1,2))') - diameter(circle) - double precision - diameter of circle - diameter(circle '((0,0),2.0)') + diameter(circle) + double precision + diameter of circle + diameter(circle '((0,0),2.0)') - height(box) - double precision - vertical size of box - height(box '((0,0),(1,1))') + height(box) + double precision + vertical size of box + height(box '((0,0),(1,1))') - isclosed(path) - boolean - a closed path? - isclosed(path '((0,0),(1,1),(2,0))') + isclosed(path) + boolean + a closed path? + isclosed(path '((0,0),(1,1),(2,0))') - isopen(path) - boolean - an open path? - isopen(path '[(0,0),(1,1),(2,0)]') + isopen(path) + boolean + an open path? + isopen(path '[(0,0),(1,1),(2,0)]') - length(object) - double precision - length - length(path '((-1,0),(1,0))') + length(object) + double precision + length + length(path '((-1,0),(1,0))') - npoints(path) - integer - number of points - npoints(path '[(0,0),(1,1),(2,0)]') + npoints(path) + integer + number of points + npoints(path '[(0,0),(1,1),(2,0)]') - npoints(polygon) - integer - number of points - npoints(polygon '((1,1),(0,0))') + npoints(polygon) + integer + number of points + npoints(polygon '((1,1),(0,0))') - pclose(path) - path - convert path to closed - pclose(path '[(0,0),(1,1),(2,0)]') + pclose(path) + path + convert path to closed + pclose(path '[(0,0),(1,1),(2,0)]') - point(lseg, lseg) - point - intersection - point(lseg '((-1,0),(1,0))',lseg '((-2,-2),(2,2))') + point(lseg, lseg) + point + intersection + point(lseg '((-1,0),(1,0))',lseg '((-2,-2),(2,2))') ]]> - popen(path) - path - convert path to open - popen(path '((0,0),(1,1),(2,0))') + popen(path) + path + convert path to open + popen(path '((0,0),(1,1),(2,0))') - radius(circle) - double precision - radius of circle - radius(circle '((0,0),2.0)') + radius(circle) + double precision + radius of circle + radius(circle '((0,0),2.0)') - width(box) - double precision - horizontal size of box - width(box '((0,0),(1,1))') + width(box) + double precision + horizontal size of box + width(box '((0,0),(1,1))') @@ -5998,102 +5998,102 @@ SELECT TIMESTAMP 'now'; - Function - Return Type - Description - Example + Function + Return Type + Description + Example - box(circle) - box - circle to box - box(circle '((0,0),2.0)') + box(circle) + box + circle to box + box(circle '((0,0),2.0)') - box(point, point) - box - points to box - box(point '(0,0)', point '(1,1)') + box(point, point) + box + points to box + box(point '(0,0)', point '(1,1)') - box(polygon) - box - polygon to box - box(polygon '((0,0),(1,1),(2,0))') + box(polygon) + box + polygon to box + box(polygon '((0,0),(1,1),(2,0))') - circle(box) - circle - box to circle - circle(box '((0,0),(1,1))') + circle(box) + circle + box to circle + circle(box '((0,0),(1,1))') - circle(point, double precision) - circle - point and radius to circle - circle(point '(0,0)', 2.0) + circle(point, double precision) + circle + point and radius to circle + circle(point '(0,0)', 2.0) - lseg(box) - lseg - box diagonal to line segment - lseg(box '((-1,0),(1,0))') + lseg(box) + lseg + box diagonal to line segment + lseg(box '((-1,0),(1,0))') - lseg(point, point) - lseg - points to line segment - lseg(point '(-1,0)', point '(1,0)') + lseg(point, point) + lseg + points to line segment + lseg(point '(-1,0)', point '(1,0)') - path(polygon) - point - polygon to path - path(polygon '((0,0),(1,1),(2,0))') + path(polygon) + point + polygon to path + path(polygon '((0,0),(1,1),(2,0))') - point(circle) - point - center of circle - point(circle '((0,0),2.0)') + point(circle) + point + center of circle + point(circle '((0,0),2.0)') - point(lseg, lseg) - point - intersection - point(lseg '((-1,0),(1,0))', lseg '((-2,-2),(2,2))') + point(lseg, lseg) + point + intersection + point(lseg '((-1,0),(1,0))', lseg '((-2,-2),(2,2))') - point(polygon) - point - center of polygon - point(polygon '((0,0),(1,1),(2,0))') + point(polygon) + point + center of polygon + point(polygon '((0,0),(1,1),(2,0))') - polygon(box) - polygon - box to 4-point polygon - polygon(box '((0,0),(1,1))') + polygon(box) + polygon + box to 4-point polygon + polygon(box '((0,0),(1,1))') - polygon(circle) - polygon - circle to 12-point polygon - polygon(circle '((0,0),2.0)') + polygon(circle) + polygon + circle to 12-point polygon + polygon(circle '((0,0),2.0)') - polygon(npts, circle) - polygon - circle to npts-point polygon - polygon(12, circle '((0,0),2.0)') + polygon(npts, circle) + polygon + circle to npts-point polygon + polygon(12, circle '((0,0),2.0)') - polygon(path) - polygon - path to polygon - polygon(path '((0,0),(1,1),(2,0))') + polygon(path) + polygon + path to polygon + polygon(path '((0,0),(1,1),(2,0))') @@ -6129,7 +6129,7 @@ SELECT TIMESTAMP 'now'; - Network Address Type Functions + Network Address Functions and Operators shows the operators @@ -6147,61 +6147,61 @@ SELECT TIMESTAMP 'now'; - Operator - Description - Example + Operator + Description + Example - < - is less than - inet '192.168.1.5' < inet '192.168.1.6' + < + is less than + inet '192.168.1.5' < inet '192.168.1.6' - <= - is less than or equal - inet '192.168.1.5' <= inet '192.168.1.5' + <= + is less than or equal + inet '192.168.1.5' <= inet '192.168.1.5' - = - equals - inet '192.168.1.5' = inet '192.168.1.5' + = + equals + inet '192.168.1.5' = inet '192.168.1.5' - >= - is greater or equal - inet '192.168.1.5' >= inet '192.168.1.5' + >= + is greater or equal + inet '192.168.1.5' >= inet '192.168.1.5' - > - is greater than - inet '192.168.1.5' > inet '192.168.1.4' + > + is greater than + inet '192.168.1.5' > inet '192.168.1.4' - <> - is not equal - inet '192.168.1.5' <> inet '192.168.1.4' + <> + is not equal + inet '192.168.1.5' <> inet '192.168.1.4' - << - is contained within - inet '192.168.1.5' << inet '192.168.1/24' + << + is contained within + inet '192.168.1.5' << inet '192.168.1/24' - <<= - is contained within or equals - inet '192.168.1/24' <<= inet '192.168.1/24' + <<= + is contained within or equals + inet '192.168.1/24' <<= inet '192.168.1/24' - >> - contains - inet '192.168.1/24' >> inet '192.168.1.5' + >> + contains + inet '192.168.1/24' >> inet '192.168.1.5' - >>= - contains or equals - inet '192.168.1/24' >>= inet '192.168.1/24' + >>= + contains or equals + inet '192.168.1/24' >>= inet '192.168.1/24' @@ -6223,76 +6223,76 @@ SELECT TIMESTAMP 'now'; - Function - Return Type - Description - Example - Result + Function + Return Type + Description + Example + Result - broadcast(inet) - inet - broadcast address for network - broadcast('192.168.1.5/24') - 192.168.1.255/24 + broadcast(inet) + inet + broadcast address for network + broadcast('192.168.1.5/24') + 192.168.1.255/24 - host(inet) - text - extract IP address as text - host('192.168.1.5/24') - 192.168.1.5 + host(inet) + text + extract IP address as text + host('192.168.1.5/24') + 192.168.1.5 - masklen(inet) - integer - extract netmask length - masklen('192.168.1.5/24') - 24 + masklen(inet) + integer + extract netmask length + masklen('192.168.1.5/24') + 24 - set_masklen(inet, integer) - inet - set netmask length for inet value - set_masklen('192.168.1.5/24', 16) - 192.168.1.5/16 + set_masklen(inet, integer) + inet + set netmask length for inet value + set_masklen('192.168.1.5/24', 16) + 192.168.1.5/16 - netmask(inet) - inet - construct netmask for network - netmask('192.168.1.5/24') - 255.255.255.0 + netmask(inet) + inet + construct netmask for network + netmask('192.168.1.5/24') + 255.255.255.0 - hostmask(inet) - inet - construct host mask for network - hostmask('192.168.23.20/30') - 0.0.0.3 + hostmask(inet) + inet + construct host mask for network + hostmask('192.168.23.20/30') + 0.0.0.3 - network(inet) - cidr - extract network part of address - network('192.168.1.5/24') - 192.168.1.0/24 + network(inet) + cidr + extract network part of address + network('192.168.1.5/24') + 192.168.1.0/24 - text(inet) - text - extract IP address and netmask length as text - text(inet '192.168.1.5') - 192.168.1.5/32 + text(inet) + text + extract IP address and netmask length as text + text(inet '192.168.1.5') + 192.168.1.5/32 - abbrev(inet) - text - abbreviated display format as text - abbrev(cidr '10.1.0.0/16') - 10.1/16 + abbrev(inet) + text + abbreviated display format as text + abbrev(cidr '10.1.0.0/16') + 10.1/16 family(inet) @@ -6322,20 +6322,20 @@ SELECT TIMESTAMP 'now'; - Function - Return Type - Description - Example - Result + Function + Return Type + Description + Example + Result - trunc(macaddr) - macaddr - set last 3 bytes to zero - trunc(macaddr '12:34:56:78:90:ab') - 12:34:56:00:00:00 + trunc(macaddr) + macaddr + set last 3 bytes to zero + trunc(macaddr '12:34:56:78:90:ab') + 12:34:56:00:00:00 @@ -6387,24 +6387,24 @@ SELECT TIMESTAMP 'now'; - nextval(text) - bigint - Advance sequence and return new value + nextval(text) + bigint + Advance sequence and return new value - currval(text) - bigint - Return value most recently obtained with nextval + currval(text) + bigint + Return value most recently obtained with nextval - setval(text, bigint) - bigint - Set sequence's current value + setval(text, bigint) + bigint + Set sequence's current value - setval(text, bigint, boolean) - bigint - Set sequence's current value and is_called flag + setval(text, bigint, boolean) + bigint + Set sequence's current value and is_called flag @@ -6440,9 +6440,9 @@ nextval('foo') searches search path for fo Advance the sequence object to its next value and return that - value. This is done atomically: even if multiple sessions - execute nextval concurrently, each will safely receive - a distinct sequence value. + value. This is done atomically: even if multiple sessions + execute nextval concurrently, each will safely receive + a distinct sequence value. @@ -6452,11 +6452,12 @@ nextval('foo') searches search path for fo Return the value most recently obtained by nextval - for this sequence in the current session. (An error is - reported if nextval has never been called for this - sequence in this session.) Notice that because this is returning - a session-local value, it gives a predictable answer even if other - sessions are executing nextval meanwhile. + for this sequence in the current session. (An error is + reported if nextval has never been called for this + sequence in this session.) Notice that because this is returning + a session-local value, it gives a predictable answer whether or not + other sessions have executed nextval since the + current session did. @@ -6466,15 +6467,15 @@ nextval('foo') searches search path for fo Reset the sequence object's counter value. The two-parameter - form sets the sequence's last_value field to the specified - value and sets its is_called field to true, - meaning that the next nextval will advance the sequence - before returning a value. In the three-parameter form, - is_called may be set either true or - false. If it's set to false, - the next nextval will return exactly the specified - value, and sequence advancement commences with the following - nextval. For example, + form sets the sequence's last_value field to the specified + value and sets its is_called field to true, + meaning that the next nextval will advance the sequence + before returning a value. In the three-parameter form, + is_called may be set either true or + false. If it's set to false, + the next nextval will return exactly the specified + value, and sequence advancement commences with the following + nextval. For example, SELECT setval('foo', 42); Next nextval will return 43 @@ -6483,7 +6484,7 @@ SELECT setval('foo', 42, false); Next nextval wi The result returned by setval is just the value of its - second argument. + second argument. @@ -6719,81 +6720,81 @@ SELECT NULLIF(value, '(none)') ... - Operator - Description - Example - Result + Operator + Description + Example + Result - = - equal - ARRAY[1.1,2.1,3.1]::int[] = ARRAY[1,2,3] - t + = + equal + ARRAY[1.1,2.1,3.1]::int[] = ARRAY[1,2,3] + t - <> - not equal - ARRAY[1,2,3] <> ARRAY[1,2,4] - t + <> + not equal + ARRAY[1,2,3] <> ARRAY[1,2,4] + t - < - less than - ARRAY[1,2,3] < ARRAY[1,2,4] - t + < + less than + ARRAY[1,2,3] < ARRAY[1,2,4] + t - > - greater than - ARRAY[1,4,3] > ARRAY[1,2,4] - t + > + greater than + ARRAY[1,4,3] > ARRAY[1,2,4] + t - <= - less than or equal - ARRAY[1,2,3] <= ARRAY[1,2,3] - t + <= + less than or equal + ARRAY[1,2,3] <= ARRAY[1,2,3] + t - >= - greater than or equal - ARRAY[1,4,3] >= ARRAY[1,4,3] - t + >= + greater than or equal + ARRAY[1,4,3] >= ARRAY[1,4,3] + t - || - array-to-array concatenation - ARRAY[1,2,3] || ARRAY[4,5,6] - {1,2,3,4,5,6} + || + array-to-array concatenation + ARRAY[1,2,3] || ARRAY[4,5,6] + {1,2,3,4,5,6} - || - array-to-array concatenation - ARRAY[1,2,3] || ARRAY[[4,5,6],[7,8,9]] - {{1,2,3},{4,5,6},{7,8,9}} + || + array-to-array concatenation + ARRAY[1,2,3] || ARRAY[[4,5,6],[7,8,9]] + {{1,2,3},{4,5,6},{7,8,9}} - || - element-to-array concatenation - 3 || ARRAY[4,5,6] - {3,4,5,6} + || + element-to-array concatenation + 3 || ARRAY[4,5,6] + {3,4,5,6} - || - array-to-element concatenation - ARRAY[4,5,6] || 7 - {4,5,6,7} + || + array-to-element concatenation + ARRAY[4,5,6] || 7 + {4,5,6,7} @@ -6815,109 +6816,109 @@ SELECT NULLIF(value, '(none)') ... - Function - Return Type - Description - Example - Result + Function + Return Type + Description + Example + Result - + array_cat (anyarray, anyarray) - anyarray - concatenate two arrays - array_cat(ARRAY[1,2,3], ARRAY[4,5]) - {1,2,3,4,5} + anyarray + concatenate two arrays + array_cat(ARRAY[1,2,3], ARRAY[4,5]) + {1,2,3,4,5} - + array_append (anyarray, anyelement) - anyarray - append an element to the end of an array - array_append(ARRAY[1,2], 3) - {1,2,3} + anyarray + append an element to the end of an array + array_append(ARRAY[1,2], 3) + {1,2,3} - + array_prepend (anyelement, anyarray) - anyarray - append an element to the beginning of an array - array_prepend(1, ARRAY[2,3]) - {1,2,3} + anyarray + append an element to the beginning of an array + array_prepend(1, ARRAY[2,3]) + {1,2,3} - + array_dims (anyarray) - text - returns a text representation of array's dimensions - array_dims(array[[1,2,3], [4,5,6]]) - [1:2][1:3] + text + returns a text representation of array's dimensions + array_dims(array[[1,2,3], [4,5,6]]) + [1:2][1:3] - + array_lower (anyarray, integer) - integer - returns lower bound of the requested array dimension - array_lower(array_prepend(0, ARRAY[1,2,3]), 1) - 0 + integer + returns lower bound of the requested array dimension + array_lower(array_prepend(0, ARRAY[1,2,3]), 1) + 0 - + array_upper (anyarray, integer) - integer - returns upper bound of the requested array dimension - array_upper(ARRAY[1,2,3,4], 1) - 4 + integer + returns upper bound of the requested array dimension + array_upper(ARRAY[1,2,3,4], 1) + 4 - + array_to_string (anyarray, text) - text - concatenates array elements using provided delimiter - array_to_string(array[1, 2, 3], '~^~') - 1~^~2~^~3 + text + concatenates array elements using provided delimiter + array_to_string(array[1, 2, 3], '~^~') + 1~^~2~^~3 - + string_to_array (text, text) - text[] - splits string into array elements using provided delimiter - string_to_array( 'xx~^~yy~^~zz', '~^~') - {xx,yy,zz} + text[] + splits string into array elements using provided delimiter + string_to_array( 'xx~^~yy~^~zz', '~^~') + {xx,yy,zz} @@ -8271,7 +8272,8 @@ SELECT has_table_privilege('myschema.mytable', 'select'); can access a function in a particular way. The possibilities for its arguments are analogous to has_table_privilege. When specifying a function by a text string rather than by OID, - the allowed input is the same as for the regprocedure data type. + the allowed input is the same as for the regprocedure data type + (see ). The desired access privilege type must evaluate to EXECUTE. An example is: @@ -8781,8 +8783,8 @@ SELECT set_config('log_statement_stats', 'off', false); - pg_cancel_backend(pid) - + pg_cancel_backend(pid) + int Cancel a backend's current query @@ -8827,15 +8829,15 @@ SELECT set_config('log_statement_stats', 'off', false); - pg_start_backup(label_text) - + pg_start_backup(label_text) + text Set up for performing on-line backup - pg_stop_backup() - + pg_stop_backup() + text Finish performing on-line backup -- 2.40.0