13.33 Timestampクラス

このクラスは、SQLの標準TIMESTAMP WITH TIME ZONE型とTIMESTAMP WITHOUT TIME ZONE型をサポートしており、すべてのデータベースのTIMESTAMP型(TIMESTAMP、TIMESTAMP WITH TIME ZONEおよびTIMESTAMP WITH LOCAL TIME ZONE)で動作します。

時、分、秒、小数秒など、Timestampの時間コンポーネントはTimestampに対して指定されたタイム・ゾーンのものです。これはリリース10gの新しい動作であり、以前のバージョンでは時間コンポーネントのGMT値がサポートされていました。時間コンポーネントは、データベースへの格納時にTimestampで指定されたタイム・ゾーンにのみ変換されました。たとえば、次のTimestamp()のコールでは、Timestamp値13-Nov 2003 17:24:30.0がタイム・ゾーン+5:30で作成されます。

Timestamp ts(env, 2003, 11, 13, 17, 24, 30, 0, 5, 30);

以前のリリースの場合、このコールの動作ではタイムスタンプ・コンポーネントがGMTとして解析され、タイム・ゾーン+5:30のタイムスタンプ値13-Nov 2003 11:54:30.0が作成されていました。コンストラクタをコールする前に、このタイムスタンプをGMTに変換する必要がありました。GMTタイム・ゾーンの場合、時と分はどちらも0 (ゼロ)です。

この動作変更は、setDate()メソッドとsetTime()メソッドにも適用されます。

表13-49は、Timestampクラスのフィールドとその有効範囲を示しています。パラメータが範囲外の場合はSQLExceptionが発生します。

表13-49 Timestampのフィールドとその有効範囲

フィールド	型	最小値	最大値
year	int	-4713	9999
month	unsigned int	1	12
day	unsigned int	1	31
hour	unsigned int	0	23
min	unsigned int	0	59
sec	unsigned int	0	61
tzhour	int	-12	14
tzmin	int	-59	59

表13-50 Timestampメソッドの概要

メソッド	概要
Timestamp()	Timestampクラスのコンストラクタです。
fromText()	文字列で指定されている値からタイムスタンプを設定します。
getDate()	Timestampオブジェクトから日付を取得します。
getTime()	TimeStampオブジェクトから時刻を取得します。
getTimeZoneOffset()	タイム・ゾーンの時および分のオフセット値を戻します。
intervalAdd()	値(タイムスタンプの値+時間隔)が設定されたTimestampオブジェクトを戻します。
intervalSub()	値(タイムスタンプの値-時間隔)が設定されたTimestampオブジェクトを戻します。
isNull()	TimestampがNULLかどうかをチェックします。
operator=()	単純割当てを行います。
operator==()	aとbが等しいかどうかをチェックします。
operator!=()	aとbが等しくないかどうかをチェックします。
operator>()	aがbを超えているかどうかをチェックします。
operator>=()	aがb以上かどうかをチェックします。
operator<()	aがb未満かどうかをチェックします。
operator<=()	aがb以下かどうかをチェックします。
setDate()	このタイムスタンプの年、月、日のコンポーネントを設定します。
setNull()	Timestampの値をNULLに設定します。
setTime()	このタイムスタンプの日、時、分、秒および小数秒の要素を設定します。
setTimeZoneOffset()	タイム・ゾーンの時および分のオフセットを設定します。
subDS()	タイムスタンプの値-valを示すIntervalDSを戻します。
subYM()	タイムスタンプの値-valを示すIntervalYMを戻します。
toText()	タイムスタンプを示すstringを、指定された書式で戻します。

13.33.1 Timestamp()

Timestampクラスのコンストラクタです。

構文	説明
Timestamp(    const Environment *env,    int year=1,    unsigned int month=1,    unsigned int day=1,    unsigned int hour=0,    unsigned int min=0,    unsigned int sec=0,    unsigned int fs=0,    int tzhour=0,    int tzmin=0);	デフォルトのTimestampオブジェクトを戻します。時間コンポーネントは指定したタイム・ゾーンのものと認識されます。
Timestamp();	NULLのTimestampオブジェクトを戻します。NULLのタイムスタンプは、fromText()メソッドを割り当てるか、コールすることによって初期化できます。NULLのTimestampオブジェクトに対してコールできるメソッドは、setNull()、isNull()およびoperator=()です。
Timestamp(    const Environment *env,    int year,    unsigned int month,    unsigned int day,    unsigned int hour,    unsigned int min,    unsigned int sec,    unsigned int fs,    const string &timezone);	これはマルチバイト・サポート用です。タイム・ゾーンは、リージョンUS/EasternまたはGMTからのオフセット+05:30として渡すことができます。空の文字列を渡すと、時刻は現行のセッションのタイム・ゾーンによるものとみなされます。この構文は、TIMESTAMP WITH LOCAL TIME ZONE型の値の作成に使用します。
Timestamp(    const Environment *env,    int year,    unsigned int month,    unsigned int day,    unsigned int hour,    unsigned int min,    unsigned int sec,    unsigned int fs,    const UString &timezone);	UTF16 (UString)のサポート用です。タイム・ゾーンは、リージョンUS/EasternまたはGMTからのオフセット+05:30として渡すことができます。空の文字列を渡すと、時刻は現行のセッションのタイム・ゾーンによるものとみなされます。この構文は、TIMESTAMP WITH LOCAL TIME ZONE型の値の作成に使用します。
Timestamp(    const Timestamp &src);	コピー・コンストラクタです。

パラメータ	説明
year	年のコンポーネントを指定します。
month	月のコンポーネントを指定します。
day	日のコンポーネントを指定します。
hour	時のコンポーネントを指定します。
minute	分のコンポーネントを指定します。
second	秒のコンポーネントを指定します。
fs	小数秒のコンポーネントを指定します。
tzhour	タイム・ゾーンの時差のコンポーネントを指定します。
tzmin	タイム・ゾーンの分の違いのコンポーネントを指定します。
src	元のTimezoneです。

例13-11 デフォルトのTimestampコンストラクタの使用

この例では、デフォルト・コンストラクタによるNULL値の作成と、TimestampにNULL以外の値を割り当て、それに基づいて操作を実行する方法が示されています。

Environment *env = Environment::createEnvironment();

//create a null timestamp
Timestamp ts;
if(ts.isNull())
   cout << "\n ts is Null";

//assign a non null value to ts
Timestamp notNullTs(env, 2000, 8, 17, 12, 0, 0, 0, 5, 30);
ts = notNullTs;

//now all operations are valid on ts
int yr;
unsigned int mth, day;
ts.getDate(yr, mth, day);

例13-12 NULLのTimestampインスタンスを初期化するためのfromText()メソッドの使用

次のコード例では、NULLのタイムスタンプを初期化するためにfromText()メソッドを使用する方法が示されています。

Environment *env = Environment::createEnvironment();

Timestamp ts1;
ts1.fromText("01:16:17.12 04/03/1825", "hh:mi:ssxff dd/mm/yyyy", "", env);

例13-13 データベースに格納されているタイムスタンプの比較

次のコード例では、結果セットからタイムスタンプ列を取得してタイムスタンプがNULLかどうかをチェックし、文字列フォーマットでタイムスタンプの値を取得して2つのタイムスタンプの差異を判断する方法が示されています。

Timestamp reft(env, 2001, 1, 1);
ResultSet *rs=stmt->executeQuery(
   "select order_date from orders where customer_id=1");
rs->next();

//retrieve the timestamp column from result set
Timestamp ts=rs->getTimestamp(1);

//check timestamp for null
if(!ts.isNull())
{
   string tsstr=ts.toText(           //get the timestamp value in string format
      "dd/mm/yyyy hh:mi:ss [tzh:tzm]",0);
   if(reft<ts                        //compare timestamps
      IntervalDS ds=reft.subDS(ts);  //get difference between timestamps
}

13.33.2 fromText()

文字列で指定されている値からタイムスタンプを設定します。文字列は指定された書式であることが必要です。nlsParamが指定されている場合は、この指定によって、変換に使用されるNLSパラメータが決まります。nlsParamが指定されていない場合、NLSパラメータは指定された環境から選択されます。環境が指定されていない場合、グローバリゼーション・サポート・パラメータはインスタンスに関連付けられている環境から選択されます(関連付けられている場合)。

TimestampオブジェクトをstringまたはUStringが表す値に設定します。

値はfmtおよびnlsParamパラメータに基づいて解析されます。nlsParamが渡されない場合は、envpパラメータのグローバリゼーション・サポート設定が使用されます。

関連項目:

TO_DATEの詳細は、『Oracle Database SQL言語リファレンス』を参照してください。

構文	説明
void fromText(    const string &timestmpStr,    const string &fmt,    const string &nlsParam = "",    const Environment *env = NULL);	Timestampオブジェクトをstringが表す値に設定します。
void fromText(    const UString &timestmpStr,    const UString &fmt,    const UString &nlsParam,    const Environment *env = NULL);	TimestampオブジェクトをUStringが表す値に設定します。これはグローバリゼーション対応の場合です。

パラメータ	説明
timestmpStr	Timestampオブジェクトに変換するタイムスタンプのstringまたはUStringを指定します。
fmt	書式文字列を指定します。
nlsParam	NLSパラメータ文字列を指定します。nlsParamが指定されている場合は、この指定によって、変換に使用されるNLSパラメータが決まります。nlsParamが指定されていない場合は、NLSパラメータがenvpから選択されます。
env	OCCI環境を指定します。グローバリゼーション対応バージョンのメソッドでは、timestampStrの解析に使用するNLS_CALENDARの判別に使用します。envを渡されなければ、オブジェクトに関連付けられている環境により設定が制御されます。NULLのTimestampオブジェクトでコールする場合は、NULL以外の値にします。

13.33.3 getDate()

Timestampの年、月および日の値を戻します。

構文

void getDate(
   int &year,
   unsigned int &month,
   unsigned int &day) const;

パラメータ	説明
year	年のコンポーネントを指定します。
month	月のコンポーネントを指定します。
day	日のコンポーネントを指定します。

13.33.4 getTime()

時、分、秒および小数秒のコンポーネントを戻します。

構文

void getTime(
   unsigned int &hour,
   unsigned int &minute,
   unsigned int &second,
   unsigned int &fs) const;

パラメータ	説明
hour	時のコンポーネントを指定します。
minute	分のコンポーネントを指定します。
second	秒のコンポーネントを指定します。
fs	小数秒のコンポーネントを指定します。

13.33.5 getTimeZoneOffset()

タイム・ゾーン・オフセットを時および分で戻します。

構文

void getTimeZoneOffset(
   int &hour,
   int &minute) const;

パラメータ	説明
hour	タイム・ゾーンの時を指定します。
minute	タイム・ゾーンの分を指定します。

13.33.6 intervalAdd()

タイムスタンプに時間隔を加算します。

構文	説明
const Timestamp intervalAdd(    const IntervalDS& val) const;	タイムスタンプにIntervalDSの時間隔を加算します。
const Timestamp intervalAdd(    const IntervalYM& val) const;	タイムスタンプにIntervalYMの時間隔を加算します。

パラメータ	説明
val	加算する時間隔です。

13.33.7 intervalSub()

タイムスタンプから時間隔を減算し、その結果をタイムスタンプで戻します。Timestampをタイムスタンプの値- valの値で戻します

構文	説明
const Timestamp intervalSub(    const IntervalDS& val) const;	タイムスタンプからIntervalDSの時間隔を減算します。
const Timestamp intervalsUB(    const IntervalYM& val) const;	タイムスタンプからIntervalYMの時間隔を減算します。

パラメータ	説明
val	減算する時間隔を指定します。

13.33.8 isNull()

TimestampがNULLの場合はTRUEを、それ以外の場合はFALSEを戻します。

構文

bool isNull() const;

13.33.9 operator=()

指定されたTimestampオブジェクトをこのオブジェクトに割り当てます。

構文

Timestamp & operator=(
   const Timestamp &src);

パラメータ	説明
src	割り当てる値を指定します。

13.33.10 operator==()

指定した2つのタイムスタンプを比較します。2つのタイムスタンプが等しい場合はTRUEを、それ以外の場合はFALSEを戻します。aまたはbがNULLの場合は、FALSEを戻します。

構文

bool operator==(
   const Timestamp &first,
   const Timestamp &second);

パラメータ	説明
first	比較対象の最初のタイムスタンプを指定します。
second	比較対象の第2のタイムスタンプを指定します。

13.33.11 operator!=()

指定した2つのタイムスタンプを比較します。2つのタイムスタンプが等しくない場合はTRUEを、それ以外の場合はFALSEを戻します。どちらかのタイムスタンプがNULLの場合はFALSEを戻します。

構文

bool operator!=(
   const Timestamp &first,
   const Timestamp &second);

パラメータ	説明
first	比較対象の最初のタイムスタンプを指定します。
second	比較対象の第2のタイムスタンプを指定します。

13.33.12 operator>()

firstがsecondより後の場合はTRUEを、それ以外の場合はFALSEを戻します。どちらかのタイムスタンプがNULLの場合はFALSEを戻します。

構文

bool operator>(
   const Timestamp &first,
   const Timestamp &second);

パラメータ	説明
first	比較対象の最初のタイムスタンプを指定します。
second	比較対象の第2のタイムスタンプを指定します。

13.33.13 operator>=()

指定した2つのタイムスタンプを比較します。firstタイムスタンプがsecondタイムスタンプ以降の場合はTRUEを、それ以外の場合はFALSEを戻します。どちらかのタイムスタンプがNULLの場合はFALSEを戻します。

構文

bool operator>=(
   const Timestamp &first,
   const Timestamp &second);

パラメータ	説明
first	比較対象の最初のタイムスタンプを指定します。
second	比較対象の第2のタイムスタンプを指定します。

13.33.14 operator<()

firstがsecondより前の場合はTRUEを、それ以外の場合はFALSEを戻します。aまたはbがNULLの場合は、FALSEを戻します。

構文

bool operator<(
   const Timestamp &first,
   const Timestamp &second);

パラメータ	説明
first	比較対象の最初のタイムスタンプを指定します。
second	比較対象の第2のタイムスタンプを指定します。

13.33.15 operator<=()

指定した2つのタイムスタンプを比較します。第1のタイムスタンプが第2のタイムスタンプと同じか、またはそれ以前の場合はTRUEを、それ以外の場合はFALSEを戻します。どちらかのタイムスタンプがNULLの場合はFALSEを戻します。

構文

bool operator<=(
   const Timestamp &first,
   const Timestamp &second);

パラメータ	説明
first	比較対象の最初のタイムスタンプを指定します。
second	比較対象の第2のタイムスタンプを指定します。

13.33.16 setDate()

このタイムスタンプの年、月、日の要素を設定します。

構文

void setDate(
   int year,
   unsigned int month,
   unsigned int day);

パラメータ	説明
year	年のコンポーネントを指定します。有効な値は、-4713から9999です。
month	月のコンポーネントを指定します。有効な値は、1から12です。
day	日のコンポーネントを指定します。有効な値は、1から31です。

13.33.17 setNull()

タイムスタンプをNULLに設定します。

構文

void setNull();

13.33.18 setTime()

このタイムスタンプの日、時、分、秒および小数秒の要素を設定します。

構文

void setTime(
   unsigned int hour,
   unsigned int minute,
   unsigned int second,
   unsigned int fs);

パラメータ	説明
hour	時のコンポーネントを指定します。有効な値は、0から23です。
minute	分のコンポーネントを指定します。有効な値は、0から59です。
second	秒のコンポーネントを指定します。有効な値は、0から59です。
fs	小数秒のコンポーネントを指定します。

13.33.19 setTimeZoneOffset()

タイム・ゾーンの時および分のオフセットを設定します。

構文

void setTimeZoneOffset(
   int hour,
   int minute);

パラメータ	説明
hour	タイム・ゾーンの時を指定します。有効な値は、-12から12です。
minute	タイム・ゾーンの分を指定します。有効な値は、-59から59です。

13.33.20 subDS()

このタイムスタンプと指定されたタイムスタンプとの差を計算し、その差をIntervalDSで戻します。

構文

const IntervalDS subDS(
   const Timestamp& val) const; 

パラメータ	説明
val	減算するタイムスタンプを指定します。

13.33.21 subYM()

2つのタイムスタンプの値の差を計算し、その差をIntervalYMで戻します。

構文

const IntervalYM subYM(
   const Timestamp& val) const;

パラメータ	説明
val	減算するTimestampを指定します。

13.33.22 toText()

タイムスタンプを表すstringまたはUStringを、指定された書式で戻します。

nlsParamが指定されている場合は、この指定によって、変換に使用されるNLSパラメータが決まります。nlsParamが指定されていない場合は、NLSパラメータがインスタンスに関連付けられている環境から選択されます(関連付けられている場合)。

関連項目:

TO_DATEの詳細は、『Oracle Database SQL言語リファレンス』を参照してください。

構文	説明
string toText(    const string &fmt,    unsigned int fsprec,    const string &nlsParam = "") const;	タイムスタンプを示すstringを、指定された書式で戻します。
UString toText(    const UString &fmt,    unsigned int fsprec,    const UString &nlsParam) const;	タイムスタンプを表すUStringを、指定された書式で戻します。グローバリゼーション対応の場合です。

パラメータ	説明
fmt	書式文字列を指定します。
fsprec	Timestampの小数秒コンポーネントの精度を指定します。
nlsParam	NLSパラメータ文字列を指定します。nlsParamが指定されている場合は、この指定によって、変換に使用されるNLSパラメータが決まります。nlsParamが指定されていない場合は、NLSパラメータがenvpから選択されます。