Re: get_bit etc.

I have added documentation for all the bit/byte get/set functions, and
added a pg_description comment for each of them --- patch attached.

---------------------------------------------------------------------------

Tom Lane wrote:
> Brian Minton <bminton@efn.org> writes:
> > Tom Lane wrote:
> >> A documentation patch would be welcomed.
>
> > ok, how do I do that?
>
> Ideally, send a patch diff against the appropriate .sgml file in the doc
> source tree to pgsql-patches.  If you're not up for patching SGML, write
> some plain ASCII text that would fit into the docs and send it to
> pgsql-docs; somebody will take care of marking it up in SGML and
> committing it where it belongs.
>
> > They are simple enough functions, and it was easy
> > to figure out what they did, but there is no mention of them, I guess
> > maybe they are "unofficial" functions.
>
> No, they're clearly intended as user-accessible functions.  I'd say the
> author was too dern lazy to include any documentation when he submitted
> the code patch :-(.  We have a lot of that disease goin' round.
>
>             regards, tom lane
>
> ---------------------------(end of broadcast)---------------------------
> TIP 6: Have you searched our list archives?
>
> http://archives.postgresql.org
>

--
  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-server/doc/src/sgml/func.sgml,v
retrieving revision 1.132
diff -c -c -r1.132 func.sgml
*** doc/src/sgml/func.sgml    23 Nov 2002 04:04:43 -0000    1.132
--- doc/src/sgml/func.sgml    5 Dec 2002 04:36:25 -0000
***************
*** 473,479 ****
      shown in <xref linkend="functions-math-bit-table">.
      Bit string arguments to <literal>&</literal>, <literal>|</literal>,
      and <literal>#</literal> must be of equal length.  When bit
!     shifting, the original length of the string is preserved, as shown in the table.
     </para>

      <table id="functions-math-bit-table">
--- 473,480 ----
      shown in <xref linkend="functions-math-bit-table">.
      Bit string arguments to <literal>&</literal>, <literal>|</literal>,
      and <literal>#</literal> must be of equal length.  When bit
!     shifting, the original length of the string is preserved, as shown
!     in the table.
     </para>

      <table id="functions-math-bit-table">
***************
*** 2119,2124 ****
--- 2120,2177 ----
         </entry>
         <entry><literal>trim('\\000'::bytea from '\\000Tom\\000'::bytea)</literal></entry>
         <entry><literal>Tom</literal></entry>
+       </row>
+
+       <row>
+        <entry><function>get_byte</function>(<parameter>string</parameter>, <parameter>offset</parameter>)</entry>
+        <entry><type>integer</type></entry>
+        <entry>
+         Extract byte from string.
+         <indexterm>
+          <primary>get_byte</primary>
+         </indexterm>
+        </entry>
+        <entry><literal>get_byte('Th\\000omas'::bytea, 4)</literal></entry>
+        <entry><literal>109</literal></entry>
+       </row>
+
+       <row>
+        <entry><function>set_byte</function>(<parameter>string</parameter>, <parameter>offset</parameter>)</entry>
+        <entry><type>bytea</type></entry>
+        <entry>
+         Set byte in string.
+         <indexterm>
+          <primary>set_byte</primary>
+         </indexterm>
+        </entry>
+        <entry><literal>set_byte('Th\\000omas'::bytea, 4, 64)</literal></entry>
+        <entry><literal>Th\000o@as</literal></entry>
+       </row>
+
+       <row>
+        <entry><function>get_bit</function>(<parameter>string</parameter>, <parameter>offset</parameter>)</entry>
+        <entry><type>integer</type></entry>
+        <entry>
+         Extract bit from string.
+         <indexterm>
+          <primary>get_bit</primary>
+         </indexterm>
+        </entry>
+        <entry><literal>get_bit('Th\\000omas'::bytea, 45)</literal></entry>
+        <entry><literal>1</literal></entry>
+       </row>
+
+       <row>
+        <entry><function>set_bit</function>(<parameter>string</parameter>, <parameter>offset</parameter>)</entry>
+        <entry><type>bytea</type></entry>
+        <entry>
+         Set bit in string.
+         <indexterm>
+          <primary>set_bit</primary>
+         </indexterm>
+        </entry>
+        <entry><literal>set_bit('Th\\000omas'::bytea, 45, 0)</literal></entry>
+        <entry><literal>Th\000omAs</literal></entry>
        </row>
       </tbody>
      </tgroup>
Index: src/include/catalog/pg_proc.h
===================================================================
RCS file: /cvsroot/pgsql-server/src/include/catalog/pg_proc.h,v
retrieving revision 1.277
diff -c -c -r1.277 pg_proc.h
*** src/include/catalog/pg_proc.h    4 Dec 2002 05:18:36 -0000    1.277
--- src/include/catalog/pg_proc.h    5 Dec 2002 04:36:30 -0000
***************
*** 958,970 ****
  DATA(insert OID = 720 (  octet_length       PGNSP PGUID 12 f f t f i 1 23 "17"  byteaoctetlen - _null_ ));
  DESCR("octet length");
  DATA(insert OID = 721 (  get_byte           PGNSP PGUID 12 f f t f i 2 23 "17 23"    byteaGetByte - _null_ ));
! DESCR("");
  DATA(insert OID = 722 (  set_byte           PGNSP PGUID 12 f f t f i 3 17 "17 23 23"  byteaSetByte - _null_ ));
! DESCR("");
  DATA(insert OID = 723 (  get_bit           PGNSP PGUID 12 f f t f i 2 23 "17 23"    byteaGetBit - _null_ ));
! DESCR("");
  DATA(insert OID = 724 (  set_bit           PGNSP PGUID 12 f f t f i 3 17 "17 23 23"  byteaSetBit - _null_ ));
! DESCR("");

  DATA(insert OID = 725 (  dist_pl           PGNSP PGUID 12 f f t f i 2 701 "600 628"  dist_pl - _null_ ));
  DESCR("distance between point and line");
--- 958,970 ----
  DATA(insert OID = 720 (  octet_length       PGNSP PGUID 12 f f t f i 1 23 "17"  byteaoctetlen - _null_ ));
  DESCR("octet length");
  DATA(insert OID = 721 (  get_byte           PGNSP PGUID 12 f f t f i 2 23 "17 23"    byteaGetByte - _null_ ));
! DESCR("get byte");
  DATA(insert OID = 722 (  set_byte           PGNSP PGUID 12 f f t f i 3 17 "17 23 23"  byteaSetByte - _null_ ));
! DESCR("set byte");
  DATA(insert OID = 723 (  get_bit           PGNSP PGUID 12 f f t f i 2 23 "17 23"    byteaGetBit - _null_ ));
! DESCR("get bit");
  DATA(insert OID = 724 (  set_bit           PGNSP PGUID 12 f f t f i 3 17 "17 23 23"  byteaSetBit - _null_ ));
! DESCR("set bit");

  DATA(insert OID = 725 (  dist_pl           PGNSP PGUID 12 f f t f i 2 701 "600 628"  dist_pl - _null_ ));
  DESCR("distance between point and line");