33.6. pgtypes ライブラリ

新規割当ての numeric 型へのポインタを要求します。

numeric *PGTYPESnumeric_new(void);

numeric 型を解放し、そのメモリをすべて解放します。

void PGTYPESnumeric_free(numeric *var);

文字列表記から numeric 型に変換します。

numeric *PGTYPESnumeric_from_asc(char *str, char **endptr);

有効な書式の例を示します。 -2、.794、+3.44、592.49E07、-32.84e-4。 値への変換に成功した場合、有効なポインタが返されます。 失敗した場合は NULL ポインタが返されます。 現在ECPGは文字列全体を解析しますので、現時点では*endptr内に最初の無効な文字のアドレスを格納することをサポートしません。 このためendptrを安全に NULL にすることができます。

numeric 型numの文字列表現を持つ、mallocで割り当てられた文字列へのポインタを返します。

char *PGTYPESnumeric_to_asc(numeric *num, int dscale);

numeric の値は、必要に応じて四捨五入され、dscale 桁の十進数で出力されます。

2つの numeric 変数を加算し、3番目の numeric 変数に格納します。

int PGTYPESnumeric_add(numeric *var1, numeric *var2, numeric *result);

この関数は変数var1と変数var2を加算し、その結果をresultに格納します。 成功時0を、エラー時-1を返します。

2つの numeric 型変数を減算し、3番目の numeric 型変数に結果を格納します。

int PGTYPESnumeric_sub(numeric *var1, numeric *var2, numeric *result);

この関数は変数var1から変数var2を差し引きます。 演算結果を変数resultに格納します。 成功時0を、エラー時-1を返します。

2つの numeric 型変数を乗算し、3番目の numeric 型変数に結果を格納します。

int PGTYPESnumeric_mul(numeric *var1, numeric *var2, numeric *result);

この関数は変数var1と変数var2を掛け合わせます。 演算結果を変数var3に格納します。 成功時0を、エラー時-1を返します。

2つの numeric 型変数で除算し、3番目の numeric 型変数に結果を格納します。

int PGTYPESnumeric_div(numeric *var1, numeric *var2, numeric *result);

この関数は変数var1を変数var2で割ります。 演算結果を変数var3に格納します。 成功時0を、エラー時-1を返します。

2つの numeric 型変数を比較します。

int PGTYPESnumeric_cmp(numeric *var1, numeric *var2)

この関数は2つの numeric 型変数を比較します。 エラーの場合INT_MAXが返ります。 成功時、この関数は以下のいずれかを返します:

• var1がvar2より大きければ1。

• var1がvar2より小さければ-1。

• var1がvar2と等しければ0。

int型変数を numeric 型変数に変換します。

int PGTYPESnumeric_from_int(signed int int_val, numeric *var);

この関数は符号付整数型の変数を受付け、numeric 型変数var内に格納します。 成功時0、失敗時-1が返ります。

long int型変数を numeric 型変数に変換します。

int PGTYPESnumeric_from_long(signed long int long_val, numeric *var);

この関数は符号付long int型の変数を受付け、numeric 型変数var内に格納します。 成功時0、失敗時-1が返ります。

numeric 型変数を他の numeric 型変数にコピーします。

int PGTYPESnumeric_copy(numeric *src, numeric *dst);

この関数は、srcが指し示す変数の値をdstが指し示す変数にコピーします。 成功時0、失敗時-1が返ります。

double型の変数を numeric 型変数に変換します。

int  PGTYPESnumeric_from_double(double d, numeric *dst);

この関数はdouble型の変数を受付け、変換結果をdstが指し示す変数内に格納します。 成功時0、失敗時-1が返ります。

numeric 型変数をdouble型に変換します。

int PGTYPESnumeric_to_double(numeric *nv, double *dp)

この関数はnvが指し示す numeric 型変数の値をdpが指し示すdouble型変数に変換します。 成功時0、オーバーフローを含むエラーが発生した時-1が返ります。 オーバーフローが発生した場合はさらに、グローバル変数errnoはPGTYPES_NUM_OVERFLOWに設定されます。

numeric 型変数をint型に変換します。

int PGTYPESnumeric_to_int(numeric *nv, int *ip);

この関数はnvが指し示す numeric 型変数の値をipが指し示す整数型変数に変換します。 成功時0、オーバーフローを含むエラーが発生した時-1が返ります。 オーバーフローが発生した場合はさらに、グローバル変数errnoはPGTYPES_NUM_OVERFLOWに設定されます。

numeric 型変数をlong型に変換します。

int PGTYPESnumeric_to_long(numeric *nv, long *lp);

この関数はnvが指し示す numeric 型変数の値をlpが指し示すlong変数に変換します。 成功時0、オーバーフローを含むエラーが発生した時-1が返ります。 オーバーフローが発生した場合はさらに、グローバル変数errnoはPGTYPES_NUM_OVERFLOWに設定されます。

numeric 型変数を decimal 型に変換します。

int PGTYPESnumeric_to_decimal(numeric *src, decimal *dst);

この関数はsrcが指し示す numeric 型変数の値をdstが指し示す decimal 型変数に変換します。 成功時0、オーバーフローを含むエラーが発生した時-1が返ります。 オーバーフローが発生した場合はさらに、グローバル変数errnoはPGTYPES_NUM_OVERFLOWに設定されます。

decimal 型変数を numeric 型に変換します。

int PGTYPESnumeric_from_decimal(decimal *src, numeric *dst);

この関数はsrcが指し示す decimal 型変数の値をdstが指し示す numeric 型変数に変換します。 成功時0、エラーが発生した時-1が返ります。 decimal 型は制限付の numeric 型として実装されていますので、この変換ではオーバーフローは起きません。

タイムスタンプから日付部分を取り出します。

date PGTYPESdate_from_timestamp(timestamp dt);

この関数は唯一の引数としてタイムスタンプを受付け、そこから日付部分を取り出します。

テキスト表現から日付型に変換します。

date PGTYPESdate_from_asc(char *str, char **endptr);

この関数はCのchar*型文字列strとCのchar*型文字列endptrへのポインタを受付けます。 現在ECPGは文字列全体を解析しますので、現時点では*endptrに最初の無効な文字のアドレスを格納することをサポートしません。 このためendptrを安全にNULLにすることができます。

この関数が常にMDY書式の日付を前提としている点に注意してください。 現在ECPGにはこれを変更するための変数がありません。

表33-2に許される入力書式を示します。

日付型変数のテキスト表現を返します。

char *PGTYPESdate_to_asc(date dDate);

この関数は唯一の引数として日付型dDateを受付けます。 この関数は1999-01-18、つまりYYYY-MM-DD書式で日付を出力します。

日付型の変数から、日、月、年の値を取り出します。

void PGTYPESdate_julmdy(date d, int *mdy);

この関数は日付型のdと、3つの整数値を持つ配列mdyへのポインタを受付けます。 この変数名はその並びを表し、mdy[0]には月数、mdy[1]には日数が、mdy[2]には年が入ります。

日付の日、月、年を指定した3つの整数からなる配列から日付値を作成します。

void PGTYPESdate_mdyjul(int *mdy, date *jdate);

この関数は、1番目の引数として3つの整数からなる配列(mdy)、2番目の引数として処理結果を格納する日付型の変数へのポインタを受付けます。

日付値から週内日数を表す数を返します。

int PGTYPESdate_dayofweek(date d);

この関数は唯一の引数としてdate型変数dを受付け、その日付の週内日数を表す整数を返します。

• 0 - 日曜

• 1 - 月曜

• 2 - 火曜

• 3 - 水曜

• 4 - 木曜

• 5 - 金曜

• 6 - 土曜

現在の日付を取得します。

void PGTYPESdate_today(date *d);

この関数は現在の日付に設定されるdate型変数(d)を指し示すポインタを受付けます。

date型変数を書式マスクを使用したテキスト表現に変換します。

int PGTYPESdate_fmt_asc(date dDate, char *fmtstring, char *outbuf);

この関数は変換対象のdate型(dDate)、書式マスク(fmtstring)、日付のテキスト表現を格納するための文字列(outbuf)を受付けます。

成功時に0、エラーが発生した場合は負の値が返ります。

以下のリテラルを使用して、フィールドを指定することができます。

• dd - 月内の日数。

• mm - 年内の月数。

• yy - 二桁表記の年数

• yyyy - 四桁表記の年数

• ddd - 日の名前（省略形）

• mmm - 月の名前（省略形）

他の文字はすべて出力文字列にそのままコピーされます。

表33-3にいくつかの可能性のある書式を示します。 この関数の使用法に関するアイディアを提供しています。 出力行はすべて同じ日付、1959年11月23日に基づいています。

書式マスクを使用してCのchar*文字列からdate型の値に変換します。

int PGTYPESdate_defmt_asc(date *d, char *fmt, char *str);

この関数は、処理結果を格納するための日付型へのポインタ(d)、日付を解析するための書式マスク(fmt)、日付のテキスト表現を含むCのchar*文字列(str)を受付けます。 テキスト表現は書式マスクに合った表現であることが仮定されています。 しかし、文字列と書式マスクを1:1に対応付けする必要はありません。 この関数は並んだ順番に解析し、年の位置を表すyyまたはyyyyを、月の位置を表すmmを、日の位置を表すddを検索します。

表33-4はいくつかの可能性のある書式を示します。 これはこの関数の使用方法に関するアイディアを提供します。

テキスト表現のタイムスタンプをタイムスタンプ型変数に変換します。

timestamp PGTYPEStimestamp_from_asc(char *str, char **endptr);

この関数は変換対象の文字列(str)とC char*へのポインタ(endptr)を受付けます。 現在ECPGは文字列全体を解析しますので、現時点では*endptrに最初の無効な文字の場所を格納をすることサポートしません。 このためendptrを安全に NULL にすることができます。

この関数は成功時変換後のタイムスタンプを返します。 エラー時、PGTYPESInvalidTimestampが返され、errnoがPGTYPES_TS_BAD_TIMESTAMPに設定されます。 この値についての重要な注意書きについてPGTYPESInvalidTimestampを参照してください。

通常、入力文字列には許される日付指定の任意の組み合わせ、空白文字、許される時間指定を含むことができます。 時間帯はECPGでサポートされていない点に注意してください。 変換することはできますが、例えばPostgreSQLサーバが行うような計算を行うことはできません。 時間帯指定は警告無しに無視されます。

表33-5に入力文字列の例をいくつか示します。

date型をC char*文字列に変換します。

char *PGTYPEStimestamp_to_asc(timestamp tstamp);

この関数はtimestamp型のtstampを唯一の引数として受付け、timestamp型のテキスト表現を含む割り当てられた文字列を返します。

現在のタイムスタンプを取り出します。

void PGTYPEStimestamp_current(timestamp *ts);

この関数は現在のタイムスタンプを取り出し、tsが指し示すtimestamp型変数に格納します。

書式マスクを使用してtimestamp型変数をC char*に変換します。

int PGTYPEStimestamp_fmt_asc(timestamp *ts, char *output, int str_len, char *fmtstr);

この関数は、最初の引数として変換対象のtimestamp型 (ts)を、出力バッファのポインタ(output)、出力バッファで割当て可能な最大長 (str_len)、変換に使用する書式マスク(fmtstr)を受付けます。

成功するとこの関数は0を返します。 エラーが発生した場合は負の値が返ります。

書式マスクには以下の書式指定を使用することができます。 書式指定はlibcのstrftime関数で使用されるものと同じです。 書式指定以外は出力バッファにコピーされます。

• %A - 各言語の曜日名称に置換されます。

• %a - 各言語の曜日略称に置換されます。

• %B - 各言語の月名称に置換されます。

• %b - 各言語の月略称に置換されます。

• %C - 年を100で割った10進数に置換されます。1桁の場合は先頭に0が付与されます。

• %c - 各言語の日付時刻表現に置換されます。

• %D - %m/%d/%yと同じです。

• %d - 月内の10進日数(01-31)に置換されます。

• %E* %O* - POSIXロケール拡張です。 %Ec %EC %Ex %EX %Ey %EY %Od %Oe %OH %OI %Om %OM %OS %Ou %OU %OV %Ow %OW %Oy という並びは別の表現を提供するものと仮定されています。

  さらに、%OBは、（日に関する仕様がない単体で使用される）別の月名を表すものとして実装されています。

• %e - 月内10進日数(1-31)に置換されます。1桁の場合は前に空白が付けられます。

• %F - %Y-%m-%dと同じです。

• %G - 世紀付の10進数として年に置換されます。 この年は週の部分がより多く含まれます。（月曜が週の最初の日です。）

• %g -%G同様に年に置換されますが、世紀の部分を除く10進数(00-99)になります。

• %H - 10進の時間(24時間単位)に置換されます(00-23)。

• %h - %bと同じです。

• %I - 10進の時間（12時間単位）に置換されます(01-12)。

• %j - 10進の年内日数に置換されます(001-366)。

• %k - 10進の時間(24時間単位)に置換されます(0-23)。1桁の場合は先頭に空白が付けられます。

• %l - 10進の時間（12時間単位）に置換されます(1-12)。1桁の場合は先頭に空白が付けられます。

• %M - 10進の分数に置換されます(00-59)。

• %m -10進の月数に置換されます(01-12)。

• %n - 改行に置換されます。

• %O* - %E*と同じです。

• %p - 各言語の"午前"または"午後"に適切に置換されます。

• %R - %H:%Mと同じです。

• %r - %I:%M:%S %pと同じです。

• %S - 10進の秒数に置換されます(00-60)。

• %s - エポック、UTCからの秒数に置換されます。

• %T - %H:%M:%Sと同じです。

• %t - タブに置換されます。

• %U - 10進の週番号（日曜が週の先頭です）に置換されます。

• %u - 10進の週番号（月曜が週の先頭です）に置換されます。

• %V - 10進の年内の週番号（月曜が週の先頭です）に置換されます(01-53)。 新しい年で、1月1日を含む週が4日以上存在する場合、その週が1となります。 さもなくば、この週は前年の週となり、次の週が1となります。

• %v - %e-%b-%Yと同じです。

• %W - 10進の年内の週番号（月曜が週の先頭です）に置換されます(00-53)。

• %w - 10進の週内日数（日曜が週の先頭です）に置換されます(0-6)。

• %X - 各言語の時間表現に置換されます。

• %x - 各言語の日付表現に置換されます。

• %Y - 10進の世紀付年に置換されます。

• %y - 10進の世紀なし年に置換されます(00-99)。

• %Z - 時間帯名称に置換されます。

• %z - UTCからの時間帯オフセットに置換されます。 UTCより東では正符号が先頭に付き、西では負符号が付きます。 それぞれ2桁の時間と分がその後に続きますが、その区切りはありません。（この形式はRFC 822の日付ヘッダでよく使用されます。）

• %+ - 各言語の日付時刻表現に置換されます。

• %-* - GNU libc拡張です。数値出力を行う際に何も文字を詰めません。

• $_* - GNU libcの拡張です。明示的に空白文字を使用して文字を詰めます。

• %0* - GNU libcの拡張です。明示的に0を使用して文字を詰めます。

• %% - %に置換されます。

タイムスタンプの減算を行い、その結果をinterval型の変数に格納します。

int PGTYPEStimestamp_sub(timestamp *ts1, timestamp *ts2, interval *iv);

この関数はts1が指し示すタイムスタンプ型変数からts2が指し示すタイムスタンプ型変数を差し引き、ivが指し示すinterval型変数に結果を格納します。

成功すると、この関数は0を返し、エラーが発生した場合は負の値を返します。

書式マスクを使用して、テキスト表現からtimestamp値へ変換します。

int PGTYPEStimestamp_defmt_asc(char *str, char *fmt, timestamp *d);

この関数はstr変数内に格納されたタイムスタンプのテキスト表現、fmt変数内に格納された使用される書式マスクを受付けます。 結果はdが指し示す変数内に格納されます。

書式マスクfmtが NULL ならば、この関数はデフォルトの書式マスク%Y-%m-%d %H:%M:%Sを使用するようになります。

これはPGTYPEStimestamp_fmt_asc関数の逆です。 使用できる書式マスク項目についてはその文書を参照してください。

timestamp型変数にinterval型変数を加算します。

int PGTYPEStimestamp_add_interval(timestamp *tin, interval *span, timestamp *tout);

この関数はtimestamp型変数tinへのポインタとinterval型変数spanへのポインタを受付けます。 これは、interval値をtimestamp値に加算し、その結果のtimestamp値をtoutが指し示す変数に格納します。

成功するとこの関数は0を返します。 エラーが発生した場合は負の値を返します。

timestamp型変数からinterval型変数の値を引きます。

int PGTYPEStimestamp_sub_interval(timestamp *tin, interval *span, timestamp *tout);

この関数はtinが指し示すtimestamp型変数からspanが指し示すinterval型変数を引きます。 結果はtoutが指し示す変数に保存されます。

成功するとこの関数は0を、エラーが発生した場合は負の値を返します。

新しく割り当てたinterval型変数へのポインタを返します。

interval *PGTYPESinterval_new(void);

以前に割り当てられたinterval型変数のメモリを解放します。

void PGTYPESinterval_new(interval *intvl);

テキスト表現からinterval型に変換します。

interval *PGTYPESinterval_from_asc(char *str, char **endptr);

この関数は入力文字列strを変換し、割当てられたinterval型へのポインタを返します。 現在ECPGは文字列全体を解析しますので、現時点では*endptrに最初の無効な文字のアドレスを格納することをサポートしません。 このためendptrを安全に NULL にすることができます。

interval型変数をテキスト表現に変換します。

char *PGTYPESinterval_to_asc(interval *span);

この関数はspanが指し示すinterval型変数をC char*に変換します。 出力は@ 1 day 12 hours 59 mins 10 secsのようになります。

interval型変数をコピーします。

int PGTYPESinterval_copy(interval *intvlsrc, interval *intvldest);

この関数は、intvlsrcが指し示すinterval型変数を intvldestが指し示す変数にコピーします。 事前に格納先の変数用のメモリを割り当てる必要があることに注意してください。

新しく割り当てられたdecimal型変数へのポインタを要求します。

decimal *PGTYPESdecimal_new(void);

decimal型を解放し、そのメモリをすべて解放します。

void PGTYPESdecimal_free(decimal *var);

引数はnumeric型変数（またはnumeric型変数へのポインタ）を含んでいるはずですが、実際のメモリ上の表現は無効でした。

オーバーフローが発生しました。 numeric型はほぼ任意の精度を扱うことができますので、numeric型変数から他の型への変換ではオーバーフローが発生する可能性があります。

アンダーフローが発生しました。 numeric型はほぼ任意の精度を扱うことができますので、numeric型変数から他の型への変換ではアンダーフローが発生する可能性があります。

ゼロ除算をしようとしました。

PGTYPESdate_from_asc関数に無効な日付文字列が渡されました。

PGTYPESdate_defmt_asc関数に無効な引数が渡されました。

PGTYPESdate_defmt_asc関数により入力文字列内に無効なトークンが見つかりました。

PGTYPESinterval_from_asc関数に無効な内部文字列が渡されました。 もしくはPGTYPESinterval_to_asc関数に無効な内部値が渡されました。

PGTYPESdate_defmt_asc関数内の日/月/年の代入において不整合がありました。

PGTYPESdate_defmt_asc関数により無効な月内日数が見つかりました。

PGTYPESdate_defmt_asc関数によって無効な月値が見つかりました。

PGTYPEStimestamp_from_asc関数に無効なタイムスタンプ文字列が渡されました。 もしくはPGTYPEStimestamp_to_asc関数に無効なtimestamp値が渡されました。

コンテキスト内で扱うことができない、無限なタイムスタンプ値がありました。

無効なタイムスタンプを表すtimestamp型の値です。 これは解析エラーの場合にPGTYPEStimestamp_from_asc関数によって返されます。 timestampデータ型の内部表現のため、PGTYPESInvalidTimestampはまた同時に有効なタイムスタンプでもあります。 これは1899-12-31 23:59:59に設定されます。 エラーを検知するためには、PGTYPEStimestamp_from_ascを呼び出す度にその後、PGTYPESInvalidTimestampを試験するだけではなく、errno != 0も試験してください。