Doc updates from Darren on char2-16 removal

6 files changed, 35 insertions, 48 deletions

diff --git a/doc/FAQ b/doc/FAQ
index c0728c25c71..59ee0191e8c 100644
--- a/doc/FAQ
+++ b/doc/FAQ
@@ -543,7 +543,7 @@ Section 3: PostgreSQL Features
         jolly=>
 
    The fields in pg_group are:
-     * groname: the group name. This a char16 and should be purely
+     * groname: the group name. This a name and should be purely
        alphanumeric. Do not include underscores or other punctuation.
      * grosysid: the group id. This is an int4. This should be unique for
        each group.
@@ -622,11 +622,7 @@ Section 3: PostgreSQL Features
   
 Type            Internal Name   Notes
 --------------------------------------------------
-CHAR            char            1 character   }
-CHAR2           char2           2 characters  }
-CHAR4           char4           4 characters  } optimized for a fixed length
-CHAR8           char8           8 characters  }
-CHAR16          char16          16 characters }
+CHAR            char            1 character
 CHAR(#)         bpchar          blank padded to the specified fixed length
 VARCHAR(#)      varchar         size specifies maximum length, no padding
 TEXT            text            length limited only by maximum tuple length
diff --git a/doc/src/sgml/advanced.sgml b/doc/src/sgml/advanced.sgml
index 9d8b2082b80..c9d2256b198 100644
--- a/doc/src/sgml/advanced.sgml
+++ b/doc/src/sgml/advanced.sgml
@@ -126,7 +126,7 @@ SELECT c.name, c.altitude
 CREATE TABLE SAL_EMP (
     name            text,
     pay_by_quarter  int4[],
-    schedule        char16[][]
+    schedule        text[][]
 );
 </ProgramListing>
 </Para>
@@ -135,7 +135,7 @@ CREATE TABLE SAL_EMP (
      The above query will create a class named SAL_EMP  with
      a  <FirstTerm>text</FirstTerm>  string (name), a one-dimensional array of <FirstTerm>int4</FirstTerm>
      (pay_by_quarter),  which  represents   the   employee's
-     salary by quarter and a two-dimensional array of <FirstTerm>char16</FirstTerm>
+     salary by quarter and a two-dimensional array of <FirstTerm>text</FirstTerm>
      (schedule),  which  represents  the  employee's  weekly
      schedule.   Now  we  do  some  <FirstTerm>INSERTS</FirstTerm>s; note that when
      appending to an array, we  enclose  the  values  within
diff --git a/doc/src/sgml/array.sgml b/doc/src/sgml/array.sgml
index 4b736086001..aada6f71c65 100644
--- a/doc/src/sgml/array.sgml
+++ b/doc/src/sgml/array.sgml
@@ -20,7 +20,7 @@ This must become a chapter on array behavior. Volunteers? - thomas 1998-01-12
 CREATE TABLE SAL_EMP (
     name            text,
     pay_by_quarter  int4[],
-    schedule        char16[][]
+    schedule        text[][]
 );
 </ProgramListing>
 </Para>
@@ -29,7 +29,7 @@ CREATE TABLE SAL_EMP (
      The above query will create a class named SAL_EMP  with
      a  <FirstTerm>text</FirstTerm>  string (name), a one-dimensional array of <FirstTerm>int4</FirstTerm>
      (pay_by_quarter),  which  represents   the   employee's
-     salary by quarter and a two-dimensional array of <FirstTerm>char16</FirstTerm>
+     salary by quarter and a two-dimensional array of <FirstTerm>text</FirstTerm>
      (schedule),  which  represents  the  employee's  weekly
      schedule.   Now  we  do  some  <FirstTerm>INSERTS</FirstTerm>s; note that when
      appending to an array, we  enclose  the  values  within
diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index 48c2a49070a..70a0d383c02 100644
--- a/doc/src/sgml/datatype.sgml
+++ b/doc/src/sgml/datatype.sgml
@@ -368,13 +368,16 @@ limit to be declared on the size of the field.
 </Para>
 
 <Para>
-There are currently other fixed-length character types. These provide no additional
-functionality and are likely to be deprecated in the future.
+There is currently one other fixed-length character type. The <Type>name</Type> type
+only has one purpose and that is to provide <ProductName>Postgres</ProductName> with a
+special type to use for internal names.  It is not intended for use by the general user.
+It's length is currently defined as 32 chars but should be reference using NAMEDATALEN.
+This is set at compile time and may change in any future release.
 </Para>
 
 <Para>
 <TABLE TOCENTRY="1">
-<TITLE><ProductName>Postgres</ProductName> Specialty Character Types</TITLE>
+<TITLE><ProductName>Postgres</ProductName> Specialty Character Type</TITLE>
 <TITLEABBREV>Specialty Characters</TITLEABBREV>
 <TGROUP COLS="3">
 <THEAD>
@@ -386,24 +389,9 @@ functionality and are likely to be deprecated in the future.
 </THEAD>
 <TBODY>
   <ROW>
-    <ENTRY>char2</ENTRY>
-    <ENTRY>2 bytes</ENTRY>
-    <ENTRY>Two characters</ENTRY>
-  </ROW>
-  <ROW>
-    <ENTRY>char4</ENTRY>
-    <ENTRY>4 bytes</ENTRY>
-    <ENTRY>Four characters</ENTRY>
-  </ROW>
-  <ROW>
-    <ENTRY>char8</ENTRY>
-    <ENTRY>8 bytes</ENTRY>
-    <ENTRY>Eight characters</ENTRY>
-  </ROW>
-  <ROW>
-    <ENTRY>char16</ENTRY>
-    <ENTRY>16 bytes</ENTRY>
-    <ENTRY>Sixteen characters</ENTRY>
+    <ENTRY>name</ENTRY>
+    <ENTRY>32 bytes</ENTRY>
+    <ENTRY>Thirty-two character internal type</ENTRY>
   </ROW>
 </TBODY>
 </TGROUP>
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 127f24517da..95608187941 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -736,7 +736,7 @@ void PQputline(PGconn *conn,
 int PQendcopy(PGconn *conn);
 </ProgramListing>
 <ProgramListing>
-PQexec(conn, "create table foo (a int4, b char16, d float8)");
+PQexec(conn, "create table foo (a int4, b text, d float8)");
 PQexec(conn, "copy foo from stdin");
 PQputline(conn, "3&lt;TAB&gt;hello world&lt;TAB&gt;4.5\n");
 PQputline(conn,"4&lt;TAB&gt;goodbye world&lt;TAB&gt;7.11\n");
diff --git a/doc/src/sgml/xfunc.sgml b/doc/src/sgml/xfunc.sgml
index f1275bbb462..880ea9fdc46 100644
--- a/doc/src/sgml/xfunc.sgml
+++ b/doc/src/sgml/xfunc.sgml
@@ -136,7 +136,7 @@
      AS 'SELECT \'None\'::text AS name,
       1000 AS salary,
       25 AS age,
-      \'none\'::char16 AS dept;'
+      \'none\'::text AS dept;'
       LANGUAGE 'sql';
 </ProgramListing>
 
@@ -263,7 +263,7 @@ The reason why, in general, we must use the function
 <Para>
      On  the  other hand, fixed-length types of any size may
      be passed by-reference.  For example, here is a  sample
-     implementation of the <ProductName>Postgres</ProductName> char16 type:
+     implementation of a <ProductName>Postgres</ProductName> type:
      
 <ProgramListing>
          /* 16-byte structure, passed by reference */
@@ -305,7 +305,6 @@ The reason why, in general, we must use the function
      structure, we might use a code fragment like this:
 <ProgramListing>
          #include "postgres.h"
-         #include "utils/palloc.h"
          ...
          char buffer[40]; /* our source data */
          ...
@@ -322,20 +321,23 @@ The reason why, in general, we must use the function
      Suppose <FileName>funcs.c</FileName> look like:
 <ProgramListing>
          #include &lt;string.h&gt;
-         #include "postgres.h"  /* for char16, etc. */
-         #include "utils/palloc.h" /* for palloc */
+         #include "postgres.h"
          int
          add_one(int arg)
          {
              return(arg + 1);
          }
-         char16 *
-         concat16(char16 *arg1, char16 *arg2)
+         text *
+         concat_text(text *arg1, text *arg2)
          {
-             char16 *new_c16 = (char16 *) palloc(sizeof(char16));
-             memset((void *) new_c16, 0, sizeof(char16));
-             (void) strncpy(new_c16, arg1, 16);
-             return (char16 *)(strncat(new_c16, arg2, 16));
+             int32 new_text_size = VARSIZE(arg1) + VARSIZE(arg2) - VARHDRSZ;
+             text *new_text = (text *) palloc(new_text_size);
+
+             memset((void *) new_text, 0, new_text_size);
+             VARSIZE(new_text) = new_text_size;
+             strncpy(VARDATA(new_text), VARDATA(arg1), VARSIZE(arg1)-VARHDRSZ);
+             strncat(VARDATA(new_text), VARDATA(arg2), VARSIZE(arg2)-VARHDRSZ);
+             return (new_text);
          }
          text *
          copytext(text *t)
@@ -364,7 +366,7 @@ The reason why, in general, we must use the function
          CREATE FUNCTION add_one(int4) RETURNS int4
               AS 'PGROOT/tutorial/obj/funcs.so' LANGUAGE 'c';
 
-         CREATE FUNCTION concat16(char16, char16) RETURNS char16
+         CREATE FUNCTION concat_text(text, text) RETURNS text
               AS 'PGROOT/tutorial/obj/funcs.so' LANGUAGE 'c';
 
          CREATE FUNCTION copytext(text) RETURNS text
@@ -401,7 +403,7 @@ The reason why, in general, we must use the function
      In the query above, we can define c_overpaid as:
      
 <ProgramListing>
-         #include "postgres.h"  /* for char16, etc. */
+         #include "postgres.h"
          #include "libpq-fe.h" /* for TUPLE */
          bool
          c_overpaid(TUPLE t,/* the current instance of EMP */
@@ -426,7 +428,7 @@ The reason why, in general, we must use the function
      is  null.   <Acronym>GetAttributeByName</Acronym> will align data properly
      so you can cast its return value to the  desired  type.
      For  example, if you have an attribute name which is of
-     the type char16, the <Acronym>GetAttributeByName</Acronym> call would look
+     the type name, the <Acronym>GetAttributeByName</Acronym> call would look
      like:
 <ProgramListing>
          char *str;
@@ -517,8 +519,9 @@ Most of the header (include) files for  <ProductName>Postgres</ProductName>
 </Para>
       <ListItem>
 <Para>   Most of the internal <ProductName>Postgres</ProductName> types are declared
-            in  postgres.h,  so  it's usually a good idea to
-            include that file as well.
+            in  postgres.h,  so  it's a good idea to always
+            include that file as well.  Including postgres.h
+            will also include elog.h and palloc.h for you.
 </Para>
       <ListItem>
 <Para>   Compiling and loading your object code  so  that