As described in <xref linkend="extend-type-system"/>, <productname>PostgreSQL</productname> can be extended to support new data types. This section describes how to define new base types, which are data types defined below the level of the <acronym>SQL</acronym> language. Creating a new base type requires implementing functions to operate on the type in a low-level language, usually C. 38.2に述べられているように、PostgreSQLは、新しい型をサポートするように拡張することができます。 本節では、SQL言語以下のレベルで定義されるデータ型である基本型を新しく定義する方法について説明します。 新しい基本型の作成には、低レベル言語、通常Cで作成された型を操作する関数の実装が必要です。

The examples in this section can be found in <filename>complex.sql</filename> and <filename>complex.c</filename> in the <filename>src/tutorial</filename> directory of the source distribution. See the <filename>README</filename> file in that directory for instructions about running the examples. 本節で使用する例は、ソース配布物内のsrc/tutorialディレクトリにcomplex.sqlとcomplex.cという名前で置いてあります。 この例の実行方法についてはディレクトリ内のREADMEを参照してください。

A user-defined type must always have input and output functions. These functions determine how the type appears in strings (for input by the user and output to the user) and how the type is organized in memory. The input function takes a null-terminated character string as its argument and returns the internal (in memory) representation of the type. The output function takes the internal representation of the type as argument and returns a null-terminated character string. If we want to do anything more with the type than merely store it, we must provide additional functions to implement whatever operations we'd like to have for the type. ユーザ定義データ型では必ず入力関数と出力関数が必要です。 これらの関数は、その型が（ユーザによる入力とユーザへの出力のための）文字列としてどのように表現されるかと、その型がメモリ中でどう構成されるかを決定します。 入力関数は引数としてヌル終端文字列を取り、その型の（メモリ中の）内部表現を返します。 出力関数は引数としてその型の内部表現を取り、ヌル終端文字列を返します。 単に格納するだけではなく、その型に操作を加えたいのであれば、その型に持たせたいすべての操作を実装した関数をさらに提供しなければなりません。

Suppose we want to define a type <type>complex</type> that represents complex numbers. A natural way to represent a complex number in memory would be the following C structure: 例えば、複素数を表現するcomplex型を定義することを考えます。 おそらく、次のようなC構造体で複素数をメモリ中で表現することがごく自然な方法です。

typedef struct Complex {
    double      x;
    double      y;
} Complex;

We will need to make this a pass-by-reference type, since it's too large to fit into a single <type>Datum</type> value. 単一のDatum値で扱うには大き過ぎるので、これは参照渡し型にしなければなりません。

As the external string representation of the type, we choose a string of the form <literal>(x,y)</literal>. この型の外部文字列表現として(x,y)形式の文字列を使用することを選択します。

The input and output functions are usually not hard to write, especially the output function. But when defining the external string representation of the type, remember that you must eventually write a complete and robust parser for that representation as your input function. For instance: 入出力関数、特に出力関数を作成することは困難ではありません。 しかし、この型の外部表現文字列を定義する時、その表現のための完全で堅牢なパーサを入力関数として作成しなければなりません。 以下に例を示します。

PG_FUNCTION_INFO_V1(complex_in);

Datum
complex_in(PG_FUNCTION_ARGS)
{
    char       *str = PG_GETARG_CSTRING(0);
    double      x,
                y;
    Complex    *result;

    if (sscanf(str, " ( %lf , %lf )", &x, &y) != 2)
        ereport(ERROR,
                (errcode(ERRCODE_INVALID_TEXT_REPRESENTATION),
                 errmsg("invalid input syntax for type %s: \"%s\"",
                        "complex", str)));

    result = (Complex *) palloc(sizeof(Complex));
    result->x = x;
    result->y = y;
    PG_RETURN_POINTER(result);
}

The output function can simply be: 出力関数は以下のように簡単にできます。

PG_FUNCTION_INFO_V1(complex_out);

Datum
complex_out(PG_FUNCTION_ARGS)
{
    Complex    *complex = (Complex *) PG_GETARG_POINTER(0);
    char       *result;

    result = psprintf("(%g,%g)", complex->x, complex->y);
    PG_RETURN_CSTRING(result);
}

You should be careful to make the input and output functions inverses of each other. If you do not, you will have severe problems when you need to dump your data into a file and then read it back in. This is a particularly common problem when floating-point numbers are involved. 入出力関数は各々の逆関数になるように注意しなければなりません。 そうしないと、データをファイルにダンプし、それを読み戻そうとする際に、深刻な問題が発生するでしょう。 これは特に浮動小数点数が関係する際によく発生する問題です。

Optionally, a user-defined type can provide binary input and output routines. Binary I/O is normally faster but less portable than textual I/O. As with textual I/O, it is up to you to define exactly what the external binary representation is. Most of the built-in data types try to provide a machine-independent binary representation. For <type>complex</type>, we will piggy-back on the binary I/O converters for type <type>float8</type>: 省略することができますが、ユーザ定義型はバイナリ入出力関数を提供することができます。 バイナリ入出力は通常テキスト入出力より高速ですが、テキスト入出力より移植性がありません。 テキスト入出力と同様に、外部バイナリ表現を正確に定義することは作成者の責任です。 ほとんどの組み込みデータ型は、マシンに依存しないバイナリ表現を提供しようとしています。 complex型ではfloat8型のバイナリ入出力コンバータを元にします。

PG_FUNCTION_INFO_V1(complex_recv);

Datum
complex_recv(PG_FUNCTION_ARGS)
{
    StringInfo  buf = (StringInfo) PG_GETARG_POINTER(0);
    Complex    *result;

    result = (Complex *) palloc(sizeof(Complex));
    result->x = pq_getmsgfloat8(buf);
    result->y = pq_getmsgfloat8(buf);
    PG_RETURN_POINTER(result);
}

PG_FUNCTION_INFO_V1(complex_send);

Datum
complex_send(PG_FUNCTION_ARGS)
{
    Complex    *complex = (Complex *) PG_GETARG_POINTER(0);
    StringInfoData buf;

    pq_begintypsend(&buf);
    pq_sendfloat8(&buf, complex->x);
    pq_sendfloat8(&buf, complex->y);
    PG_RETURN_BYTEA_P(pq_endtypsend(&buf));
}

Once we have written the I/O functions and compiled them into a shared library, we can define the <type>complex</type> type in SQL. First we declare it as a shell type: 入出力関数を作成し共有ライブラリ内にコンパイルすれば、SQLでcomplex型を定義することができます。 まずシェル型として宣言します。

CREATE TYPE complex;

This serves as a placeholder that allows us to reference the type while defining its I/O functions. Now we can define the I/O functions: これは、入出力関数を定義する時にこの型を参照することができるプレースホルダとして動作します。 この後以下のように、入出力関数を定義することができます。

CREATE FUNCTION complex_in(cstring)
    RETURNS complex
    AS 'filename'
    LANGUAGE C IMMUTABLE STRICT;

CREATE FUNCTION complex_out(complex)
    RETURNS cstring
    AS 'filename'
    LANGUAGE C IMMUTABLE STRICT;

CREATE FUNCTION complex_recv(internal)
   RETURNS complex
   AS 'filename'
   LANGUAGE C IMMUTABLE STRICT;

CREATE FUNCTION complex_send(complex)
   RETURNS bytea
   AS 'filename'
   LANGUAGE C IMMUTABLE STRICT;

Finally, we can provide the full definition of the data type: 最後にデータ型の完全な定義を提供することができます。

CREATE TYPE complex (
   internallength = 16,
   input = complex_in,
   output = complex_out,
   receive = complex_recv,
   send = complex_send,
   alignment = double
);

When you define a new base type, <productname>PostgreSQL</productname> automatically provides support for arrays of that type. The array type typically has the same name as the base type with the underscore character (<literal>_</literal>) prepended. 新しい基本型を定義すると、PostgreSQLは自動的にその型の配列のサポートを提供します。 配列型は通常、基本型の名前の前にアンダースコア文字_が付いた名前になります。

Once the data type exists, we can declare additional functions to provide useful operations on the data type. Operators can then be defined atop the functions, and if needed, operator classes can be created to support indexing of the data type. These additional layers are discussed in following sections. データ型が存在するようになると、そのデータ型に対する有用な操作を提供する関数を宣言することができます。 そしてその関数を使用する演算子も定義できます。 また、必要に応じて、そのデータ型用のインデックスをサポートするための演算子クラスも作成することができます。 こうした追加層については後の節で説明します。

If the internal representation of the data type is variable-length, the internal representation must follow the standard layout for variable-length data: the first four bytes must be a <type>char[4]</type> field which is never accessed directly (customarily named <structfield>vl_len_</structfield>). You must use the <function>SET_VARSIZE()</function> macro to store the total size of the datum (including the length field itself) in this field and <function>VARSIZE()</function> to retrieve it. (These macros exist because the length field may be encoded depending on platform.) データ型の内部表現が可変長であるなら、内部表現は可変長データの標準配置に従わなければなりません。先頭の4バイトはchar[4]フィールドで、直接アクセスされることは決してありません（慣習的にvl_len_と呼ばれます）。 SET_VARSIZE()マクロを使用してデータの総量をこのフィールドに格納し、また、VARSIZE()を使用して取り出さなければなりません。 (長さフィールドはプラットフォームに依存してエンコードされるかもしれませんので、このマクロが存在します。)

For further details see the description of the <xref linkend="sql-createtype"/> command. 詳細についてはCREATE TYPEコマンドの説明を参照してください。