Thread: (b)trim anomalies

(b)trim anomalies

From
Thomas F.O'Connell
Date:
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


Re: (b)trim anomalies

From
Bruce Momjian
Date:
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

Re: (b)trim anomalies

From
Thomas F.O'Connell
Date:
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


Re: (b)trim anomalies

From
Bruce Momjian
Date:
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>

Re: (b)trim anomalies

From
Thomas F.O'Connell
Date:
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>


Re: (b)trim anomalies

From
Bruce Momjian
Date:
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