Code and docs review for pg_column_size() patch.

1 files changed, 65 insertions, 44 deletions

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index ba372618ac8..7dc9a3b5978 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.275 2005/07/30 22:53:15 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.276 2005/08/02 16:11:56 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -2207,14 +2207,6 @@ PostgreSQL documentation
       </row>
 
       <row>
-       <entry><literal><function>pg_column_size</function>(<parameter>string</parameter>)</literal></entry>
-       <entry><type>integer</type></entry>
-       <entry>Number of bytes required to store the value, which might be compressed</entry>
-       <entry><literal>pg_column_size('jo\\000se'::bytea)</literal></entry>
-       <entry><literal>5</literal></entry>
-      </row>
-
-      <row>
        <entry><literal><function>position</function>(<parameter>substring</parameter> in <parameter>string</parameter>)</literal></entry>
        <entry><type>integer</type></entry>
        <entry>Location of specified substring</entry>
@@ -9181,11 +9173,29 @@ SELECT set_config('log_statement_stats', 'off', false);
    </para>
 
    <para>
-    The functions shown in <xref
-    linkend="functions-admin-dbsize"> calculate the actual disk space
-    usage of database objects.
+    The functions shown in <xref linkend="functions-admin-dbsize"> calculate
+    the actual disk space usage of database objects.
    </para>
 
+   <indexterm zone="functions-admin">
+    <primary>pg_column_size</primary>
+   </indexterm>
+   <indexterm zone="functions-admin">
+    <primary>pg_tablespace_size</primary>
+   </indexterm>
+   <indexterm zone="functions-admin">
+    <primary>pg_database_size</primary>
+   </indexterm>
+   <indexterm zone="functions-admin">
+    <primary>pg_relation_size</primary>
+   </indexterm>
+   <indexterm zone="functions-admin">
+    <primary>pg_complete_relation_size</primary>
+   </indexterm>
+   <indexterm zone="functions-admin">
+    <primary>pg_size_pretty</primary>
+   </indexterm>
+
    <table id="functions-admin-dbsize">
     <title>Database Object Size Functions</title>
     <tgroup cols="3">
@@ -9196,96 +9206,107 @@ SELECT set_config('log_statement_stats', 'off', false);
 
      <tbody>
       <row>
+       <entry><function>pg_column_size</function>(<parameter>any</parameter>)</entry>
+       <entry><type>integer</type></entry>
+       <entry>Number of bytes used to store a particular value (possibly compressed)</entry>
+      </row>
+      <row>
        <entry>
         <literal><function>pg_tablespace_size</function>(<parameter>oid</parameter>)</literal>
         </entry>
-       <entry><type>int8</type></entry>
-       <entry>Calculates the total disk space used by the tablespace with the specified OID</entry>
+       <entry><type>bigint</type></entry>
+       <entry>Total disk space used by the tablespace with the specified OID</entry>
       </row>
       <row>
        <entry>
         <literal><function>pg_tablespace_size</function>(<parameter>name</parameter>)</literal>
         </entry>
-       <entry><type>int8</type></entry>
-       <entry>Calculates the total disk space used by the tablespace with the specified name</entry>
+       <entry><type>bigint</type></entry>
+       <entry>Total disk space used by the tablespace with the specified name</entry>
       </row>
       <row>
        <entry>
         <literal><function>pg_database_size</function>(<parameter>oid</parameter>)</literal>
         </entry>
-       <entry><type>int8</type></entry>
-       <entry>Calculates the total disk space used by the database with the specified OID</entry>
+       <entry><type>bigint</type></entry>
+       <entry>Total disk space used by the database with the specified OID</entry>
       </row>
       <row>
        <entry>
         <literal><function>pg_database_size</function>(<parameter>name</parameter>)</literal>
         </entry>
-       <entry><type>int8</type></entry>
-       <entry>Calculates the total disk space used by the database with the specified name</entry>
+       <entry><type>bigint</type></entry>
+       <entry>Total disk space used by the database with the specified name</entry>
       </row>
       <row>
        <entry>
         <literal><function>pg_relation_size</function>(<parameter>oid</parameter>)</literal>
         </entry>
-       <entry><type>int8</type></entry>
-       <entry>Calculates the disk space used by the table or index with the specified OID</entry>
+       <entry><type>bigint</type></entry>
+       <entry>Disk space used by the table or index with the specified OID</entry>
       </row>
       <row>
        <entry>
         <literal><function>pg_relation_size</function>(<parameter>text</parameter>)</literal>
         </entry>
-       <entry><type>int8</type></entry>
-       <entry>Calculates the disk space used by the index or table with the specified name. 
-       The name may be prefixed with a schema name if required</entry>
+       <entry><type>bigint</type></entry>
+       <entry>Disk space used by the table or index with the specified name.
+       The name may be qualified with a schema name</entry>
       </row>
       <row>
        <entry>
         <literal><function>pg_complete_relation_size</function>(<parameter>oid</parameter>)</literal>
         </entry>
-       <entry><type>int8</type></entry>
-       <entry>Calculates the total disk space used by the table with the specified OID, 
+       <entry><type>bigint</type></entry>
+       <entry>Total disk space used by the table with the specified OID, 
        including indexes and toasted data</entry>
       </row>
       <row>
        <entry>
         <literal><function>pg_complete_relation_size</function>(<parameter>text</parameter>)</literal>
         </entry>
-       <entry><type>int8</type></entry>
-       <entry>Calculates the total disk space used by the table with the specified name, 
-       including indexes and toasted data. The name may be prefixed with a schema name if 
-       required</entry>
+       <entry><type>bigint</type></entry>
+       <entry>Total disk space used by the table with the specified name, 
+       including indexes and toasted data.
+       The table name may be qualified with a schema name</entry>
       </row>
       <row>
        <entry>
-        <literal><function>pg_size_pretty</function>(<parameter>int8</parameter>)</literal>
+        <literal><function>pg_size_pretty</function>(<parameter>bigint</parameter>)</literal>
         </entry>
        <entry><type>text</type></entry>
-       <entry>Formats the size value (in bytes) into a human readable format with size units </entry>
+       <entry>Converts a size in bytes into a human-readable format with size units</entry>
       </row>
      </tbody>
     </tgroup>
    </table>
 
    <para>
-    <function>pg_tablespace_size</> and <function>pg_database_size</> accept an 
-    oid or name of a tablespace or database, and return the disk space usage of the specified object. 
+    <function>pg_column_size</> shows the space used to store any individual
+    data value.
    </para>
 
-   <indexterm zone="functions-admin">
-    <primary>pg_relation_size</primary>
-   </indexterm>
    <para>
-    <function>pg_relation_size</> accepts the oid or name of a table, index or
+    <function>pg_tablespace_size</> and <function>pg_database_size</> accept
+    the OID or name of a tablespace or database, and return the total disk
+    space used therein.
+   </para>
+
+   <para>
+    <function>pg_relation_size</> accepts the OID or name of a table, index or
     toast table, and returns the size in bytes.
    </para>
+
    <para>
-    <function>pg_complete_relation_size</> accepts the oid or name of a table or
-    toast table, and returns the size in bytes of the data and all associated
-    indexes and toast tables.
+    <function>pg_complete_relation_size</> accepts the OID or name of a table
+    or toast table, and returns the size in bytes of the data and all
+    associated indexes and toast tables.
    </para>
+
    <para>
-    <function>pg_size_pretty</> can be used to format the size of the
-    database objects in a human readable way, using kB, MB, GB or TB as appropriate.
+    <function>pg_size_pretty</> can be used to format the result of one of
+    the other functions in a human-readable way, using kB, MB, GB or TB as
+    appropriate.
    </para>
 
   </sect1>