Thread: (b)trim anomalies
I was just wondering why the btrim syntax that takes only a single
argument is not documented in 9.4 in the documentation (I checked both
7.4 and 8.0 docs).
This is in a 7.4.5 installation:
pg=# \df btrim
List of functions
Result data type | Schema | Name | Argument data types
------------------+------------+-------+---------------------
bytea | pg_catalog | btrim | bytea, bytea
text | pg_catalog | btrim | text
text | pg_catalog | btrim | text, text
(3 rows)
Is it ever documented anywhere that the single-argument version of
btrim can be used to remove whitespace from the left and right of a
given string? Is this version not supposed to be user-facing for some
reason?
Also, in this post:
http://archives.postgresql.org/pgsql-sql/2002-01/msg00053.php
Bruce sort of explains that TRIM is an ANSI word but doesn't fully
explain why it doesn't show up in a \df listing:
pg=# \df trim
List of functions
Result data type | Schema | Name | Argument data types
------------------+--------+------+---------------------
(0 rows)
This one's more a curiosity thing.
-tfo
--
Thomas F. O'Connell
Co-Founder, Information Architect
Sitening, LLC
http://www.sitening.com/
110 30th Avenue North, Suite 6
Nashville, TN 37203-6320
615-260-0005
Thomas F.O'Connell wrote: > I was just wondering why the btrim syntax that takes only a single > argument is not documented in 9.4 in the documentation (I checked both > 7.4 and 8.0 docs). > > This is in a 7.4.5 installation: > > pg=# \df btrim > List of functions > Result data type | Schema | Name | Argument data types > ------------------+------------+-------+--------------------- > bytea | pg_catalog | btrim | bytea, bytea > text | pg_catalog | btrim | text > text | pg_catalog | btrim | text, text > (3 rows) > > Is it ever documented anywhere that the single-argument version of > btrim can be used to remove whitespace from the left and right of a > given string? Is this version not supposed to be user-facing for some > reason? > > Also, in this post: > > http://archives.postgresql.org/pgsql-sql/2002-01/msg00053.php > > Bruce sort of explains that TRIM is an ANSI word but doesn't fully > explain why it doesn't show up in a \df listing: > > pg=# \df trim > List of functions > Result data type | Schema | Name | Argument data types > ------------------+--------+------+--------------------- > (0 rows) > > This one's more a curiosity thing. Because TRIM is an ANSI standard, we document TRIM (BOTH, ...) but not btrim. The parser does the translation: | TRIM '(' BOTH trim_list ')' { /* various trim expressions are defined in SQL92 * - thomas 1997-07-19 */ FuncCall *n = makeNode(FuncCall); n->funcname = SystemFuncName("btrim"); n->args = $4; n->agg_star = FALSE; n->agg_distinct = FALSE; $$ = (Node *)n; Does that answer your questions? -- Bruce Momjian | http://candle.pha.pa.us pgman@candle.pha.pa.us | (610) 359-1001 + If your life is a hard drive, | 13 Roberts Road + Christ can be your backup. | Newtown Square, Pennsylvania 19073
Not entirely. Per <http://www.postgresql.org/docs/7.4/static/functions-string.html>, btrim is documented as taking two arguments. There is a single-argument version that exists that trims whitespace if only the first argument is given (i.e., the characters to trim are omitted). This latter version is nowhere documented as far as I can tell. I'm also curious why, despite its place in the ANSI standard, \df seems to reveal no information about trim. -tfo -- Thomas F. O'Connell Co-Founder, Information Architect Sitening, LLC http://www.sitening.com/ 110 30th Avenue North, Suite 6 Nashville, TN 37203-6320 615-260-0005 On Nov 27, 2004, at 9:23 PM, Bruce Momjian wrote: > Thomas F.O'Connell wrote: >> I was just wondering why the btrim syntax that takes only a single >> argument is not documented in 9.4 in the documentation (I checked both >> 7.4 and 8.0 docs). >> >> This is in a 7.4.5 installation: >> >> pg=# \df btrim >> List of functions >> Result data type | Schema | Name | Argument data types >> ------------------+------------+-------+--------------------- >> bytea | pg_catalog | btrim | bytea, bytea >> text | pg_catalog | btrim | text >> text | pg_catalog | btrim | text, text >> (3 rows) >> >> Is it ever documented anywhere that the single-argument version of >> btrim can be used to remove whitespace from the left and right of a >> given string? Is this version not supposed to be user-facing for some >> reason? >> >> Also, in this post: >> >> http://archives.postgresql.org/pgsql-sql/2002-01/msg00053.php >> >> Bruce sort of explains that TRIM is an ANSI word but doesn't fully >> explain why it doesn't show up in a \df listing: >> >> pg=# \df trim >> List of functions >> Result data type | Schema | Name | Argument data types >> ------------------+--------+------+--------------------- >> (0 rows) >> >> This one's more a curiosity thing. > > Because TRIM is an ANSI standard, we document TRIM (BOTH, ...) but not > btrim. The parser does the translation: > > | TRIM '(' BOTH trim_list ')' > { > /* various trim expressions are defined in SQL92 > * - thomas 1997-07-19 > */ > FuncCall *n = makeNode(FuncCall); > n->funcname = SystemFuncName("btrim"); > n->args = $4; > n->agg_star = FALSE; > n->agg_distinct = FALSE; > $$ = (Node *)n; > > Does that answer your questions? > > -- > Bruce Momjian | http://candle.pha.pa.us > pgman@candle.pha.pa.us | (610) 359-1001 > + If your life is a hard drive, | 13 Roberts Road > + Christ can be your backup. | Newtown Square, Pennsylvania > 19073
OK, I have documented that the second parameter to btrim() is optional, and default to a space. Patch attached and applied. --------------------------------------------------------------------------- Thomas F. O'Connell wrote: > Not entirely. > > Per <http://www.postgresql.org/docs/7.4/static/functions-string.html>, > btrim is documented as taking two arguments. There is a single-argument > version that exists that trims whitespace if only the first argument is > given (i.e., the characters to trim are omitted). This latter version > is nowhere documented as far as I can tell. > > I'm also curious why, despite its place in the ANSI standard, \df seems > to reveal no information about trim. > > -tfo > > -- > Thomas F. O'Connell > Co-Founder, Information Architect > Sitening, LLC > http://www.sitening.com/ > 110 30th Avenue North, Suite 6 > Nashville, TN 37203-6320 > 615-260-0005 > > On Nov 27, 2004, at 9:23 PM, Bruce Momjian wrote: > > > Thomas F.O'Connell wrote: > >> I was just wondering why the btrim syntax that takes only a single > >> argument is not documented in 9.4 in the documentation (I checked both > >> 7.4 and 8.0 docs). > >> > >> This is in a 7.4.5 installation: > >> > >> pg=# \df btrim > >> List of functions > >> Result data type | Schema | Name | Argument data types > >> ------------------+------------+-------+--------------------- > >> bytea | pg_catalog | btrim | bytea, bytea > >> text | pg_catalog | btrim | text > >> text | pg_catalog | btrim | text, text > >> (3 rows) > >> > >> Is it ever documented anywhere that the single-argument version of > >> btrim can be used to remove whitespace from the left and right of a > >> given string? Is this version not supposed to be user-facing for some > >> reason? > >> > >> Also, in this post: > >> > >> http://archives.postgresql.org/pgsql-sql/2002-01/msg00053.php > >> > >> Bruce sort of explains that TRIM is an ANSI word but doesn't fully > >> explain why it doesn't show up in a \df listing: > >> > >> pg=# \df trim > >> List of functions > >> Result data type | Schema | Name | Argument data types > >> ------------------+--------+------+--------------------- > >> (0 rows) > >> > >> This one's more a curiosity thing. > > > > Because TRIM is an ANSI standard, we document TRIM (BOTH, ...) but not > > btrim. The parser does the translation: > > > > | TRIM '(' BOTH trim_list ')' > > { > > /* various trim expressions are defined in SQL92 > > * - thomas 1997-07-19 > > */ > > FuncCall *n = makeNode(FuncCall); > > n->funcname = SystemFuncName("btrim"); > > n->args = $4; > > n->agg_star = FALSE; > > n->agg_distinct = FALSE; > > $$ = (Node *)n; > > > > Does that answer your questions? > > > > -- > > Bruce Momjian | http://candle.pha.pa.us > > pgman@candle.pha.pa.us | (610) 359-1001 > > + If your life is a hard drive, | 13 Roberts Road > > + Christ can be your backup. | Newtown Square, Pennsylvania > > 19073 > -- Bruce Momjian | http://candle.pha.pa.us pgman@candle.pha.pa.us | (610) 359-1001 + If your life is a hard drive, | 13 Roberts Road + Christ can be your backup. | Newtown Square, Pennsylvania 19073 Index: doc/src/sgml/func.sgml =================================================================== RCS file: /cvsroot/pgsql/doc/src/sgml/func.sgml,v retrieving revision 1.225 diff -c -c -r1.225 func.sgml *** doc/src/sgml/func.sgml 1 Dec 2004 19:32:12 -0000 1.225 --- doc/src/sgml/func.sgml 2 Dec 2004 17:12:57 -0000 *************** *** 1070,1081 **** </row> <row> ! <entry><literal><function>btrim</function>(<parameter>string</parameter> <type>text</type>, <parameter>characters</parameter><type>text</type>)</literal></entry> <entry><type>text</type></entry> <entry> Remove the longest string consisting only of characters ! in <parameter>characters</parameter> from the start and end of ! <parameter>string</parameter>. </entry> <entry><literal>btrim('xyxtrimyyx', 'xy')</literal></entry> <entry><literal>trim</literal></entry> --- 1070,1082 ---- </row> <row> ! <entry><literal><function>btrim</function>(<parameter>string</parameter> <type>text</type> ! <optional>, <parameter>characters</parameter> <type>text</type></optional>)</literal></entry> <entry><type>text</type></entry> <entry> Remove the longest string consisting only of characters ! in <parameter>characters</parameter> (or spaces if not supplied) ! from the start and end of <parameter>string</parameter>. </entry> <entry><literal>btrim('xyxtrimyyx', 'xy')</literal></entry> <entry><literal>trim</literal></entry>
Nice. Thanks, Bruce. If I felt as if I could speak a little more authoritatively about why it had been missing, I would've offered to document it. Now it is a psql/postgres internals issue that causes \df trim not to reveal anything? -tfo -- Thomas F. O'Connell Co-Founder, Information Architect Sitening, LLC http://www.sitening.com/ 110 30th Avenue North, Suite 6 Nashville, TN 37203-6320 615-260-0005 On Dec 2, 2004, at 11:14 AM, Bruce Momjian wrote: > OK, I have documented that the second parameter to btrim() is optional, > and default to a space. Patch attached and applied. > > ----------------------------------------------------------------------- > ---- > > Thomas F. O'Connell wrote: >> Not entirely. >> >> Per <http://www.postgresql.org/docs/7.4/static/functions-string.html>, >> btrim is documented as taking two arguments. There is a >> single-argument >> version that exists that trims whitespace if only the first argument >> is >> given (i.e., the characters to trim are omitted). This latter version >> is nowhere documented as far as I can tell. >> >> I'm also curious why, despite its place in the ANSI standard, \df >> seems >> to reveal no information about trim. >> >> -tfo >> >> -- >> Thomas F. O'Connell >> Co-Founder, Information Architect >> Sitening, LLC >> http://www.sitening.com/ >> 110 30th Avenue North, Suite 6 >> Nashville, TN 37203-6320 >> 615-260-0005 >> >> On Nov 27, 2004, at 9:23 PM, Bruce Momjian wrote: >> >>> Thomas F.O'Connell wrote: >>>> I was just wondering why the btrim syntax that takes only a single >>>> argument is not documented in 9.4 in the documentation (I checked >>>> both >>>> 7.4 and 8.0 docs). >>>> >>>> This is in a 7.4.5 installation: >>>> >>>> pg=# \df btrim >>>> List of functions >>>> Result data type | Schema | Name | Argument data types >>>> ------------------+------------+-------+--------------------- >>>> bytea | pg_catalog | btrim | bytea, bytea >>>> text | pg_catalog | btrim | text >>>> text | pg_catalog | btrim | text, text >>>> (3 rows) >>>> >>>> Is it ever documented anywhere that the single-argument version of >>>> btrim can be used to remove whitespace from the left and right of a >>>> given string? Is this version not supposed to be user-facing for >>>> some >>>> reason? >>>> >>>> Also, in this post: >>>> >>>> http://archives.postgresql.org/pgsql-sql/2002-01/msg00053.php >>>> >>>> Bruce sort of explains that TRIM is an ANSI word but doesn't fully >>>> explain why it doesn't show up in a \df listing: >>>> >>>> pg=# \df trim >>>> List of functions >>>> Result data type | Schema | Name | Argument data types >>>> ------------------+--------+------+--------------------- >>>> (0 rows) >>>> >>>> This one's more a curiosity thing. >>> >>> Because TRIM is an ANSI standard, we document TRIM (BOTH, ...) but >>> not >>> btrim. The parser does the translation: >>> >>> | TRIM '(' BOTH trim_list ')' >>> { >>> /* various trim expressions are defined in SQL92 >>> * - thomas 1997-07-19 >>> */ >>> FuncCall *n = makeNode(FuncCall); >>> n->funcname = SystemFuncName("btrim"); >>> n->args = $4; >>> n->agg_star = FALSE; >>> n->agg_distinct = FALSE; >>> $$ = (Node *)n; >>> >>> Does that answer your questions? >>> >>> -- >>> Bruce Momjian | http://candle.pha.pa.us >>> pgman@candle.pha.pa.us | (610) 359-1001 >>> + If your life is a hard drive, | 13 Roberts Road >>> + Christ can be your backup. | Newtown Square, >>> Pennsylvania >>> 19073 >> > > -- > Bruce Momjian | http://candle.pha.pa.us > pgman@candle.pha.pa.us | (610) 359-1001 > + If your life is a hard drive, | 13 Roberts Road > + Christ can be your backup. | Newtown Square, Pennsylvania > 19073 > Index: doc/src/sgml/func.sgml > =================================================================== > RCS file: /cvsroot/pgsql/doc/src/sgml/func.sgml,v > retrieving revision 1.225 > diff -c -c -r1.225 func.sgml > *** doc/src/sgml/func.sgml 1 Dec 2004 19:32:12 -0000 1.225 > --- doc/src/sgml/func.sgml 2 Dec 2004 17:12:57 -0000 > *************** > *** 1070,1081 **** > </row> > > <row> > ! > <entry><literal><function>btrim</function>(<parameter>string</ > parameter> <type>text</type>, <parameter>characters</parameter> > <type>text</type>)</literal></entry> > <entry><type>text</type></entry> > <entry> > Remove the longest string consisting only of characters > ! in <parameter>characters</parameter> from the start and end > of > ! <parameter>string</parameter>. > </entry> > <entry><literal>btrim('xyxtrimyyx', 'xy')</literal></entry> > <entry><literal>trim</literal></entry> > --- 1070,1082 ---- > </row> > > <row> > ! > <entry><literal><function>btrim</function>(<parameter>string</ > parameter> <type>text</type> > ! <optional>, <parameter>characters</parameter> > <type>text</type></optional>)</literal></entry> > <entry><type>text</type></entry> > <entry> > Remove the longest string consisting only of characters > ! in <parameter>characters</parameter> (or spaces if not > supplied) > ! from the start and end of <parameter>string</parameter>. > </entry> > <entry><literal>btrim('xyxtrimyyx', 'xy')</literal></entry> > <entry><literal>trim</literal></entry>
Thomas F. O'Connell wrote: > Nice. Thanks, Bruce. If I felt as if I could speak a little more > authoritatively about why it had been missing, I would've offered to > document it. > > Now it is a psql/postgres internals issue that causes \df trim not to > reveal anything? It doesn't reveal with \df because we are mapping the ANSI-standard syntax of TRIM to the Oracle-compatible function of btrim. That mapping is not something psql can see. -- Bruce Momjian | http://candle.pha.pa.us pgman@candle.pha.pa.us | (610) 359-1001 + If your life is a hard drive, | 13 Roberts Road + Christ can be your backup. | Newtown Square, Pennsylvania 19073