Notes C API探訪: TIMEDATE(データ型)その2

その1はこちらです。

繰り返しになりますが、TIMEDATE型は日時データ型です。今回は日時データを操作するための関数を紹介します。

BOOL LNPUBLIC TimeDateAdjust (
  TIMEDATE far *Time,
  int seconds,
  int minutes,
  int hours,
  int days,
  int months,
  int years);

TimeDateAdjust

TimeDateAdjust関数は、Timeで受け取った日時を、秒、分、時、日、月、年の単位で一括調整します。戻り値は、成功時にFALSEを返します。

int LNPUBLIC TimeDateCompare (const TIMEDATE far *t1, const TIMEDATE far *t2);
int LNPUBLIC TimeDateCollate (const TIMEDATE far *t1, const TIMEDATE far *t2);
#define TimeDateEqual(a,b) ((BOOL)TimeDateCollate(a,b)==0)

TimeDateCompare、TimeDateCollate、TimeDateEqual

TimeDateCompare関数、TimeDateCollate関数ともに2つの日時を比較します。t1よりt2が大きければ-1、小さければ1、等値なら0を返します。TimeDateEqualマクロは2つの日時が等値かどうかを返します。
2つの関数の違いはワイルドカードの扱いです。日時におけるワイルドカードとは、日付部分と時刻部分で「なんらかの時間」を表すものです。日付にワイルドカードが指定されている場合、「****/**/** 12:34:56」みたいなイメージです。時刻にワイルドカードが指定されている場合は、「2021/12/24 **:**:**」みたいなイメージになります。日時にワイルドカード値が含まれていると、TimeDateCollate関数では正しく比較できませんが、高速に動作します(等値はワイルドカードを含んでいても動作します)。逆にTimeDateCompare関数はワイルドカードが指定されていても正しく比較できますが、その分処理が遅くなります。

LONG LNPUBLIC TimeDateDifference (
  const TIMEDATE far *t1,
  const TIMEDATE far *t2);
void LNPUBLIC TimeDateDifferenceFloat (
  const TIMEDATE far *t1,
  const TIMEDATE far *t2,
  NUMBER far *difference);

TimeDateDifference、TimeDateDifferenceFloat

TimeDateDifference関数、TimeDateDifferenceFloat関数は、ともに2つの日時の差を秒数で返します。前者はLONG値、後者はNUMBER型(実体は倍精度小数点数)で返します。t1からt2を引いて計算するので、t1が大きい場合は正の数、t2が大きい場合は負の数になります。なお、タイムゾーンが異なる場合は共通化されます。

STATUS LNPUBLIC TimeDateIncrement (TIMEDATE far *Time, LONG Interval);

TimeDateIncrement

TimeDateIncrement関数は、Timeで与えられた日時を増減させます。Interval値は10ms単位で指定するので、100なら1秒、6,000なら1分、360,000なら1時間になります。戻り値はSTATUS型です。失敗の要因としては、時刻にワイルドカードが指定されていると、ERR_TREQというエラー値を返します。

#define	TIMEDATE_MINIMUM	0
#define	TIMEDATE_MAXIMUM	1
#define	TIMEDATE_WILDCARD	2
void LNPUBLIC TimeConstant(WORD, TIMEDATE far *);

TimeConstant

TimeConstant関数は特殊な日時定数を返します。
第1引数にTIMEDATE_MINIMUMを渡すと、日時のヌル値のような値を返します。
TIMEDATE_MAXIMUMを渡すと、日時の最大値を返します。
TIMEDATE_WILDCARDを渡すと、日付、時刻ともにワイルドカード化された日時値を返します。ちなみに、日付のワイルドカード値はANYDAY、時刻のワイルドカードはALLDAYという名前の定数になっています。