From 4ad047a6eac356436b88681a9383a52cde2ffe9c Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Thu, 30 Apr 2020 00:34:05 -0400 Subject: [PATCH] Doc: re-re-revise markup for tables of functions. Make the markup a bit less ad-hoc. A function-table cell now contains several units, and we label the ones that contain function signatures with role="func_signature". The CSS or FO stylesheets then key off of that to decide how to set the indentation. A very useful win from this approach is that we can have more than one signature entry per table cell, simplifying the documentation of closely-related operators and functions. This patch mostly just replaces the markup in the tables I converted so far. But I did alter a couple of places where multiple signatures were helpful. Discussion: https://postgr.es/m/5561.1587922854@sss.pgh.pa.us --- doc/src/sgml/func.sgml | 4730 +++++++++++++++++----------- doc/src/sgml/stylesheet-common.xsl | 7 - doc/src/sgml/stylesheet-fo.xsl | 35 +- doc/src/sgml/stylesheet.css | 17 +- 4 files changed, 2962 insertions(+), 1827 deletions(-) diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index 692f78aa51..d5c7a14415 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -325,224 +325,269 @@ repeat('Pg', 4) PgPgPgPg - - PredicateDescriptionExample(s) - + + Predicate + + + Description + + + Example(s) + - + datatype BETWEEN datatype AND datatype boolean - + + Between (inclusive of the range endpoints). - + + 2 BETWEEN 1 AND 3 t - + + 2 BETWEEN 3 AND 1 f - + - + datatype NOT BETWEEN datatype AND datatype boolean - + + Not between (the negation of BETWEEN). - + + 2 NOT BETWEEN 1 AND 3 f - + - + datatype BETWEEN SYMMETRIC datatype AND datatype boolean - + + Between, after sorting the two endpoint values. - + + 2 BETWEEN SYMMETRIC 3 AND 1 t - + - + datatype NOT BETWEEN SYMMETRIC datatype AND datatype boolean - + + Not between, after sorting the two endpoint values. - + + 2 NOT BETWEEN SYMMETRIC 3 AND 1 f - + - + datatype IS DISTINCT FROM datatype boolean - + + Not equal, treating null as a comparable value. - + + 1 IS DISTINCT FROM NULL t (rather than NULL) - + + NULL IS DISTINCT FROM NULL f (rather than NULL) - + - + datatype IS NOT DISTINCT FROM datatype boolean - + + Equal, treating null as a comparable value. - + + 1 IS NOT DISTINCT FROM NULL f (rather than NULL) - + + NULL IS NOT DISTINCT FROM NULL t (rather than NULL) - + - + datatype IS NULL boolean - + + Test whether value is null. - + + 1.5 IS NULL f - + - + datatype IS NOT NULL boolean - + + Test whether value is not null. - + + 'null' IS NOT NULL t - + - + datatype ISNULL boolean - + + Test whether value is null (nonstandard syntax). - + - + datatype NOTNULL boolean - + + Test whether value is not null (nonstandard syntax). - + - + boolean IS TRUE boolean - + + Test whether boolean expression yields true. - + + true IS TRUE t - + + NULL::boolean IS TRUE f (rather than NULL) - + - + boolean IS NOT TRUE boolean - + + Test whether boolean expression yields false or unknown. - + + true IS NOT TRUE f - + + NULL::boolean IS NOT TRUE t (rather than NULL) - + - + boolean IS FALSE boolean - + + Test whether boolean expression yields false. - + + true IS FALSE f - + + NULL::boolean IS FALSE f (rather than NULL) - + - + boolean IS NOT FALSE boolean - + + Test whether boolean expression yields true or unknown. - + + true IS NOT FALSE t - + + NULL::boolean IS NOT FALSE t (rather than NULL) - + - + boolean IS UNKNOWN boolean - + + Test whether boolean expression yields unknown. - + + true IS UNKNOWN f - + + NULL::boolean IS UNKNOWN t (rather than NULL) - + - + boolean IS NOT UNKNOWN boolean - + + Test whether boolean expression yields true or false. - + + true IS NOT UNKNOWN t - + + NULL::boolean IS NOT UNKNOWN f (rather than NULL) - + @@ -746,40 +791,50 @@ repeat('Pg', 4) PgPgPgPg - - FunctionDescriptionExample(s) - + + Function + + + Description + + + Example(s) + - + num_nonnulls num_nonnulls ( VARIADIC "any" ) integer - + + Returns the number of non-null arguments. - + + num_nonnulls(1, NULL, 2) 2 - + - + num_nulls num_nulls ( VARIADIC "any" ) integer - + + Returns the number of null arguments. - + + num_nulls(1, NULL, 2) 1 - + @@ -809,9 +864,6 @@ repeat('Pg', 4) PgPgPgPg Operators shown as accepting integral_type are available for the types smallint, integer, and bigint. - Operators shown as accepting numeric_or_dp - are available for the types numeric and double - precision. Except where noted, each form of an operator returns the same data type as its argument(s). Calls involving multiple argument data types, such as integer + numeric, @@ -824,251 +876,302 @@ repeat('Pg', 4) PgPgPgPg - - OperatorDescriptionExample(s) - + + Operator + + + Description + + + Example(s) + - + numeric_type + numeric_type numeric_type - + + Addition - + + 2 + 3 5 - + - + + numeric_type numeric_type - + + Unary plus (no operation) - + + + 3.5 3.5 - + - + numeric_type - numeric_type numeric_type - + + Subtraction - + + 2 - 3 -1 - + - + - numeric_type numeric_type - + + Negation - + + - (-4) 4 - + - + numeric_type * numeric_type numeric_type - + + Multiplication - + + 2 * 3 6 - + - + numeric_type / numeric_type numeric_type - + + Division (for integral types, division truncates the result towards zero) - + + 5.0 / 2 2.5000000000000000 - + + 5 / 2 2 - + + (-5) / 2 -2 - + - + numeric_type % numeric_type numeric_type - + + Modulo (remainder); available for smallint, integer, bigint, and numeric - + + 5 % 4 1 - + - - numeric_or_dp ^ numeric_or_dp - numeric_or_dp - + + numeric ^ numeric + numeric + + + double precision ^ double precision + double precision + + Exponentiation (unlike typical mathematical practice, multiple uses of ^ will associate left to right) - + + 2 ^ 3 8 - + + 2 ^ 3 ^ 3 512 - + - + |/ double precision double precision - + + Square root - + + |/ 25.0 5 - + - + ||/ double precision double precision - + + Cube root - + + ||/ 64.0 4 - + - + bigint ! numeric - + + Factorial - + + 5 ! 120 - + - + !! bigint numeric - + + Factorial (as a prefix operator) - + + !! 5 120 - + - + @ numeric_type numeric_type - + + Absolute value - + + @ -5.0 5 - + - + integral_type & integral_type integral_type - + + Bitwise AND - + + 91 & 15 11 - + - + integral_type | integral_type integral_type - + + Bitwise OR - + + 32 | 3 35 - + - + integral_type # integral_type integral_type - + + Bitwise exclusive OR - + + 17 # 5 20 - + - + ~ integral_type integral_type - + + Bitwise NOT - + + ~1 -2 - + - + integral_type << integer integral_type - + + Bitwise shift left - + + 1 << 4 16 - + - + integral_type >> integer integral_type - + + Bitwise shift right - + + 8 >> 2 2 - + @@ -1093,444 +1196,561 @@ repeat('Pg', 4) PgPgPgPg - - FunctionDescriptionExample(s) - + + Function + + + Description + + + Example(s) + - + abs abs ( numeric_type ) numeric_type - + + Absolute value - + + abs(-17.4) 17.4 - + - + cbrt cbrt ( double precision ) double precision - + + Cube root - + + cbrt(64.0) 4 - + - + ceil - ceil ( numeric_or_dp ) - numeric_or_dp - + ceil ( numeric ) + numeric + + + ceil ( double precision ) + double precision + + Nearest integer greater than or equal to argument - + + ceil(42.2) 43 - + + ceil(-42.8) -42 - + - + ceiling - ceiling ( numeric_or_dp ) - numeric_or_dp - + ceiling ( numeric ) + numeric + + + ceiling ( double precision ) + double precision + + Nearest integer greater than or equal to argument (same as ceil) - + + ceiling(95.3) 96 - + - + degrees degrees ( double precision ) double precision - + + Converts radians to degrees - + + degrees(0.5) 28.64788975654116 - + - + div div ( y numeric, x numeric ) numeric - + + Integer quotient of y/x (truncates towards zero) - + + div(9,4) 2 - + - + exp - exp ( numeric_or_dp ) - numeric_or_dp - + exp ( numeric ) + numeric + + + exp ( double precision ) + double precision + + Exponential (e raised to the given power) - + + exp(1.0) 2.7182818284590452 - + - + floor - floor ( numeric_or_dp ) - numeric_or_dp - + floor ( numeric ) + numeric + + + floor ( double precision ) + double precision + + Nearest integer less than or equal to argument - + + floor(42.8) 42 - + + floor(-42.8) -43 - + - + gcd gcd ( numeric_type, numeric_type ) numeric_type - + + Greatest common divisor (the largest positive number that divides both inputs with no remainder); returns 0 if both inputs are zero; available for integer, bigint, and numeric - + + gcd(1071, 462) 21 - + - + lcm lcm ( numeric_type, numeric_type ) numeric_type - + + Least common multiple (the smallest strictly positive number that is an integral multiple of both inputs); returns 0 if either input is zero; available for integer, bigint, and numeric - + + lcm(1071, 462) 23562 - + - + ln - ln ( numeric_or_dp ) - numeric_or_dp - + ln ( numeric ) + numeric + + + ln ( double precision ) + double precision + + Natural logarithm - + + ln(2.0) 0.6931471805599453 - + - + log - log ( numeric_or_dp ) - numeric_or_dp - + log ( numeric ) + numeric + + + log ( double precision ) + double precision + + Base 10 logarithm - + + log(100) 2 - + - + log10 - log10 ( numeric_or_dp ) - numeric_or_dp - + log10 ( numeric ) + numeric + + + log10 ( double precision ) + double precision + + Base 10 logarithm (same as log) - + + log10(1000) 3 - + - + log ( b numeric, x numeric ) numeric - + + Logarithm of x to base b - + + log(2.0, 64.0) 6.0000000000 - + - + min_scale min_scale ( numeric ) integer - + + Minimum scale (number of fractional decimal digits) needed to represent the supplied value precisely - + + min_scale(8.4100) 2 - + - + mod mod ( y numeric_type, x numeric_type ) numeric_type - + + Remainder of y/x; available for smallint, integer, bigint, and numeric - + + mod(9,4) 1 - + - + pi pi ( ) double precision - + + Approximate value of π - + + pi() 3.141592653589793 - + - + power - power ( a numeric_or_dp, - b numeric_or_dp ) - numeric_or_dp - + power ( a numeric, + b numeric ) + numeric + + + power ( a double precision, + b double precision ) + double precision + + a raised to the power of b - + + power(9, 3) 729 - + - + radians radians ( double precision ) double precision - + + Converts degrees to radians - + + radians(45.0) 0.7853981633974483 - + - + round - round ( numeric_or_dp ) - numeric_or_dp - + round ( numeric ) + numeric + + + round ( double precision ) + double precision + + Rounds to nearest integer - + + round(42.4) 42 - + - + round ( v numeric, s integer ) numeric - + + Rounds v to s decimal places - + + round(42.4382, 2) 42.44 - + - + scale scale ( numeric ) integer - + + Scale of the argument (the number of decimal digits in the fractional part) - + + scale(8.4100) 4 - + - + sign - sign ( numeric_or_dp ) - numeric_or_dp - + sign ( numeric ) + numeric + + + sign ( double precision ) + double precision + + Sign of the argument (-1, 0, or +1) - + + sign(-8.4) -1 - + - + sqrt - sqrt ( numeric_or_dp ) - numeric_or_dp - + sqrt ( numeric ) + numeric + + + sqrt ( double precision ) + double precision + + Square root - + + sqrt(2) 1.4142135623730951 - + - + trim_scale trim_scale ( numeric ) numeric - + + Reduces the value's scale (number of fractional decimal digits) by removing trailing zeroes - + + trim_scale(8.4100) 8.41 - + - + trunc - trunc ( numeric_or_dp ) - numeric_or_dp - + trunc ( numeric ) + numeric + + + trunc ( double precision ) + double precision + + Truncates to integer (towards zero) - + + trunc(42.8) 42 - + + trunc(-42.8) -42 - + - + trunc ( v numeric, s integer ) numeric - + + Truncates v to s decimal places - + + trunc(42.4382, 2) 42.43 - + - + width_bucket - width_bucket ( operand numeric_or_dp, low numeric_or_dp, high numeric_or_dp, count integer ) + width_bucket ( operand numeric, low numeric, high numeric, count integer ) integer - + + + width_bucket ( operand double precision, low double precision, high double precision, count integer ) + integer + + Returns the number of the bucket in which operand falls in a histogram having count equal-width buckets spanning the @@ -1538,17 +1758,19 @@ repeat('Pg', 4) PgPgPgPg Returns 0 or count+1 for an input outside that range. - + + width_bucket(5.35, 0.024, 10.06, 5) 3 - + - + width_bucket ( operand anyelement, thresholds anyarray ) integer - + + Returns the number of the bucket in which operand falls given an array listing the lower bounds of the buckets. Returns 0 for an @@ -1558,10 +1780,11 @@ repeat('Pg', 4) PgPgPgPg The thresholds array must be sorted, smallest first, or unexpected results will be obtained. - + + width_bucket(now(), array['yesterday', 'today', 'tomorrow']::timestamptz[]) 2 - + @@ -1578,41 +1801,51 @@ repeat('Pg', 4) PgPgPgPg - - FunctionDescriptionExample(s) - + + Function + + + Description + + + Example(s) + - + random random ( ) double precision - + + Returns a random value in the range 0.0 <= x < 1.0 - + + random() 0.897124072839091 - + - + setseed setseed ( double precision ) void - + + Sets the seed for subsequent random() calls; argument must be between -1.0 and 1.0, inclusive - + + setseed(0.12345) - + @@ -1642,257 +1875,295 @@ repeat('Pg', 4) PgPgPgPg - - FunctionDescriptionExample(s) - + + Function + + + Description + + + Example(s) + - + acos acos ( double precision ) double precision - + + Inverse cosine, result in radians - + + acos(1) 0 - + - + acosd acosd ( double precision ) double precision - + + Inverse cosine, result in degrees - + + acosd(0.5) 60 - + - + asin asin ( double precision ) double precision - + + Inverse sine, result in radians - + + asin(1) 1.5707963267948966 - + - + asind asind ( double precision ) double precision - + + Inverse sine, result in degrees - + + asind(0.5) 30 - + - + atan atan ( double precision ) double precision - + + Inverse tangent, result in radians - + + atan(1) 0.7853981633974483 - + - + atand atand ( double precision ) double precision - + + Inverse tangent, result in degrees - + + atand(1) 45 - + - + atan2 atan2 ( y double precision, x double precision ) double precision - + + Inverse tangent of y/x, result in radians - + + atan2(1,0) 1.5707963267948966 - + - + atan2d atan2d ( y double precision, x double precision ) double precision - + + Inverse tangent of y/x, result in degrees - + + atan2d(1,0) 90 - + - + cos cos ( double precision ) double precision - + + Cosine, argument in radians - + + cos(0) 1 - + - + cosd cosd ( double precision ) double precision - + + Cosine, argument in degrees - + + cosd(60) 0.5 - + - + cot cot ( double precision ) double precision - + + Cotangent, argument in radians - + + cot(0.5) 1.830487721712452 - + - + cotd cotd ( double precision ) double precision - + + Cotangent, argument in degrees - + + cotd(45) 1 - + - + sin sin ( double precision ) double precision - + + Sine, argument in radians - + + sin(1) 0.8414709848078965 - + - + sind sind ( double precision ) double precision - + + Sine, argument in degrees - + + sind(30) 0.5 - + - + tan tan ( double precision ) double precision - + + Tangent, argument in radians - + + tan(1) 1.5574077246549023 - + - + tand tand ( double precision ) double precision - + + Tangent, argument in degrees - + + tand(45) 1 - + @@ -1920,101 +2191,119 @@ repeat('Pg', 4) PgPgPgPg - - FunctionDescriptionExample(s) - + + Function + + + Description + + + Example(s) + - + sinh sinh ( double precision ) double precision - + + Hyperbolic sine - + + sinh(1) 1.1752011936438014 - + - + cosh cosh ( double precision ) double precision - + + Hyperbolic cosine - + + cosh(0) 1 - + - + tanh tanh ( double precision ) double precision - + + Hyperbolic tangent - + + tanh(1) 0.7615941559557649 - + - + asinh asinh ( double precision ) double precision - + + Inverse hyperbolic sine - + + asinh(1) 0.881373587019543 - + - + acosh acosh ( double precision ) double precision - + + Inverse hyperbolic cosine - + + acosh(1) 0 - + - + atanh atanh ( double precision ) double precision - + + Inverse hyperbolic tangent - + + atanh(0.5) 0.5493061443340548 - + @@ -2067,48 +2356,61 @@ repeat('Pg', 4) PgPgPgPg - - Function/OperatorDescriptionExample(s) - + + Function/Operator + + + Description + + + Example(s) + - + character string concatenation text || text text - + + Concatenates the two strings. - + + 'Post' || 'greSQL' PostgreSQL - + - + text || anynonarray - or anynonarray || text text - + + + anynonarray || text + text + + Converts the non-string input to text, then concatenates the two strings. (The non-string input cannot be of an array type, because that would create ambiguity with the array || operators. If you want to concatenate an array's text equivalent, cast it to text explicitly.) - + + 'Value: ' || 42 Value: 42 - + - + normalized @@ -2117,7 +2419,8 @@ repeat('Pg', 4) PgPgPgPg text IS NOT form NORMALIZED boolean - + + Checks whether the string is in the specified Unicode normalization form. The optional form key word specifies the form: NFC (the default), NFD, @@ -2125,30 +2428,33 @@ repeat('Pg', 4) PgPgPgPg only be used when the server encoding is UTF8. Note that checking for normalization using this expression is often faster than normalizing possibly already normalized strings. - + + U&'\0061\0308bc' IS NFD NORMALIZED t - + - + bit_length bit_length ( text ) integer - + + Returns number of bits in the string (8 times the octet_length). - + + bit_length('jose') 32 - + - + char_length @@ -2162,34 +2468,44 @@ repeat('Pg', 4) PgPgPgPg character string, length char_length ( text ) - or character_length ( text ) integer - + + + + character_length + + character_length ( text ) + integer + + Returns number of characters in the string. - + + char_length('josé') 4 - + - + lower lower ( text ) text - + + Converts the string to all lower case, according to the rules of the database's locale. - + + lower('TOM') tom - + - + normalize @@ -2199,140 +2515,158 @@ repeat('Pg', 4) PgPgPgPg normalize ( text , form ) text - + + Converts the string to the specified Unicode normalization form. The optional form key word specifies the form: NFC (the default), NFD, NFKC, or NFKD. This function can only be used when the server encoding is UTF8. - + + normalize(U&'\0061\0308bc', NFC) U&'\00E4bc' - + - + octet_length octet_length ( text ) integer - + + Returns number of bytes in the string. - + + octet_length('josé') 5 (if server encoding is UTF8) - + - + octet_length octet_length ( character ) integer - + + Returns number of bytes in the string. Since this version of the function accepts type character directly, it will not strip trailing spaces. - + + octet_length('abc '::character(4)) 4 - + - + overlay overlay ( string text PLACING newsubstring text FROM start integer FOR count integer ) text - + + Replaces the substring of string that starts at the start'th character and extends for count characters with newsubstring. If count is omitted, it defaults to the length of newsubstring. - + + overlay('Txxxxas' placing 'hom' from 2 for 4) Thomas - + - + position position ( substring text IN string text ) integer - + + Returns starting index of specified substring within string, or zero if it's not present. - + + position('om' in 'Thomas') 3 - + - + substring substring ( string text FROM start integer FOR count integer ) text - + + Extracts the substring of string starting at the start'th character if that is specified, and stopping after count characters if that is specified. Provide at least one of start and count. - + + substring('Thomas' from 2 for 3) hom - + + substring('Thomas' from 3) omas - + + substring('Thomas' for 2) Th - + - + substring ( string text FROM pattern text ) text - + + Extracts substring matching POSIX regular expression; see . - + + substring('Thomas' from '...$') mas - + - + substring ( string text FROM pattern text FOR escape text ) text - + + Extracts substring matching SQL regular expression; see . - + + substring('Thomas' from '%#"o_a#"_' for '#') oma - + - + trim @@ -2340,45 +2674,51 @@ repeat('Pg', 4) PgPgPgPg characters text FROM string text ) text - + + Removes the longest string containing only characters in characters (a space by default) from the start, end, or both ends (BOTH is the default) of string. - + + trim(both 'xyz' from 'yxTomxx') Tom - + - + trim ( LEADING | TRAILING | BOTH FROM string text , characters text ) text - + + This is a non-standard syntax for trim(). - + + trim(both from 'yxTomxx', 'xyz') Tom - + - + upper upper ( text ) text - + + Converts the string to all upper case, according to the rules of the database's locale. - + + upper('tom') TOM - + @@ -2395,87 +2735,101 @@ repeat('Pg', 4) PgPgPgPg - - FunctionDescriptionExample(s) - + + Function + + + Description + + + Example(s) + - + ascii ascii ( text ) integer - + + Returns the numeric code of the first character of the argument. In UTF8 encoding, returns the Unicode code point of the character. In other multibyte encodings, the argument must be an ASCII character. - + + ascii('x') 120 - + - + btrim btrim ( string text , characters text ) text - + + Removes the longest string containing only characters in characters (a space by default) from the start and end of string. - + + btrim('xyxtrimyyx', 'xyz') trim - + - + chr chr ( integer ) text - + + Returns the character with the given code. In UTF8 encoding the argument is treated as a Unicode code point. In other multibyte encodings the argument must designate an ASCII character. chr(0) is disallowed because text data types cannot store that character. - + + chr(65) A - + - + concat concat ( val1 "any" [, val2 "any" [, ...] ] ) text - + + Concatenates the text representations of all the arguments. NULL arguments are ignored. - + + concat('abcde', 2, NULL, 22) abcde222 - + - + concat_ws @@ -2483,86 +2837,96 @@ repeat('Pg', 4) PgPgPgPg val1 "any" [, val2 "any" [, ...] ] ) text - + + Concatenates all but the first argument, with separators. The first argument is used as the separator string, and should not be NULL. Other NULL arguments are ignored. - + + concat_ws(',', 'abcde', 2, NULL, 22) abcde,2,22 - + - + format format ( formatstr text [, formatarg "any" [, ...] ] ) text - + + Formats arguments according to a format string; see . This function is similar to the C function sprintf. - + + format('Hello %s, %1$s', 'World') Hello World, World - + - + initcap initcap ( text ) text - + + Converts the first letter of each word to upper case and the rest to lower case. Words are sequences of alphanumeric characters separated by non-alphanumeric characters. - + + initcap('hi THOMAS') Hi Thomas - + - + left left ( string text, n integer ) text - + + Returns first n characters in the string, or when n is negative, returns all but last |n| characters. - + + left('abcde', 2) ab - + - + length length ( text ) integer - + + Returns the number of characters in the string. - + + length('jose') 4 - + - + lpad @@ -2570,61 +2934,68 @@ repeat('Pg', 4) PgPgPgPg length integer , fill text ) text - + + Extends the string to length length by prepending the characters fill (a space by default). If the string is already longer than length then it is truncated (on the right). - + + lpad('hi', 5, 'xy') xyxhi - + - + ltrim ltrim ( string text , characters text ) text - + + Removes the longest string containing only characters in characters (a space by default) from the start of string. - + + ltrim('zzzytest', 'xyz') test - + - + md5 md5 ( text ) text - + + Computes the MD5 hash of the argument, with the result written in hexadecimal. - + + md5('abc') 900150983cd24fb0&zwsp;d6963f7d28e17f72 - + - + parse_ident parse_ident ( qualified_identifier text [, strict_mode boolean DEFAULT true ] ) text[] - + + Splits qualified_identifier into an array of identifiers, removing any quoting of individual identifiers. By default, extra characters after the last identifier are considered an @@ -2633,55 +3004,61 @@ repeat('Pg', 4) PgPgPgPg names for objects like functions.) Note that this function does not truncate over-length identifiers. If you want truncation you can cast the result to name[]. - + + parse_ident('"SomeSchema".someTable') {SomeSchema,sometable} - + - + pg_client_encoding pg_client_encoding ( ) name - + + Returns current client encoding name. - + + pg_client_encoding() UTF8 - + - + quote_ident quote_ident ( text ) text - + + Returns 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. See also . - + + quote_ident('Foo bar') "Foo bar" - + - + quote_literal quote_literal ( text ) text - + + Returns the given string suitably quoted to be used as a string literal in an SQL statement string. Embedded single-quotes and backslashes are properly doubled. @@ -2689,160 +3066,189 @@ repeat('Pg', 4) PgPgPgPg input; if the argument might be null, quote_nullable is often more suitable. See also . - + + quote_literal(E'O\'Reilly') 'O''Reilly' - + - + quote_literal ( anyelement ) text - + + Converts the given value to text and then quotes it as a literal. Embedded single-quotes and backslashes are properly doubled. - + + quote_literal(42.5) '42.5' - + - + quote_nullable quote_nullable ( text ) text - + + Returns the given string suitably quoted to be used as a string literal in an SQL statement string; or, if the argument is null, returns NULL. Embedded single-quotes and backslashes are properly doubled. See also . - + + quote_nullable(NULL) NULL - + - + quote_nullable ( anyelement ) text - + + Converts the given value to text and then quotes it as a literal; or, if the argument is null, returns NULL. Embedded single-quotes and backslashes are properly doubled. - + + quote_nullable(42.5) '42.5' - + - + regexp_match regexp_match ( string text, pattern text [, flags text ] ) text[] - + + Returns captured substring(s) resulting from the first match of a POSIX regular expression to the string; see . - + + regexp_match('foobarbequebaz', '(bar)(beque)') {bar,beque} - + - + regexp_matches regexp_matches ( string text, pattern text [, flags text ] ) setof text[] - + + Returns captured substring(s) resulting from matching a POSIX regular expression to the string; see . - + + regexp_matches('foobarbequebaz', 'ba.', 'g') - {bar}{baz}(2 rows in result) - + + + {bar} + {baz} + + (2 rows in result) + - + regexp_replace regexp_replace ( string text, pattern text, replacement text [, flags text ] ) text - + + Replaces substring(s) matching a POSIX regular expression; see . - + + regexp_replace('Thomas', '.[mN]a.', 'M') ThM - + - + regexp_split_to_array regexp_split_to_array ( string text, pattern text [, flags text ] ) text[] - + + Splits string using a POSIX regular expression as the delimiter; see . - + + regexp_split_to_array('hello world', '\s+') {hello,world} - + - + regexp_split_to_table regexp_split_to_table ( string text, pattern text [, flags text ] ) setof text - + + Splits string using a POSIX regular expression as the delimiter; see . - + + regexp_split_to_table('hello world', '\s+') - helloworld(2 rows in result) - + + + hello + world + + (2 rows in result) + - + repeat repeat ( string text, number integer ) text - + + Repeats string the specified number of times. - + + repeat('Pg', 4) PgPgPgPg - + - + replace @@ -2850,33 +3256,37 @@ repeat('Pg', 4) PgPgPgPg from text, to text ) text - + + Replaces all occurrences in string of substring from with substring to. - + + replace('abcdefabcdef', 'cd', 'XX') abXXefabXXef - + - + reverse reverse ( text ) text - + + Reverses the order of the characters in the string. - + + reverse('abcde') edcba - + - + right @@ -2884,18 +3294,20 @@ repeat('Pg', 4) PgPgPgPg n integer ) ) text - + + Returns last n characters in the string, or when n is negative, returns all but first |n| characters. - + + right('abcde', 2) de - + - + rpad @@ -2904,38 +3316,42 @@ repeat('Pg', 4) PgPgPgPg , fill text ) ) text - + + Extends the string to length length by appending the characters fill (a space by default). If the string is already longer than length then it is truncated. - + + rpad('hi', 5, 'xy') hixyx - + - + rtrim rtrim ( string text , characters text ) text - + + Removes the longest string containing only characters in characters (a space by default) from the end of string. - + + rtrim('testxxzx', 'xyz') test - + - + split_part @@ -2943,43 +3359,48 @@ repeat('Pg', 4) PgPgPgPg delimiter text, n integer ) text - + + Splits string at occurrences of delimiter and returns the n'th field (counting from one). - + + split_part('abc~@~def~@~ghi', '~@~', 2) def - + - + strpos strpos ( string text, substring text ) integer - + + Returns starting index of specified substring within string, or zero if it's not present. (Same as position(substring in string), but note the reversed argument order.) - + + strpos('high', 'ig') 2 - + - + substr substr ( string text, start integer , count integer ) text - + + Extracts the substring of string starting at the start'th character, and extending for count characters if that is @@ -2987,73 +3408,94 @@ repeat('Pg', 4) PgPgPgPg as substring(string from start for count).) - + + substr('alphabet', 3) phabet - + + substr('alphabet', 3, 2) ph - + - + starts_with starts_with ( string text, prefix text ) boolean - + + Returns true if string starts with prefix. - + + starts_with('alphabet', 'alph') t - + - + to_ascii - to_ascii ( string text - , encoding name or integer ) + to_ascii ( string text ) text - + + + to_ascii ( string text, + encoding name ) + text + + + to_ascii ( string text, + encoding integer ) + text + + Converts string to ASCII - from another encoding, which may be identified by name or number; - if encoding is omitted the database encoding - is assumed. The conversion consists primarily of dropping accents. + from another encoding, which may be identified by name or number. + If encoding is omitted the database encoding + is assumed (which in practice is the only useful case). + The conversion consists primarily of dropping accents. Conversion is only supported from LATIN1, LATIN2, LATIN9, and WIN1250 encodings. - + (See the module for another, more flexible + solution.) + + to_ascii('Karél') Karel - + - + to_hex - to_hex ( number - integer - or bigint ) + to_hex ( integer ) text - - Converts number to its equivalent hexadecimal - representation. - + + + to_hex ( bigint ) + text + + + Converts the number to its equivalent hexadecimal representation. + + to_hex(2147483647) 7fffffff - + - + translate @@ -3061,17 +3503,19 @@ repeat('Pg', 4) PgPgPgPg from text, to text ) text - + + Replaces each character in string that matches a character in the from set with the corresponding character in the to set. If from is longer than to, occurrences of the extra characters in from are deleted. - + + translate('12345', '143', 'ax') a2x5 - + @@ -3339,117 +3783,135 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three'); - - Function/OperatorDescriptionExample(s) - + + Function/Operator + + + Description + + + Example(s) + - + binary string concatenation bytea || bytea bytea - + + Concatenates the two binary strings. - + + '\x123456'::bytea || '\x789a00bcde'::bytea \x123456789a00bcde - + - + bit_length bit_length ( bytea ) integer - + + Returns number of bits in the binary string (8 times the octet_length). - + + bit_length('\x123456'::bytea) 24 - + - + octet_length octet_length ( bytea ) integer - + + Returns number of bytes in the binary string. - + + octet_length('\x123456'::bytea) 3 - + - + overlay overlay ( bytes bytea PLACING newsubstring bytea FROM start integer FOR count integer ) bytea - + + Replaces the substring of bytes that starts at the start'th byte and extends for count bytes with newsubstring. If count is omitted, it defaults to the length of newsubstring. - + + overlay('\x1234567890'::bytea placing '\002\003'::bytea from 2 for 3) \x12020390 - + - + position position ( substring bytea IN bytes bytea ) integer - + + Returns starting index of specified substring within bytes, or zero if it's not present. - + + position('\x5678'::bytea in '\x1234567890'::bytea) 3 - + - + substring substring ( bytes bytea FROM start integer FOR count integer ) bytea - + + Extracts the substring of bytes starting at the start'th byte if that is specified, and stopping after count bytes if that is specified. Provide at least one of start and count. - + + substring('\x1234567890'::bytea from 3 for 2) \x5678 - + - + trim @@ -3457,28 +3919,32 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three'); bytesremoved bytea FROM bytes bytea ) bytea - + + Removes the longest string containing only bytes appearing in bytesremoved from the start and end of bytes. - + + trim('\x9012'::bytea from '\x1234567890'::bytea) \x345678 - + - + trim ( BOTH FROM bytes bytea, bytesremoved bytea ) bytea - + + This is a non-standard syntax for trim(). - + + trim(both from '\x1234567890'::bytea, '\x9012'::bytea) \x345678 - + @@ -3497,67 +3963,79 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three'); - - FunctionDescriptionExample(s) - + + Function + + + Description + + + Example(s) + - + btrim btrim ( bytes bytea, bytesremoved bytea ) bytea - + + Removes the longest string containing only bytes appearing in bytesremoved from the start and end of bytes. - + + btrim('\x1234567890'::bytea, '\x9012'::bytea) \x345678 - + - + get_bit get_bit ( bytes bytea, n bigint ) integer - + + Extracts n'th bit from binary string. - + + get_bit('\x1234567890'::bytea, 30) 1 - + - + get_byte get_byte ( bytes bytea, n integer ) integer - + + Extracts n'th byte from binary string. - + + get_byte('\x1234567890'::bytea, 4) 144 - + - + length @@ -3572,46 +4050,52 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three'); length ( bytea ) integer - + + Returns the number of bytes in the binary string. - + + length('\x1234567890'::bytea) 5 - + - + length ( bytes bytea, encoding name ) integer - + + Returns the number of characters in the binary string, assuming that it is text in the given encoding. - + + length('jose'::bytea, 'UTF8') 4 - + - + md5 md5 ( bytea ) text - + + Computes the MD5 hash of the binary string, with the result written in hexadecimal. - + + md5('Th\000omas'::bytea) 8ab2d3c9689aaf18&zwsp;b4958c334c82d8b1 - + - + set_bit @@ -3619,17 +4103,19 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three'); n bigint, newvalue integer ) bytea - + + Sets n'th bit in binary string to newvalue. - + + set_bit('\x1234567890'::bytea, 30, 0) \x1234563890 - + - + set_byte @@ -3637,87 +4123,98 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three'); n integer, newvalue integer ) bytea - + + Sets n'th byte in binary string to newvalue. - + + set_byte('\x1234567890'::bytea, 4, 64) \x1234567840 - + - + sha224 sha224 ( bytea ) bytea - + + Computes the SHA-224 hash of the binary string. - + + sha224('abc'::bytea) \x23097d223405d8228642a477bda2&zwsp;55b32aadbce4bda0b3f7e36c9da7 - + - + sha256 sha256 ( bytea ) bytea - + + Computes the SHA-256 hash of the binary string. - + + sha256('abc'::bytea) \xba7816bf8f01cfea414140de5dae2223&zwsp;b00361a396177a9cb410ff61f20015ad - + - + sha384 sha384 ( bytea ) bytea - + + Computes the SHA-384 hash of the binary string. - + + sha384('abc'::bytea) \xcb00753f45a35e8bb5a03d699ac65007&zwsp;272c32ab0eded1631a8b605a43ff5bed&zwsp;8086072ba1e7cc2358baeca134c825a7 - + - + sha512 sha512 ( bytea ) bytea - + + Computes the SHA-512 hash of the binary string. - + + sha512('abc'::bytea) \xddaf35a193617abacc417349ae204131&zwsp;12e6fa4e89a97ea20a9eeee64b55d39a&zwsp;2192992a274fc1a836ba3c23a3feebbd&zwsp;454d4423643ce80e2a9ac94fa54ca49f - + - + substr substr ( bytes bytea, start integer , count integer ) bytea - + + Extracts the substring of bytes starting at the start'th byte, and extending for count bytes if that is @@ -3725,10 +4222,11 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three'); as substring(bytes from start for count).) - + + substr('\x1234567890'::bytea, 3, 2) \x5678 - + @@ -3778,15 +4276,21 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three'); - - FunctionDescriptionExample(s) - + + Function + + + Description + + + Example(s) + - + convert @@ -3794,93 +4298,103 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three'); src_encoding name, dest_encoding name ) bytea - + + Converts a binary string representing text in encoding src_encoding to a binary string in encoding dest_encoding (see for available conversions). - + + convert('text_in_utf8', 'UTF8', 'LATIN1') \x746578745f696e5f75746638 - + - + convert_from convert_from ( bytes bytea, src_encoding name ) text - + + Converts a binary string representing text in encoding src_encoding to text in the database encoding (see for available conversions). - + + convert_from('text_in_utf8', 'UTF8') text_in_utf8 - + - + convert_to convert_to ( string text, dest_encoding name ) bytea - + + Converts a text string (in the database encoding) to a binary string encoded in encoding dest_encoding (see for available conversions). - + + convert_to('some_text', 'UTF8') \x736f6d655f74657874 - + - + encode encode ( bytes bytea, format text ) text - + + Encodes binary data into a textual representation; supported format values are: base64, escape, hex. - + + encode('123\000\001', 'base64') MTIzAAE= - + - + decode decode ( string text, format text ) bytea - + + Decodes binary data from a textual representation; supported format values are the same as for encode. - + + decode('MTIzAAE=', 'base64') \x3132330001 - + @@ -3987,97 +4501,117 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three'); - - OperatorDescriptionExample(s) - + + Operator + + + Description + + + Example(s) + - + bit || bit bit - + + Concatenation - + + B'10001' || B'011' 10001011 - + - + bit & bit bit - + + Bitwise AND (inputs must be of equal length) - + + B'10001' & B'01101' 00001 - + - + bit | bit bit - + + Bitwise OR (inputs must be of equal length) - + + B'10001' | B'01101' 11101 - + - + bit # bit bit - + + Bitwise exclusive OR (inputs must be of equal length) - + + B'10001' # B'01101' 11100 - + - + ~ bit bit - + + Bitwise NOT - + + ~ B'10001' 01110 - + - + bit << integer bit - + + Bitwise shift left (string length is preserved) - + + B'10001' << 3 01000 - + - + bit >> integer bit - + + Bitwise shift right (string length is preserved) - + + B'10001' >> 2 00100 - + @@ -4093,30 +4627,38 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three'); - - FunctionDescriptionExample(s) - + + Function + + + Description + + + Example(s) + - + bit_length bit_length ( bit ) integer - + + Returns number of bits in the bit string. - + + bit_length(B'10111') 5 - + - + length @@ -4126,103 +4668,115 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three'); length ( bit ) integer - + + Returns number of bits in the bit string. - + + length(B'10111') 5 - + - + octet_length octet_length ( bit ) integer - + + Returns number of bytes in the bit string. - + + octet_length(B'1011111011') 2 - + - + overlay overlay ( bits bit PLACING newsubstring bit FROM start integer FOR count integer ) bit - + + Replaces the substring of bits that starts at the start'th bit and extends for count bits with newsubstring. If count is omitted, it defaults to the length of newsubstring. - + + overlay(B'01010101010101010' placing B'11111' from 2 for 3) 0111110101010101010 - + - + position position ( substring bit IN bits bit ) integer - + + Returns starting index of specified substring within bits, or zero if it's not present. - + + position(B'010' in B'000001101011') 8 - + - + substring substring ( bits bit FROM start integer FOR count integer ) bit - + + Extracts the substring of bits starting at the start'th bit if that is specified, and stopping after count bits if that is specified. Provide at least one of start and count. - + + substring(B'110010111111' from 3 for 2) 00 - + - + get_bit get_bit ( bits bit, n integer ) integer - + + Extracts n'th bit from bit string; the first (leftmost) bit is bit 0. - + + get_bit(B'101010101010101010', 6) 1 - + - + set_bit @@ -4230,14 +4784,16 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three'); n integer, newvalue integer ) bit - + + Sets n'th bit in bit string to newvalue; the first (leftmost) bit is bit 0. - + + set_bit(B'101010101010101010', 6, 0) 101010001010101010 - + @@ -4673,59 +5229,73 @@ substring('foobar' from '#"o_b#"%' for '#') NULL - - OperatorDescriptionExample(s) - + + Operator + + + Description + + + Example(s) + - + text ~ text boolean - + + String matches regular expression, case sensitively - + + 'thomas' ~ '.*thom.*' t - + - + text ~* text boolean - + + String matches regular expression, case insensitively - + + 'thomas' ~* '.*Thom.*' t - + - + text !~ text boolean - + + String does not match regular expression, case sensitively - + + 'thomas' !~ '.*thomas.*' f - + - + text !~* text boolean - + + String does not match regular expression, case insensitively - + + 'thomas' !~* '.*vadim.*' t - + @@ -6446,105 +7016,129 @@ SELECT regexp_match('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}'); - - FunctionDescriptionExample(s) - + + Function + + + Description + + + Example(s) + - + to_char - to_char ( timestamp with time zone, text ) + to_char ( timestamp, text ) text - + + + to_char ( timestamp with time zone, text ) + text + + Converts time stamp to string according to the given format. - + + to_char(timestamp '2002-04-20 17:31:12.66', 'HH12:MI:SS') 05:31:12 - + - + to_char ( interval, text ) text - + + Converts interval to string according to the given format. - + + to_char(interval '15h 2m 12s', 'HH24:MI:SS') 15:02:12 - + - + to_char ( numeric_type, text ) text - + + Converts number to string according to the given format; available for integer, bigint, numeric, real, double precision. - + + to_char(125, '999') 125 - + + to_char(125.8::real, '999D9') 125.8 - + + to_char(-125.8, '999D99S') 125.80- - + - + to_date to_date ( text, text ) date - + + Converts string to date according to the given format. - + + to_date('05 Dec 2000', 'DD Mon YYYY') 2000-12-05 - + - + to_number to_number ( text, text ) numeric - + + Converts string to numeric according to the given format. - + + to_number('12,454.8-', '99G999D9S') -12454.8 - + - + to_timestamp to_timestamp ( text, text ) timestamp with time zone - + + Converts string to time stamp according to the given format. (See also to_timestamp(double precision) in .) - + + to_timestamp('05 Dec 2000', 'DD Mon YYYY') 2000-12-05 00:00:00-05 - + @@ -7588,221 +8182,263 @@ SELECT regexp_match('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}'); - - OperatorDescriptionExample(s) - + + Operator + + + Description + + + Example(s) + - + date + integer date - + + Add a number of days to a date - + + date '2001-09-28' + 7 2001-10-05 - + - + date + interval timestamp - + + Add an interval to a date - + + date '2001-09-28' + interval '1 hour' 2001-09-28 01:00:00 - + - + date + time timestamp - + + Add a time-of-day to a date - + + date '2001-09-28' + time '03:00' 2001-09-28 03:00:00 - + - + interval + interval interval - + + Add intervals - + + interval '1 day' + interval '1 hour' 1 day 01:00:00 - + - + timestamp + interval timestamp - + + Add an interval to a timestamp - + + timestamp '2001-09-28 01:00' + interval '23 hours' 2001-09-29 00:00:00 - + - + time + interval time - + + Add an interval to a time - + + time '01:00' + interval '3 hours' 04:00:00 - + - + - interval interval - + + Negate an interval - + + - interval '23 hours' -23:00:00 - + - + date - date integer - + + Subtract dates, producing the number of days elapsed - + + date '2001-10-01' - date '2001-09-28' 3 - + - + date - integer date - + + Subtract a number of days from a date - + + date '2001-10-01' - 7 2001-09-24 - + - + date - interval timestamp - + + Subtract an interval from a date - + + date '2001-09-28' - interval '1 hour' 2001-09-27 23:00:00 - + - + time - time interval - + + Subtract times - + + time '05:00' - time '03:00' 02:00:00 - + - + time - interval time - + + Subtract an interval from a time - + + time '05:00' - interval '2 hours' 03:00:00 - + - + timestamp - interval timestamp - + + Subtract an interval from a timestamp - + + timestamp '2001-09-28 23:00' - interval '23 hours' 2001-09-28 00:00:00 - + - + interval - interval interval - + + Subtract intervals - + + interval '1 day' - interval '1 hour' 1 day -01:00:00 - + - + timestamp - timestamp interval - + + Subtract timestamps - + + timestamp '2001-09-29 03:00' - timestamp '2001-09-27 12:00' 1 day 15:00:00 - + - + interval * double precision interval - + + Multiply an interval by a scalar - + + interval '1 second' * 900 00:15:00 - + + interval '1 day' * 21 21 days - + + interval '1 hour' * 3.5 03:30:00 - + - + interval / double precision interval - + + Divide an interval by a scalar - + + interval '1 hour' / 1.5 00:40:00 - + @@ -7813,373 +8449,429 @@ SELECT regexp_match('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}'); - - FunctionDescriptionExample(s) - + + Function + + + Description + + + Example(s) + - + age age ( timestamp, timestamp ) interval - + + Subtract arguments, producing a symbolic result that uses years and months, rather than just days - + + age(timestamp '2001-04-10', timestamp '1957-06-13') 43 years 9 mons 27 days - + - + age ( timestamp ) interval - + + Subtract argument from current_date (at midnight) - + + age(timestamp '1957-06-13') 62 years 6 mons 10 days - + - + clock_timestamp clock_timestamp ( ) timestamp with time zone - + + Current date and time (changes during statement execution); see - + + clock_timestamp() 2019-12-23 14:39:53.662522-05 - + - + current_date current_date date - + + Current date; see - + + current_date 2019-12-23 - + - + current_time current_time time with time zone - + + Current time of day; see - + + current_time 14:39:53.662522-05 - + - + current_time ( integer ) time with time zone - + + Current time of day, with limited precision; see - + + current_time(2) 14:39:53.66-05 - + - + current_timestamp current_timestamp timestamp with time zone - + + Current date and time (start of current transaction); see - + + current_timestamp 2019-12-23 14:39:53.662522-05 - + - + current_timestamp ( integer ) timestamp with time zone - + + Current date and time (start of current transaction), with limited precision; see - + + current_timestamp(0) 2019-12-23 14:39:53-05 - + - + date_part date_part ( text, timestamp ) double precision - + + Get timestamp subfield (equivalent to extract); see - + + date_part('hour', timestamp '2001-02-16 20:38:40') 20 - + - + date_part ( text, interval ) double precision - + + Get interval subfield (equivalent to extract); see - + + date_part('month', interval '2 years 3 months') 3 - + - + date_trunc date_trunc ( text, timestamp ) timestamp - + + Truncate to specified precision; see - + + date_trunc('hour', timestamp '2001-02-16 20:38:40') 2001-02-16 20:00:00 - + - + date_trunc ( text, timestamp with time zone, text ) timestamp with time zone - + + Truncate to specified precision in the specified time zone; see - + + date_trunc('day', timestamptz '2001-02-16 20:38:40+00', 'Australia/Sydney') 2001-02-16 13:00:00+00 - + - + date_trunc ( text, interval ) interval - + + Truncate to specified precision; see - + + date_trunc('hour', interval '2 days 3 hours 40 minutes') 2 days 03:00:00 - + - + extract extract ( field from timestamp ) double precision - + + Get timestamp subfield; see - + + extract(hour from timestamp '2001-02-16 20:38:40') 20 - + - + extract ( field from interval ) double precision - + + Get interval subfield; see - + + extract(month from interval '2 years 3 months') 3 - + - + isfinite isfinite ( date ) boolean - + + Test for finite date (not +/-infinity) - + + isfinite(date '2001-02-16') true - + - + isfinite ( timestamp ) boolean - + + Test for finite timestamp (not +/-infinity) - + + isfinite(timestamp 'infinity') false - + - + isfinite ( interval ) boolean - + + Test for finite interval (currently always true) - + + isfinite(interval '4 hours') true - + - + justify_days justify_days ( interval ) interval - + + Adjust interval so 30-day time periods are represented as months - + + justify_days(interval '35 days') 1 mon 5 days - + - + justify_hours justify_hours ( interval ) interval - + + Adjust interval so 24-hour time periods are represented as days - + + justify_hours(interval '27 hours') 1 day 03:00:00 - + - + justify_interval justify_interval ( interval ) interval - + + Adjust interval using justify_days and justify_hours, with additional sign adjustments - + + justify_interval(interval '1 mon -1 hour') 29 days 23:00:00 - + - + localtime localtime time - + + Current time of day; see - + + localtime 14:39:53.662522 - + - + localtime ( integer ) time - + + Current time of day, with limited precision; see - + + localtime(0) 14:39:53 - + - + localtimestamp localtimestamp timestamp - + + Current date and time (start of current transaction); see - + + localtimestamp 2019-12-23 14:39:53.662522 - + - + localtimestamp ( integer ) timestamp - + + Current date and time (start of current transaction), with limited precision; see - + + localtimestamp(2) 2019-12-23 14:39:53.66 - + - + make_date @@ -8187,16 +8879,18 @@ SELECT regexp_match('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}'); month int, day int ) date - + + Create date from year, month and day fields - + + make_date(2013, 7, 15) 2013-07-15 - + - + make_interval make_interval ( year int @@ -8208,17 +8902,19 @@ SELECT regexp_match('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}'); , sec double precision ) interval - + + Create interval from years, months, weeks, days, hours, minutes and seconds fields, each of which can default to zero - + + make_interval(days => 10) 10 days - + - + make_time @@ -8226,16 +8922,18 @@ SELECT regexp_match('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}'); min int, sec double precision ) time - + + Create time from hour, minute and seconds fields - + + make_time(8, 15, 23.5) 08:15:23.5 - + - + make_timestamp @@ -8246,16 +8944,18 @@ SELECT regexp_match('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}'); min int, sec double precision ) timestamp - + + Create timestamp from year, month, day, hour, minute and seconds fields - + + make_timestamp(2013, 7, 15, 8, 15, 23.5) 2013-07-15 08:15:23.5 - + - + make_timestamptz @@ -8267,95 +8967,107 @@ SELECT regexp_match('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}'); sec double precision , timezone text ) timestamp with time zone - + + Create timestamp with time zone from year, month, day, hour, minute and seconds fields; if timezone is not specified, the current time zone is used - + + make_timestamptz(2013, 7, 15, 8, 15, 23.5) 2013-07-15 08:15:23.5+01 - + - + now now ( ) timestamp with time zone - + + Current date and time (start of current transaction); see - + + now() 2019-12-23 14:39:53.662522-05 - + - + statement_timestamp statement_timestamp ( ) timestamp with time zone - + + Current date and time (start of current statement); see - + + statement_timestamp() 2019-12-23 14:39:53.662522-05 - + - + timeofday timeofday ( ) text - + + Current date and time (like clock_timestamp, but as a text string); see - + + timeofday() Mon Dec 23 14:39:53.662522 2019 EST - + - + transaction_timestamp transaction_timestamp ( ) timestamp with time zone - + + Current date and time (start of current transaction); see - + + transaction_timestamp() 2019-12-23 14:39:53.662522-05 - + - + to_timestamp to_timestamp ( double precision ) timestamp with time zone - + + Convert Unix epoch (seconds since 1970-01-01 00:00:00+00) to timestamp with time zone - + + to_timestamp(1284352323) 2010-09-13 04:32:03+00 - + @@ -9021,53 +9733,65 @@ SELECT date_trunc('hour', INTERVAL '3 days 02:47:33'); - - OperatorDescriptionExample(s) - + + Operator + + + Description + + + Example(s) + - + timestamp without time zone AT TIME ZONE zone timestamp with time zone - + + Converts given time stamp without time zone to time stamp with time zone, assuming the given value is in the named time zone. - + + timestamp '2001-02-16 20:38:40' at time zone 'America/Denver' 2001-02-17 03:38:40+00 - + - + timestamp with time zone AT TIME ZONE zone timestamp without time zone - + + Converts given time stamp with time zone to time stamp without time zone, as the time would appear in that zone. - + + timestamp with time zone '2001-02-16 20:38:40-05' at time zone 'America/Denver' 2001-02-16 18:38:40 - + - + time with time zone AT TIME ZONE zone time with time zone - + + Converts given time with time zone to a new time zone. Since no date is supplied, this uses the currently active UTC offset for the named destination zone. - + + time with time zone '05:34:17-05' at time zone 'UTC' 10:34:17+00 - + @@ -9348,76 +10072,92 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple - - FunctionDescriptionExample(s) - + + Function + + + Description + + + Example(s) + - + enum_first enum_first ( anyenum ) anyenum - + + Returns the first value of the input enum type. - + + enum_first(null::rainbow) red - + - + enum_last enum_last ( anyenum ) anyenum - + + Returns the last value of the input enum type. - + + enum_last(null::rainbow) purple - + - + enum_range enum_range ( anyenum ) anyarray - + + Returns all values of the input enum type in an ordered array. - + + enum_range(null::rainbow) {red,orange,yellow,&zwsp;green,blue,purple} - + - + enum_range ( anyenum, anyenum ) anyarray - + + Returns the range between the two given enum values, as an ordered array. The values must be from the same enum type. If the first parameter is null, the result will start with the first value of the enum type. If the second parameter is null, the result will end with the last value of the enum type. - + + enum_range('orange'::rainbow, 'green'::rainbow) {orange,yellow,green} - + + enum_range(NULL, 'green'::rainbow) {red,orange,&zwsp;yellow,green} - + + enum_range('orange'::rainbow, NULL) {orange,yellow,green,&zwsp;blue,purple} - + @@ -9451,60 +10191,73 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple - - OperatorDescriptionExample(s) - + + Operator + + + Description + + + Example(s) + - + geometric_type + point geometric_type - + + Adds the coordinates of the second point to those of each point of the first argument, thus performing translation. Available for point, box, path, circle. - + + box '(1,1),(0,0)' + point '(2,0)' (3,1),(2,0) - + - + path + path path - + + Concatenates two open paths (returns NULL if either path is closed). - + + path '[(0,0),(1,1)]' + path '[(2,2),(3,3),(4,4)]' [(0,0),(1,1),(2,2),(3,3),(4,4)] - + - + geometric_type - point geometric_type - + + Subtracts the coordinates of the second point from those of each point of the first argument, thus performing translation. Available for point, box, path, circle. - + + box '(1,1),(0,0)' - point '(2,0)' (-1,1),(-2,0) - + - + geometric_type * point geometric_type - + + Multiplies each point of the first argument by the second point (treating a point as being a complex number represented by real and imaginary parts, and performing standard @@ -9519,20 +10272,23 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple still considered to have sides parallel to the axes. Hence the box's size is not preserved, as a true rotation would do. path, circle. - + + path '((0,0),(1,0),(1,1))' * point '(3.0,0)' ((0,0),(3,0),(3,3)) - + + path '((0,0),(1,0),(1,1))' * point(cosd(45), sind(45)) ((0,0),&zwsp;(0.7071067811865475,0.7071067811865475),&zwsp;(0,1.414213562373095)) - + - + geometric_type / point geometric_type - + + Divides each point of the first argument by the second point (treating a point as being a complex number represented by real and imaginary parts, and performing standard @@ -9544,85 +10300,98 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple Available for point, box, path, circle. - + + path '((0,0),(1,0),(1,1))' / point '(2.0,0)' ((0,0),(0.5,0),(0.5,0.5)) - + + path '((0,0),(1,0),(1,1))' / point(cosd(45), sind(45)) ((0,0),&zwsp;(0.7071067811865476,-0.7071067811865476),&zwsp;(1.4142135623730951,0)) - + - + @-@ geometric_type double precision - + + Computes the total length. Available for lseg, path. - + + @-@ path '[(0,0),(1,0),(1,1)]' 2 - + - + @@ geometric_type point - + + Computes the center point. Available for box, lseg, path, polygon, circle. - + + @@ box '(2,2),(0,0)' (1,1) - + - + # geometric_type integer - + + Returns the number of points. Available for path, polygon. - + + # path '((1,0),(0,1),(-1,0))' 3 - + - + geometric_type # geometric_type point - + + Computes the point of intersection, or NULL if there is none. Available for lseg, line. - + + lseg '[(0,0),(1,1)]' # lseg '[(1,0),(0,1)]' (0.5,0.5) - + - + box # box box - + + Computes the intersection of two boxes, or NULL if there is none. - + + box '(2,2),(-1,-1)' # box '(1,1),(-2,-2)' (1,1),(-1,-1) - + - + geometric_type ## geometric_type point - + + Computes the closest point to the first object on the second object. Available for these pairs of types: (point, box), @@ -9633,17 +10402,19 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple (lseg, line), (line, box), (line, lseg). - + + point '(0,0)' ## lseg '[(2,0),(0,2)]' (1,1) - + - + geometric_type <-> geometric_type double precision - + + Computes the distance between the objects. Available for all seven geometric types, for all combinations of point with another geometric type, and for @@ -9653,17 +10424,19 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple (lseg, line), (polygon, circle) (and the commutator cases). - + + circle '<(0,0),1>' <-> circle '<(5,0),1>' 3 - + - + geometric_type @> geometric_type boolean - + + Does first object contain second? Available for these pairs of types: (box, point), @@ -9673,17 +10446,19 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple (polygon, polygon), (circle, point), (circle, circle). - + + circle '<(0,0),2>' @> point '(1,1)' t - + - + geometric_type <@ geometric_type boolean - + + Is first object contained in or on second? Available for these pairs of types: (point, box), @@ -9697,193 +10472,221 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple (lseg, line), (polygon, polygon), (circle, circle). - + + point '(1,1)' <@ circle '<(0,0),2>' t - + - + geometric_type && geometric_type boolean - + + Do these objects overlap? (One point in common makes this true.) Available for box, polygon, circle. - + + box '(1,1),(0,0)' && box '(2,2),(0,0)' t - + - + geometric_type << geometric_type boolean - + + Is first object strictly left of second? Available for point, box, polygon, circle. - + + circle '<(0,0),1>' << circle '<(5,0),1>' t - + - + geometric_type >> geometric_type boolean - + + Is first object strictly right of second? Available for point, box, polygon, circle. - + + circle '<(5,0),1>' >> circle '<(0,0),1>' t - + - + geometric_type &< geometric_type boolean - + + Does first object not extend to the right of second? Available for box, polygon, circle. - + + box '(1,1),(0,0)' &< box '(2,2),(0,0)' t - + - + geometric_type &> geometric_type boolean - + + Does first object not extend to the left of second? Available for box, polygon, circle. - + + box '(3,3),(0,0)' &> box '(2,2),(0,0)' t - + - + geometric_type <<| geometric_type boolean - + + Is first object strictly below second? Available for box, polygon, circle. - + + box '(3,3),(0,0)' <<| box '(5,5),(3,4)' t - + - + geometric_type |>> geometric_type boolean - + + Is first object strictly above second? Available for box, polygon, circle. - + + box '(5,5),(3,4)' |>> box '(3,3),(0,0)' t - + - + geometric_type &<| geometric_type boolean - + + Does first object not extend above second? Available for box, polygon, circle. - + + box '(1,1),(0,0)' &<| box '(2,2),(0,0)' t - + - + geometric_type |&> geometric_type boolean - + + Does first object not extend below second? Available for box, polygon, circle. - + + box '(3,3),(0,0)' |&> box '(2,2),(0,0)' t - + - + box <^ box boolean - + + Is first object below second (allows edges to touch)? - + + box '((1,1),(0,0))' <^ box '((2,2),(1,1))' t - + - + point <^ point boolean - + + Is first object strictly below second? (This operator is misnamed; it should be <<|.) - + + point '(1,0)' <^ point '(1,1)' t - + - + box >^ box boolean - + + Is first object above second (allows edges to touch)? - + + box '((2,2),(1,1))' >^ box '((1,1),(0,0))' t - + - + point >^ point boolean - + + Is first object strictly above second? (This operator is misnamed; it should be |>>.) - + + point '(1,1)' >^ point '(1,0)' t - + - + geometric_type ?# geometric_type boolean - + + Do these objects intersect? Available for these pairs of types: (box, box), @@ -9893,100 +10696,127 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple (line, box), (line, line), (path, path). - + + lseg '[(-1,0),(1,0)]' ?# box '(2,2),(-2,-2)' t - + - - ?- geometric_type + + ?- line boolean - + + + ?- lseg + boolean + + Is line horizontal? - Available for lseg, line. - + + ?- lseg '[(-1,0),(1,0)]' t - + - + point ?- point boolean - + + Are points horizontally aligned (that is, have same y coordinate)? - + + point '(1,0)' ?- point '(0,0)' t - + - - ?| geometric_type + + ?| line boolean - + + + ?| lseg + boolean + + Is line vertical? - Available for lseg, line. - + + ?| lseg '[(-1,0),(1,0)]' f - + - + point ?| point boolean - + + Are points vertically aligned (that is, have same x coordinate)? - + + point '(0,1)' ?| point '(0,0)' t - + - - geometric_type ?-| geometric_type + + line ?-| line boolean - + + + lseg ?-| lseg + boolean + + Are lines perpendicular? - Available for lseg, line. - + + lseg '[(0,0),(0,1)]' ?-| lseg '[(0,0),(1,0)]' t - + - - geometric_type ?|| geometric_type + + line ?|| line boolean - + + + lseg ?|| lseg + boolean + + Are lines parallel? - Available for lseg, line. - + + lseg '[(-1,0),(1,0)]' ?|| lseg '[(-1,2),(1,2)]' t - + - + geometric_type ~= geometric_type boolean - + + Are these objects the same? Available for point, box, polygon, circle. - + + polygon '((0,0),(1,1))' ~= polygon '((1,1),(0,0))' t - + @@ -10018,229 +10848,263 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple - - FunctionDescriptionExample(s) - + + Function + + + Description + + + Example(s) + - + area area ( geometric_type ) double precision - + + Computes area. Available for box, path, circle. A path input must be closed, else NULL is returned. Also, if the path is self-intersecting, the result may be meaningless. - + + area(box '(2,2),(0,0)') 4 - + - + center center ( geometric_type ) point - + + Computes center point. Available for box, circle. - + + center(box '(1,2),(0,0)') (0.5,1) - + - + diagonal diagonal ( box ) lseg - + + Extracts box's diagonal as a line segment (same as lseg(box)). - + + diagonal(box '(1,2),(0,0)') [(1,2),(0,0)] - + - + diameter diameter ( circle ) double precision - + + Computes diameter of circle. - + + diameter(circle '<(0,0),2>') 4 - + - + height height ( box ) double precision - + + Computes vertical size of box. - + + height(box '(1,2),(0,0)') 2 - + - + isclosed isclosed ( path ) boolean - + + Is path closed? - + + isclosed(path '((0,0),(1,1),(2,0))') t - + - + isopen isopen ( path ) boolean - + + Is path open? - + + isopen(path '[(0,0),(1,1),(2,0)]') t - + - + length length ( geometric_type ) double precision - + + Computes the total length. Available for lseg, path. - + + length(path '((-1,0),(1,0))') 4 - + - + npoints npoints ( geometric_type ) integer - + + Returns the number of points. Available for path, polygon. - + + npoints(path '[(0,0),(1,1),(2,0)]') 3 - + - + pclose pclose ( path ) path - + + Converts path to closed form. - + + pclose(path '[(0,0),(1,1),(2,0)]') ((0,0),(1,1),(2,0)) - + - + popen popen ( path ) path - + + Converts path to open form. - + + popen(path '((0,0),(1,1),(2,0))') [(0,0),(1,1),(2,0)] - + - + radius radius ( circle ) double precision - + + Computes radius of circle. - + + radius(circle '<(0,0),2>') 2 - + - + slope slope ( point, point ) double precision - + + Computes slope of a line drawn through the two points. - + + slope(point '(0,0)', point '(2,1)') 0.5 - + - + width width ( box ) double precision - + + Computes horizontal size of box. - + + width(box '(1,2),(0,0)') 1 - + @@ -10251,290 +11115,338 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple - - FunctionDescriptionExample(s) - + + Function + + + Description + + + Example(s) + - + box box ( circle ) box - + + Computes box inscribed within the circle. - + + box(circle '<(0,0),2>') (1.414213562373095,1.414213562373095),&zwsp;(-1.414213562373095,-1.414213562373095) - + - + box ( point ) box - + + Converts point to empty box. - + + box(point '(1,0)') (1,0),(1,0) - + - + box ( point, point ) box - + + Converts any two corner points to box. - + + box(point '(0,1)', point '(1,0)') (1,1),(0,0) - + - + box ( polygon ) box - + + Computes bounding box of polygon. - + + box(polygon '((0,0),(1,1),(2,0))') (2,1),(0,0) - + - + bound_box bound_box ( box, box ) box - + + Computes bounding box of two boxes. - + + bound_box(box '(1,1),(0,0)', box '(4,4),(3,3)') (4,4),(0,0) - + - + circle circle ( box ) circle - + + Computes smallest circle enclosing box. - + + circle(box '(1,1),(0,0)') <(0.5,0.5),0.7071067811865476> - + - + circle ( point, double precision ) circle - + + Constructs circle from center and radius. - + + circle(point '(0,0)', 2.0) <(0,0),2> - + - + circle ( polygon ) circle - + + Converts polygon to circle. The circle's center is the mean of the positions of the polygon's points, and the radius is the average distance of the polygon's points from that center. - + + circle(polygon '((0,0),(1,3),(2,0))') <(1,1),1.6094757082487299> - + - + line line ( point, point ) line - + + Converts two points to the line through them. - + + line(point '(-1,0)', point '(1,0)') {0,-1,0} - + - + lseg lseg ( box ) lseg - + + Extracts box's diagonal as a line segment. - + + lseg(box '(1,0),(-1,0)') [(1,0),(-1,0)] - + - + lseg ( point, point ) lseg - + + Constructs line segment from two endpoints. - + + lseg(point '(-1,0)', point '(1,0)') [(-1,0),(1,0)] - + - + path path ( polygon ) path - + + Converts polygon to a closed path with the same list of points. - + + path(polygon '((0,0),(1,1),(2,0))') ((0,0),(1,1),(2,0)) - + - + point point ( double precision, double precision ) point - + + Constructs point from its coordinates. - + + point(23.4, -44.5) (23.4,-44.5) - + - + point ( box ) point - + + Computes center of box. - + + point(box '(1,0),(-1,0)') (0,0) - + - + point ( circle ) point - + + Computes center of circle. - + + point(circle '<(0,0),2>') (0,0) - + - + point ( lseg ) point - + + Computes center of line segment. - + + point(lseg '[(-1,0),(1,0)]') (0,0) - + - + point ( polygon ) point - + + Computes center of polygon (the mean of the positions of the polygon's points). - + + point(polygon '((0,0),(1,1),(2,0))') (1,0.3333333333333333) - + - + polygon polygon ( box ) polygon - + + Converts box to a 4-point polygon. - + + polygon(box '(1,1),(0,0)') ((0,0),(0,1),(1,1),(1,0)) - + - + polygon ( circle ) polygon - + + Converts circle to a 12-point polygon. - + + polygon(circle '<(0,0),2>') ((-2,0),&zwsp;(-1.7320508075688774,0.9999999999999999),&zwsp;(-1.0000000000000002,1.7320508075688772),&zwsp;(-1.2246063538223773e-16,2),&zwsp;(0.9999999999999996,1.7320508075688774),&zwsp;(1.732050807568877,1.0000000000000007),&zwsp;(2,2.4492127076447545e-16),&zwsp;(1.7320508075688776,-0.9999999999999994),&zwsp;(1.0000000000000009,-1.7320508075688767),&zwsp;(3.673819061467132e-16,-2),&zwsp;(-0.9999999999999987,-1.732050807568878),&zwsp;(-1.7320508075688767,-1.0000000000000009)) - + - + polygon ( integer, circle ) polygon - + + Converts circle to an n-point polygon. - + + polygon(4, circle '<(3,0),1>') ((2,0),&zwsp;(3,1),&zwsp;(4,1.2246063538223773e-16),&zwsp;(3,-1)) - + - + polygon ( path ) polygon - + + Converts closed path to a polygon with the same list of points. - + + polygon(path '((0,0),(1,1),(2,0))') ((0,0),(1,1),(2,0)) - + @@ -10582,171 +11494,205 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple - - OperatorDescriptionExample(s) - + + Operator + + + Description + + + Example(s) + - + inet << inet boolean - + + Is subnet strictly contained by subnet? This operator, and the next four, test for subnet inclusion. They consider only the network parts of the two addresses (ignoring any bits to the right of the netmasks) and determine whether one network is identical to or a subnet of the other. - + + inet '192.168.1.5' << inet '192.168.1/24' t - + + inet '192.168.0.5' << inet '192.168.1/24' f - + + inet '192.168.1/24' << inet '192.168.1/24' f - + - + inet <<= inet boolean - + + Is subnet contained by or equal to subnet? - + + inet '192.168.1/24' <<= inet '192.168.1/24' t - + - + inet >> inet boolean - + + Does subnet strictly contain subnet? - + + inet '192.168.1/24' >> inet '192.168.1.5' t - + - + inet >>= inet boolean - + + Does subnet contain or equal subnet? - + + inet '192.168.1/24' >>= inet '192.168.1/24' t - + - + inet && inet boolean - + + Does either subnet contain or equal the other? - + + inet '192.168.1/24' && inet '192.168.1.80/28' t - + + inet '192.168.1/24' && inet '192.168.2.0/28' f - + - + ~ inet inet - + + Computes bitwise NOT. - + + ~ inet '192.168.1.6' 63.87.254.249 - + - + inet & inet inet - + + Computes bitwise AND. - + + inet '192.168.1.6' & inet '0.0.0.255' 0.0.0.6 - + - + inet | inet inet - + + Computes bitwise OR. - + + inet '192.168.1.6' | inet '0.0.0.255' 192.168.1.255 - + - + inet + bigint inet - + + Adds an offset to an address. - + + inet '192.168.1.6' + 25 192.168.1.31 - + - + bigint + inet inet - + + Adds an offset to an address. - + + 200 + inet '::ffff:fff0:1' ::ffff:255.240.0.201 - + - + inet - bigint inet - + + Subtracts an offset from an address. - + + inet '192.168.1.43' - 36 192.168.1.7 - + - + inet - inet bigint - + + Computes the difference of two addresses. - + + inet '192.168.1.43' - inet '192.168.1.19' 24 - + + inet '::1' - inet '::ffff:1' -4294901760 - + @@ -10757,228 +11703,262 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple - - FunctionDescriptionExample(s) - + + Function + + + Description + + + Example(s) + - + abbrev abbrev ( inet ) text - + + Creates an abbreviated display format as text. (The result is the same as the inet output function produces; it is abbreviated only in comparison to the result of an explicit cast to text, which for historical reasons will never suppress the netmask part.) - + + abbrev(inet '10.1.0.0/32') 10.1.0.0 - + - + abbrev ( cidr ) text - + + Creates an abbreviated display format as text. (The abbreviation consists of dropping all-zero octets to the right of the netmask; more examples are in .) - + + abbrev(cidr '10.1.0.0/16') 10.1/16 - + - + broadcast broadcast ( inet ) inet - + + Computes the broadcast address for the address's network. - + + broadcast(inet '192.168.1.5/24') 192.168.1.255/24 - + - + family family ( inet ) integer - + + Returns the address's family: 4 for IPv4, 6 for IPv6. - + + family(inet '::1') 6 - + - + host host ( inet ) text - + + Returns the IP address as text, ignoring the netmask. - + + host(inet '192.168.1.0/24') 192.168.1.0 - + - + hostmask hostmask ( inet ) inet - + + Computes the host mask for the address's network. - + + hostmask(inet '192.168.23.20/30') 0.0.0.3 - + - + inet_merge inet_merge ( inet, inet ) cidr - + + Computes the smallest network that includes both of the given networks. - + + inet_merge(inet '192.168.1.5/24', inet '192.168.2.5/24') 192.168.0.0/22 - + - + inet_same_family inet_same_family ( inet, inet ) boolean - + + Tests whether the addresses belong to the same IP family. - + + inet_same_family(inet '192.168.1.5/24', inet '::1') f - + - + masklen masklen ( inet ) integer - + + Returns the netmask length in bits. - + + masklen(inet '192.168.1.5/24') 24 - + - + netmask netmask ( inet ) inet - + + Computes the network mask for the address's network. - + + netmask(inet '192.168.1.5/24') 255.255.255.0 - + - + network network ( inet ) cidr - + + Returns the network part of the address, zeroing out whatever is to the right of the netmask. (This is equivalent to casting the value to cidr.) - + + network(inet '192.168.1.5/24') 192.168.1.0/24 - + - + set_masklen set_masklen ( inet, integer ) inet - + + Sets the netmask length for an inet value. The address part does not change. - + + set_masklen(inet '192.168.1.5/24', 16) 192.168.1.5/16 - + - + set_masklen ( cidr, integer ) cidr - + + Sets the netmask length for a cidr value. Address bits to the right of the new netmask are set to zero. - + + set_masklen(cidr '192.168.1.0/24', 16) 192.168.0.0/16 - + - + text text ( inet ) text - + + Returns the unabbreviated IP address and netmask length as text. (This has the same result as an explicit cast to text.) - + + text(inet '192.168.1.5') 192.168.1.5/32 - + @@ -11008,58 +11988,70 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple - - FunctionDescriptionExample(s) - + + Function + + + Description + + + Example(s) + - + trunc trunc ( macaddr ) macaddr - + + Sets the last 3 bytes of the address to zero. The remaining prefix can be associated with a particular manufacturer (using data not included in PostgreSQL). - + + trunc(macaddr '12:34:56:78:90:ab') 12:34:56:00:00:00 - + - + trunc ( macaddr8 ) macaddr8 - + + Sets the last 5 bytes of the address to zero. The remaining prefix can be associated with a particular manufacturer (using data not included in PostgreSQL). - + + trunc(macaddr8 '12:34:56:78:90:ab:cd:ef') 12:34:56:00:00:00:00:00 - + - + macaddr8_set7bit macaddr8_set7bit ( macaddr8 ) macaddr8 - + + Sets the 7th bit of the address to one, creating what is known as modified EUI-64, for inclusion in an IPv6 address. - + + macaddr8_set7bit(macaddr8 '00:34:56:ab:cd:ef') 02:34:56:ff:fe:ab:cd:ef - + @@ -11096,149 +12088,181 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple - - OperatorDescriptionExample(s) - + + Operator + + + Description + + + Example(s) + - + tsvector @@ tsquery - or + boolean + + tsquery @@ tsvector boolean - + + Does tsvector match tsquery? - + (The arguments can be given in either order.) + + to_tsvector('fat cats ate rats') @@ to_tsquery('cat & rat') t - + - + text @@ tsquery boolean - + + Does text string, after implicit invocation of to_tsvector(), match tsquery? - + + 'fat cats ate rats' @@ to_tsquery('cat & rat') t - + - + tsvector @@@ tsquery - or + boolean + + tsquery @@@ tsvector boolean - + + This is a deprecated synonym for @@. - + + to_tsvector('fat cats ate rats') @@@ to_tsquery('cat & rat') t - + - + tsvector || tsvector tsvector - + + Concatenates two tsvectors. If both inputs contain lexeme positions, the second input's positions are adjusted accordingly. - + + 'a:1 b:2'::tsvector || 'c:1 d:2 b:3'::tsvector 'a':1 'b':2,5 'c':3 'd':4 - + - + tsquery && tsquery tsquery - + + ANDs two tsquerys together, producing a query that matches documents that match both input queries. - + + 'fat | rat'::tsquery && 'cat'::tsquery ( 'fat' | 'rat' ) & 'cat' - + - + tsquery || tsquery tsquery - + + ORs two tsquerys together, producing a query that matches documents that match either input query. - + + 'fat | rat'::tsquery || 'cat'::tsquery 'fat' | 'rat' | 'cat' - + - + !! tsquery tsquery - + + Negates a tsquery, producing a query that matches documents that do not match the input query. - + + !! 'cat'::tsquery !'cat' - + - + tsquery <-> tsquery tsquery - + + Constructs a phrase query, which matches if the two input queries match at successive lexemes. - + + to_tsquery('fat') <-> to_tsquery('rat') 'fat' <-> 'rat' - + - + tsquery @> tsquery boolean - + + Does first tsquery contain the second? (This considers only whether all the lexemes appearing in one query appear in the other, ignoring the combining operators.) - + + 'cat'::tsquery @> 'cat & rat'::tsquery f - + - + tsquery <@ tsquery boolean - + + Is first tsquery contained in the second? (This considers only whether all the lexemes appearing in one query appear in the other, ignoring the combining operators.) - + + 'cat'::tsquery <@ 'cat & rat'::tsquery t - + + 'cat'::tsquery <@ '!cat & rat'::tsquery t - + @@ -11258,78 +12282,92 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple - - FunctionDescriptionExample(s) - + + Function + + + Description + + + Example(s) + - + array_to_tsvector array_to_tsvector ( text[] ) tsvector - + + Converts an array of lexemes to a tsvector. The given strings are used as-is without further processing. - + + array_to_tsvector('{fat,cat,rat}'::text[]) 'cat' 'fat' 'rat' - + - + get_current_ts_config get_current_ts_config ( ) regconfig - + + Returns the OID of the current default text search configuration (as set by ). - + + get_current_ts_config() english - + - + length length ( tsvector ) integer - + + Returns the number of lexemes in the tsvector. - + + length('fat:2,4 cat:3 rat:5A'::tsvector) 3 - + - + numnode numnode ( tsquery ) integer - + + Returns the number of lexemes plus operators in the tsquery. - + + numnode('(fat & rat) | cat'::tsquery) 5 - + - + plainto_tsquery @@ -11337,19 +12375,21 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple config regconfig, query text ) tsquery - + + Converts text to a tsquery, normalizing words according to the specified or default configuration. Any punctuation in the string is ignored (it does not determine query operators). The resulting query matches documents containing all non-stopwords in the text. - + + plainto_tsquery('english', 'The Fat Rats') 'fat' & 'rat' - + - + phraseto_tsquery @@ -11357,22 +12397,25 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple config regconfig, query text ) tsquery - + + Converts text to a tsquery, normalizing words according to the specified or default configuration. Any punctuation in the string is ignored (it does not determine query operators). The resulting query matches phrases containing all non-stopwords in the text. - + + phraseto_tsquery('english', 'The Fat Rats') 'fat' <-> 'rat' - + + phraseto_tsquery('english', 'The Cat and Rats') 'cat' <2> 'rat' - + - + websearch_to_tsquery @@ -11380,87 +12423,97 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple config regconfig, query text ) tsquery - + + Converts text to a tsquery, normalizing words according to the specified or default configuration. Quoted word sequences are converted to phrase tests. The word or is understood as producing an OR operator, and a dash produces a NOT operator; other punctuation is ignored. This approximates the behavior of some common web search tools. - + + websearch_to_tsquery('english', '"fat rat" or cat dog') 'fat' <-> 'rat' | 'cat' & 'dog' - + - + querytree querytree ( tsquery ) text - + + Produces a representation of the indexable portion of a tsquery. A result that is empty or just T indicates a non-indexable query. - + + querytree('foo & ! bar'::tsquery) 'foo' - + - + setweight setweight ( vector tsvector, weight "char" ) tsvector - + + Assigns the specified weight to each element of the vector. - + + setweight('fat:2,4 cat:3 rat:5B'::tsvector, 'A') 'cat':3A 'fat':2A,4A 'rat':5A - + - + setweight setweight for specific lexeme(s) setweight ( vector tsvector, weight "char", lexemes text[] ) tsvector - + + Assigns the specified weight to elements of the vector that are listed in lexemes. - + + setweight('fat:2,4 cat:3 rat:5,6B'::tsvector, 'A', '{cat,rat}') 'cat':3A 'fat':2,4 'rat':5A,6A - + - + strip strip ( tsvector ) tsvector - + + Removes positions and weights from the tsvector. - + + strip('fat:2,4 cat:3 rat:5A'::tsvector) 'cat' 'fat' 'rat' - + - + to_tsquery @@ -11468,18 +12521,20 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple config regconfig, query text ) tsquery - + + Converts text to a tsquery, normalizing words according to the specified or default configuration. The words must be combined by valid tsquery operators. - + + to_tsquery('english', 'The & Fat & Rats') 'fat' & 'rat' - + - + to_tsvector @@ -11487,23 +12542,32 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple config regconfig, document text ) tsvector - + + Converts text to a tsvector, normalizing words according to the specified or default configuration. Position information is included in the result. - + + to_tsvector('english', 'The Fat Rats') 'fat':2 'rat':3 - + - + to_tsvector ( config regconfig, - document json(b) ) + document json ) tsvector - + + + to_tsvector ( + config regconfig, + document jsonb ) + tsvector + + Converts each string value in the JSON document to a tsvector, normalizing words according to the specified or default configuration. The results are then concatenated in @@ -11512,26 +12576,39 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple values. (Beware that document order of the fields of a JSON object is implementation-dependent when the input is jsonb; observe the difference in the examples.) - + + to_tsvector('english', '{"aa": "The Fat Rats", "b": "dog"}'::json) 'dog':5 'fat':2 'rat':3 - + + to_tsvector('english', '{"aa": "The Fat Rats", "b": "dog"}'::jsonb) 'dog':1 'fat':4 'rat':5 - + - + - json(b)_to_tsvector + json_to_tsvector - json(b)_to_tsvector ( + json_to_tsvector ( config regconfig, - document json(b), + document json, filter jsonb ) tsvector - + + + + jsonb_to_tsvector + + jsonb_to_tsvector ( + config regconfig, + document jsonb, + filter jsonb ) + tsvector + + Selects each item in the JSON document that is requested by the filter and converts each one to a tsvector, normalizing words according to the specified @@ -11550,63 +12627,71 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple "all" (to include all the above). As a special case, the filter can also be a simple JSON value that is one of these keywords. - + + json_to_tsvector('english', '{"a": "The Fat Rats", "b": 123}'::json, '["string", "numeric"]') '123':5 'fat':2 'rat':3 - + + json_to_tsvector('english', '{"cat": "The Fat Rats", "dog": 123}'::json, '"all"') '123':9 'cat':1 'dog':7 'fat':4 'rat':5 - + - + ts_delete ts_delete ( vector tsvector, lexeme text ) tsvector - + + Removes any occurrence of the given lexeme from the vector. - + + ts_delete('fat:2,4 cat:3 rat:5A'::tsvector, 'fat') 'cat':3 'rat':5A - + - + ts_delete ( vector tsvector, lexemes text[] ) tsvector - + + Removes any occurrences of the lexemes in lexemes from the vector. - + + ts_delete('fat:2,4 cat:3 rat:5A'::tsvector, ARRAY['fat','rat']) 'cat':3 - + - + ts_filter ts_filter ( vector tsvector, weights "char"[] ) tsvector - + + Selects only elements with the given weights from the vector. - + + ts_filter('fat:2,4 cat:3b,7c rat:5A'::tsvector, '{a,b}') 'cat':3B 'rat':5A - + - + ts_headline @@ -11616,7 +12701,8 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple query tsquery , options text ) text - + + Displays, in an abbreviated form, the match(es) for the query in the document, which must be raw text not @@ -11625,33 +12711,44 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple the query. Use of this function is discussed in , which also describes the available options. - + + ts_headline('The fat cat ate the rat.', 'cat') The fat <b>cat</b> ate the rat. - + - + ts_headline ( config regconfig, - document json(b), + document json, query tsquery , options text ) text - + + + ts_headline ( + config regconfig, + document jsonb, + query tsquery + , options text ) + text + + Displays, in an abbreviated form, match(es) for the query that occur in string values within the JSON document. See for more details. - + + ts_headline('{"cat":"raining cats and dogs"}'::jsonb, 'cat') {"cat": "raining <b>cats</b> and dogs"} - + - + ts_rank @@ -11661,19 +12758,21 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple query tsquery , normalization integer ) real - + + Computes a score showing how well the vector matches the query. See for details. - + + ts_rank(to_tsvector('raining cats and dogs'), 'cat') 0.06079271 - + - + ts_rank_cd @@ -11683,19 +12782,21 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple query tsquery , normalization integer ) real - + + Computes a score showing how well the vector matches the query, using a cover density algorithm. See for details. - + + ts_rank_cd(to_tsvector('raining cats and dogs'), 'cat') 0.1 - + - + ts_rewrite @@ -11703,83 +12804,93 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple target tsquery, substitute tsquery ) tsquery - + + Replaces occurrences of target with substitute within the query. See for details. - + + ts_rewrite('a & b'::tsquery, 'a'::tsquery, 'foo|bar'::tsquery) 'b' & ( 'foo' | 'bar' ) - + - + ts_rewrite ( query tsquery, select text ) tsquery - + + Replaces portions of the query according to target(s) and substitute(s) obtained by executing a SELECT command. See for details. - + + SELECT ts_rewrite('a & b'::tsquery, 'SELECT t,s FROM aliases') 'b' & ( 'foo' | 'bar' ) - + - + tsquery_phrase tsquery_phrase ( query1 tsquery, query2 tsquery ) tsquery - + + Constructs a phrase query that searches for matches of query1 and query2 at successive lexemes (same as <-> operator). - + + tsquery_phrase(to_tsquery('fat'), to_tsquery('cat')) 'fat' <-> 'cat' - + - + tsquery_phrase ( query1 tsquery, query2 tsquery, distance integer ) tsquery - + + Constructs a phrase query that searches for matches of query1 and query2 that occur exactly distance lexemes apart. - + + tsquery_phrase(to_tsquery('fat'), to_tsquery('cat'), 10) 'fat' <10> 'cat' - + - + tsvector_to_array tsvector_to_array ( tsvector ) text[] - + + Converts a tsvector to an array of lexemes. - + + tsvector_to_array('fat:2,4 cat:3 rat:5A'::tsvector) {cat,fat,rat} - + - + unnest for tsvector @@ -11789,12 +12900,21 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple OUT positions smallint[], OUT weights text ) setof record - + + Expands a tsvector into a set of rows, one per lexeme. - - unnest('cat:3 fat:2,4 rat:5A'::tsvector) - (cat,{3},{D})(fat,"{2,4}","{D,D}")(rat,{5},{A})(3 rows in result) - + + + select * from unnest('cat:3 fat:2,4 rat:5A'::tsvector) + + + lexeme | positions | weights +--------+-----------+--------- + cat | {3} | {D} + fat | {2,4} | {D,D} + rat | {5} | {A} + + @@ -11822,15 +12942,21 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple - - FunctionDescriptionExample(s) - + + Function + + + Description + + + Example(s) + - + ts_debug @@ -11844,38 +12970,42 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple OUT dictionary regdictionary, OUT lexemes text[] ) setof record - + + Extracts and normalizes tokens from the document according to the specified or default text search configuration, and returns information about how each token was processed. See for details. - + + ts_debug('english', 'The Brightest supernovaes') (asciiword,"Word, all ASCII",The,{english_stem},english_stem,{}) ... - + - + ts_lexize ts_lexize ( dict regdictionary, token text ) text[] - + + Returns an array of replacement lexemes if the input token is known to the dictionary, or an empty array if the token is known to the dictionary but it is a stop word, or NULL if it is not a known word. See for details. - + + ts_lexize('english_stem', 'stars') {star} - + - + ts_parse @@ -11884,35 +13014,39 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple OUT tokid integer, OUT token text ) setof record - + + Extracts tokens from the document using the named parser. See for details. - + + ts_parse('default', 'foo - bar') (1,foo) ... - + - + ts_parse ( parser_oid oid, document text, OUT tokid integer, OUT token text ) setof record - + + Extracts tokens from the document using a parser specified by OID. See for details. - + + ts_parse(3722, 'foo - bar') (1,foo) ... - + - + ts_token_type @@ -11921,35 +13055,39 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple OUT alias text, OUT description text ) setof record - + + Returns a table that describes each type of token the named parser can recognize. See for details. - + + ts_token_type('default') (1,asciiword,"Word, all ASCII") ... - + - + ts_token_type ( parser_oid oid, OUT tokid integer, OUT alias text, OUT description text ) setof record - + + Returns a table that describes each type of token a parser specified by OID can recognize. See for details. - + + ts_token_type(3722) (1,asciiword,"Word, all ASCII") ... - + - + ts_stat @@ -11959,15 +13097,17 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple OUT ndoc integer, OUT nentry integer ) setof record - + + Executes the sqlquery, which must return a single tsvector column, and returns statistics about each distinct lexeme contained in the data. See for details. - + + ts_stat('SELECT vector FROM apod') (foo,10,15) ... - + @@ -24034,59 +25174,71 @@ SELECT (pg_stat_file('filename')).modification; - - FunctionDescriptionExample Usage - + + Function + + + Description + + + Example Usage + - + suppress_redundant_updates_trigger suppress_redundant_updates_trigger ( ) trigger - + + Suppresses do-nothing update operations. See below for details. - + + CREATE TRIGGER ... suppress_redundant_updates_trigger() - + - + tsvector_update_trigger tsvector_update_trigger ( ) trigger - + + Automatically updates a tsvector column from associated plain-text document column(s). The text search configuration to use is specified by name as a trigger argument. See for details. - + + CREATE TRIGGER ... tsvector_update_trigger(tsvcol, 'pg_catalog.swedish', title, body) - + - + tsvector_update_trigger_column tsvector_update_trigger_column ( ) trigger - + + Automatically updates a tsvector column from associated plain-text document column(s). The text search configuration to use is taken from a regconfig column of the table. See for details. - + + CREATE TRIGGER ... tsvector_update_trigger_column(tsvcol, tsconfigcol, title, body) - + diff --git a/doc/src/sgml/stylesheet-common.xsl b/doc/src/sgml/stylesheet-common.xsl index b772f876c1..761484c7fe 100644 --- a/doc/src/sgml/stylesheet-common.xsl +++ b/doc/src/sgml/stylesheet-common.xsl @@ -101,11 +101,4 @@ - - - - -
- - diff --git a/doc/src/sgml/stylesheet-fo.xsl b/doc/src/sgml/stylesheet-fo.xsl index 2f2517d8ce..fe2a06a26a 100644 --- a/doc/src/sgml/stylesheet-fo.xsl +++ b/doc/src/sgml/stylesheet-fo.xsl @@ -63,30 +63,14 @@ - - - - - - bold - - - - bold - - - - - - - 4em + + + + -3.5em - left - - + + + @@ -96,11 +80,6 @@ - - - - - diff --git a/doc/src/sgml/stylesheet.css b/doc/src/sgml/stylesheet.css index f369e12a3c..11f88cc0be 100644 --- a/doc/src/sgml/stylesheet.css +++ b/doc/src/sgml/stylesheet.css @@ -78,13 +78,24 @@ div.example { /* formatting for entries in tables of functions: indent all but first line */ -th.functableentry, -td.functableentry { +th.func_table_entry p, +td.func_table_entry p { + margin-top: 0.1em; + margin-bottom: 0.1em; padding-left: 4em; - text-indent: -3.5em; text-align: left; } +p.func_signature { + text-indent: -3.5em; +} + +td.func_table_entry pre.programlisting { + margin-top: 0.1em; + margin-bottom: 0.1em; + padding-left: 4em; +} + /* Put these here instead of inside the HTML (see unsetting of admon.style in XSL) so that the web site stylesheet can set its own style. */