.\\" auto-generated by docbook2man-spec $Revision: 1.2 $
.TH "CREATE CAST" "" "2007-05-04" "SQL - 言語" "SQLコマンド"
.SH NAME
CREATE CAST \- 新しいキャストを定義する

.SH SYNOPSIS
.sp
.nf
CREATE CAST (\fIsourcetype\fR AS \fItargettype\fR)
    WITH FUNCTION \fIfuncname\fR (\fIargtypes\fR)
    [ AS ASSIGNMENT | AS IMPLICIT ]

CREATE CAST (\fIsourcetype\fR AS \fItargettype\fR)
    WITHOUT FUNCTION
    [ AS ASSIGNMENT | AS IMPLICIT ]
.sp
.fi
.SH "説明"
.PP
\fBCREATE CAST\fRを使用すると、新しいキャストを定義できます。
キャストは、2つのデータ型間の変換処理方法を指定するものです。
以下に例を示します。
.sp
.nf
SELECT CAST(42 AS text);
.sp
.fi
この文を実行すると、事前に指定された関数（この場合text(int4)）が呼び出され、整数定数42が\fBtext\fR型に変換されます
（適切なキャストが定義されていない場合、変換処理は失敗します）。
.PP
2つのデータ型に、\fIバイナリ互換性\fRがある可能性があります。
この場合は、関数を呼び出さなくても、``自由に''お互いのデータ型に変換することができます。
ただし、対応する値は、同じ内部表現を使用している必要があります。
例えば、データ型\fBtext\fRと\fBvarchar\fRには、バイナリ互換性があります。 
.PP
デフォルトでは、キャストは明示的なキャスト要求があった場合のみ発生します。
明示的なキャスト要求の構文は、CAST(\fIx\fR AS \fItypename\fR)、もしくは、\fIx\fR::\fItypename\fRです。
.PP
キャストにAS ASSIGNMENTオプションを付けると、対象データ型の列に代入する際、暗黙的にそのキャストを発生させるように設定できます。
例えば、foo.f1が\fBtext\fR型の列であるとします。
.sp
.nf
INSERT INTO foo (f1) VALUES (42);
.sp
.fi
\fBinteger\fR型を\fBtext\fR型に変換するキャストにAS ASSIGNMENTオプションが付けられていれば、上記のSQL文が実行できます。
しかし、AS ASSIGNMENTオプションが付いていなければ、実行できません
（一般的に、この種のキャストは\fI代入キャスト\fRと呼ばれています）。
.PP
キャストにAS IMPLICITオプションを付けると、代入の場合だけでなく、式の中にある場合でも、全てのコンテキストで暗黙的にそのキャストを呼び出すように設定できます。
以下の例を参照してください。
||は\fBtext\fR型の引数を受け取るので、
.sp
.nf
SELECT 'The time is ' || now();
.sp
.fi
というSQL文は、\fBtimestamp\fR型を\fBtext\fR型に変換するキャストにAS IMPLICITオプションが付けられている場合のみ実行可能です。
AS IMPLICITオプションが付いていない場合、以下のように明示的にキャストを記述する必要があります。
.sp
.nf
SELECT 'The time is ' || CAST(now() AS text);
.sp
.fi
（一般的に、この種のキャストは\fI暗黙キャスト\fRと呼ばれています。）
.PP
暗黙キャストは、多用しない方が賢明です。
暗黙的キャストを使用し過ぎると、PostgreSQLがコマンドを思わぬ意味に解釈してしまう原因になります。
また、複数の解釈が可能なため、コマンドをまったく解読できなくなってしまう可能性もあります。
経験的には、2つのデータ型が同一の一般的なデータ型のカテゴリに属しており、変換によって情報が保持される場合のみ、暗黙キャストを呼び出し可能にするのが良い方法と思われます。
例えば、\fBint2\fR型から\fBint4\fR型へのキャストは、暗黙キャストにするのが妥当ですが、\fBfloat8\fR型から\fBint4\fR型へのキャストは、代入キャストのみにすべきと思われます。
\fBtext\fR型から\fBint4\fR型への変換のような、カテゴリを越えるデータ型のキャストは、明示的にのみ使用するのが適切です。
.PP
キャストを作成するには、変換元または変換先のデータ型を所有している必要があります。
また、バイナリ互換性を持つキャストを作成できるのは、スーパーユーザのみです
（バイナリ互換性があるキャスト変換を誤って使用するとサーバがクラッシュしてしまう可能性が高いことから、この制限が付けられました）。
.SH "パラメータ"
.TP
\fB\fIsourcetype\fB\fR
キャストする変換元のデータ型の名前です。
.TP
\fB\fItargettype\fB\fR
キャストする変換先のデータ型の名前です。
.TP
\fB\fIfuncname\fB(\fIargtypes\fB)\fR
この関数は、キャストを実行するために使用します。
関数名は、スキーマ修飾することができます。
スキーマ修飾されていない場合、関数はスキーマ検索パスから検索されます。
関数の結果のデータ型は、キャストの変換先のデータ型と一致する必要があります。
引数については後で説明します。
.TP
\fBWITHOUT FUNCTION\fR
変換元データ型と変換先データ型の間に、バイナリ互換性があることを示します。
この場合、キャストを実行するのに関数は必要ありません。
.TP
\fBAS ASSIGNMENT\fR
代入コンテキストで、暗黙的にキャストを呼び出せることを示します。
.TP
\fBAS IMPLICIT\fR
任意のコンテキストで、暗黙的にキャストを呼び出せることを示します。
.PP
キャストを実装する関数は1〜3個の引数を取ることができます。
1番目の引数型はキャストの変換元データ型と同一でなければなりません。
2番目の引数（もしあれば）は、\fBinteger\fR型でなければなりません。変換先の型に関連付けられた型修飾子を指定します。
型修飾子がない場合は-1を指定します。
3番目の引数（もしあれば）は、\fBboolean\fR型でなければなりません。キャストが明示的なキャストであればtrueを、それ以外であればfalseを指定します
（奇妙な話ですが、SQL仕様では、明示的キャストと暗黙的キャストとの間で異なる振舞いを要求する場合があります。
この引数はそのようなキャストを実装しなければならない関数用に提供されています。
独自のデータ型をこの流儀に従うように設計することは勧められません）。
.PP
.PP
通常、キャストにおける変換元データ型と変換先データ型は異なる必要があります。
しかし、2つ以上の引数を持つ関数でキャストを実装した場合は、変換元と変換先とで同一のデータ型を持つキャストを宣言することができます。
これは、システムカタログにおいて型固有の長さ強制関数を表現するために使用されています。
このように指定された関数は、型の値を強制的に2番目の引数で与えられた型修飾子の値にするために使用されます
（文法上、型修飾子を持つのは特定の組み込みデータ型のみなので、この機能は変換先のデータ型がユーザ定義のものである場合には役に立ちません。
ここでは、説明を完全にするために言及しています）。
.PP
.PP
変換元と変換先のデータ型が異なるキャストにおいて複数の引数を取る関数は、あるデータ型から他のデータ型への変換と長さの強制を1つの操作にまとめたものを表します。
引数を1つしか取らない場合は、型修飾子を使用して型を強制するために、データ型間の変換と修飾子の適用という2つの操作が必要となります。
.PP
.SH "注釈"
.PP
ユーザ定義のキャストを削除するには、DROP CAST [\fBdrop_cast\fR(l)]を使用してください。
.PP
データ型を双方向に変更可能にするには、双方向のキャストを明示的に宣言する必要があることに注意してください。
.PP
PostgreSQL 7.3より前のバージョンでは、データ型と同じ名前を持ち、そのデータ型を返し、異なるデータ型の引数を1つ取る関数は、自動的にキャスト関数とみなされていました。
この慣習は、スキーマを導入し、システムカタログでバイナリ互換性によるキャストを実現可能にしたことにより、廃止されました。 
組み込みキャスト関数は、まだこの命名規則に従っています。
しかし、他のキャスト同様、pg_castシステムカタログにキャストとして示されている必要があります。 
.PP
必須ではありませんが、キャストを実装する関数には変換先のデータ型の名前を付けるという以前からの慣習に従っておくことを推奨します。
多くのユーザは\fItypename\fR(\fIx\fR)という関数スタイルの記法でデータ型のキャストを行っています。
この記法は、キャストを実装している関数の呼び出しに他なりません。
キャストとして特別に扱っているわけではないのです。
ユーザが作成した変換関数の名前がこの慣習に従っていないと、他のユーザがとまどうことになります。
PostgreSQLは引数として異なる型を取る同じ名前の関数をオーバーロードすることができるので、様々な型から特定の変換先型への変換関数の名前を全て変換先の型名にしても特に問題は発生しません。
.sp
.RS
.B "Note:"
ただし、先ほどの段落には少しだけ嘘があります。
\fBpg_cast\fRが、明示的な関数呼び出しの意味解決に使用される場合があることです。
関数呼び出し\fIname\fR(\fIx\fR)が実際の関数に一致せず、\fIname\fRがデータ型の名前であり、\fBpg_cast\fRに\fIx\fRの型からその型へのキャストがバイナリ互換であることが示されていた場合、この呼び出しは明示的キャストとして処理されます。
この例外は、実際の関数が存在しなくても、関数のような構文でバイナリ互換キャストを呼び出すことができるように作成されました。
.RE
.sp
.SH "例"
.PP
関数int4(text)を使用した\fBtext\fR型から\fBint4\fR型へのキャストを作成します。
.sp
.nf
CREATE CAST (text AS int4) WITH FUNCTION int4(text);
.sp
.fi
（このキャストは、システムに既に定義されています。）
.SH "互換性"
.PP
SQLではバイナリ互換性があるデータ型や実装関数の追加の引数について規定されていません。さらに、AS IMPLICITは、PostgreSQLの拡張です。
これらの点以外では、\fBCREATE CAST\fRは標準SQLに準拠しています。
.SH "関連項目"
.PP
CREATE FUNCTION [\fBcreate_function\fR(l)],
CREATE TYPE [\fBcreate_type\fR(l)],
DROP CAST [\fBdrop_cast\fR(l)]
