ワークスペースにおいて文字列式を設定できる場所では、ここで掲げる関数を使うことにより、ある時点を示す「時間位置: temporal」（日付: date、時刻: time、日付時刻: datetime の総称。「日付/時刻」も同じ意味で用います）の計算や書式変更などを行うことができます。
明示的に書式を指定する場合を除き、「時間位置: temporal」は FME標準日付/時刻書式、2つの時間位置の間の差分を示す「時間間隔: interval」はISO8601に基づく時間間隔の標準書式（後述）によって表されるものとします。
@DateTimeParse 関数および @DateTimeFormat 関数において指定する変換前/変換後の日付/時刻書式は、日付/時刻書式指定子の組み合わせによる書式指定文字列によって指定します。
引数の値が有効範囲外である場合、あるいは書式が無効である場合、日付/時刻関数は原則として null を返します。ただし、@DateTimeParse 関数だけは、有効範囲を超える月、日、時、分、秒を繰り上げることによって有効範囲内の値に修復 (repair) するオプション機能を持っています。例えば、@DateTimeParse(20161332,%Y%m%d,repair) は “20161332” を修復して “20170201” を返します。この修復機能は、センサーなどが機械的に生成した有効範囲外の要素を含む時間位置を修正する場合などに効果的に使用できます。
関数名や日付/時刻の書式を指定する文字列では大文字と小文字が区別されますが、@DateTimeDiff 関数の <intervalType> など、特定の文字列を指定する引数では大文字と小文字は区別されません。
| 構文と概要 | 例 (式 = 式が返す値) |
|---|---|
[時間位置への時間間隔の加算]@DateTimeAdd(<temporal>,<interval>)<temporal> (時間位置) に <interval> (時間間隔) を加算した時間位置を返す。 時間間隔の先頭にマイナス記号がついているときは、減算 (負の時間間隔の加算) が行われる。 | @DateTimeAdd(20170102000000,P1M5DT9H30M) = 20170207093000 @DateTimeAdd(000000,PT9H30M) = 093000 @DateTimeAdd(20170102,P1M5D) = 20170207 @DateTimeAdd(20170102,-P1M5D) = 20161127 |
[時間位置の型変換]@DateTimeCast(<temporal>,<temporalType>)<temporal> を <temporalType> に指定した型 (date, time, または datetime) の値に変換して返す。 | @DateTimeCast(20170301081530,date) = 20170301 @DateTimeCast(20170301081530,time) = 081530 @DateTimeCast(20170301,datetime) = 20170301000000 ※日付 (date) は、時刻を 000000 とした日付時刻 (datetime) に変換できる。 @DateTimeCast(081530,datetime) = null ※時刻 (time) は、日付時刻 (datetime) に変換できない。 |
[時間位置の作成]@DateTimeCreate(<year>,<month>,<day>,<hours>,<minitues>,<seconds>,<offset>)引数で指定された年、月、日、時、分、秒を示す時間位置を返す。 <offset> に UTC (協定世界時) との時差を符号付きの値で指定すると、タイムゾーン指定子を付加した値が得られる。 <offset> の書式は (+|-)hh, (+|-)hhmm, または (+|-)hh:mm とし、タイムゾーン指定子が不要な場合は空文字列 “” とする。 | @DateTimeCreate(2017,1,2,12,30,0,+09) = 20170102123000+09:00 @DateTimeCreate(2017,1,2,12,30,0,-0330) = 20170102123000-03:30 @DateTimeCreate(2017,1,2,12,30,0,””) = 20170102123000 |
[2つの時間位置間の差分 (時間間隔) 計算]@DateTimeDiff(<endTemporal>,<startTemporal>[,<intervalType>])<endTemporal> (終了時間位置) から <startTemporal> (開始時間位置) を引いた時間間隔を返す。 結果として得られる時間間隔の書式や単位は、<intervalType> に指定する文字列 (次のいずれかひとつ) によって異なる。 interval: 時間間隔の標準書式 years: 小数点数 [年] months: 小数点数 [月] weeks: 小数点数 [週] days: 小数点数 [日] hours: 小数点数 [時] minutes: 小数点数 [分] seconds: 小数点数 [秒] | @DateTimeDiff(20170201,20170101,interval) = P1M @DateTimeDiff(20170201,20170101,years) = 0.083333333333333329 @DateTimeDiff(20170201,20170101,months) = 1 @DateTimeDiff(20170201,20170101,weeks) = 4.4285714285714288 @DateTimeDiff(20170201,20170101,days) = 31 @DateTimeDiff(20170201,20170101,hours) = 744 @DateTimeDiff(20170201,20170101,minutes) = 44640 @DateTimeDiff(20170201,20170101,seconds) = 2678400 @DateTimeDiff(20170201,20170101) = P1M ※’interval’ の指定は省略しても良い。 |
[時間位置の書式設定]@DateTimeFormat(<temporal>,<format>)<temporal> を <format> で指定した書式による日付、時刻、または日付時刻文字列を返す。 | @DateTimeFormat(20170301081530,%Y-%m-%d) = 2017-03-01 @DateTimeFormat(20170301,%Y-%m-%d) = 2017-03-01 @DateTimeFormat(20170301081530,%H:%M:%S) = 08:15:30 @DateTimeFormat(081530,%H:%M:%S) = 08:15:30 @DateTimeFormat(20170301081530,%Y-%m-%d %H:%M:%S) = 2017-03-01 08:15:30 |
[時間間隔の作成]@DateTimeIntervalCreate(<years>,<months>,<days>,<hours>,<minitues>,<seconds>[,<sign>])引数で指定された年数、月数、日数、時間数、分数、秒数を示す時間間隔を返す。 年数～分数は0以上の整数、秒数は0以上の小数点数（小数点以下9桁まで有効）とする。 <sign> (符号) を省略または + を指定したときは正、- を指定したときは負の時間間隔となる。 | @DateTimeIntervalCreate(1,2,3,4,5,6) = P1Y2M3DT4H5M6S @DateTimeIntervalCreate(1,2,3,4,5,6,+) = P1Y2M3DT4H5M6S @DateTimeIntervalCreate(1,2,3,4,5,6,-) = -P1Y2M3DT4H5M6S @DateTimeIntervalCreate(-1,2,-3,4,5,6) = null ※負の年数等は無効。 @DateTimeIntervalCreate(1,2,3,4,5,6,x) = null ※+, – 以外の <sign> は無効。 |
[時間間隔の正負の逆転]@DateTimeIntervalNegate(<interval>)<interval> (時間間隔) と正負が逆の時間間隔を返す。 | @DateTimeIntervalNegate(P1Y2M3DT4H5M6S) = -P1Y2M3DT4H5M6S @DateTimeIntervalNegate(-P1Y2M3DT4H5M6S) = P1Y2M3DT4H5M6S |
[現在の時間位置の取得]@DateTimeNow([<offsetType>])<offsetType> の指定に応じて、関数実行時点における次の日付時刻を返す。 指定なし: ローカル時刻 (タイムゾーン指定子なし) local: ローカル時刻 (タイムゾーン指定子あり) utc: UTC (協定世界時) 時刻 (タイムゾーン指定子あり) | 日本のタイムゾーン (UTC+09:00) に設定されているシステムで日本時間 2017年3月1日 9:00 ちょうどに実行した場合 @DateTimeNow() = 20170301090000 @DateTimeNow(local) = 20170301090000+09:00 @DateTimeNow(utc) = 20170301000000+00:00 |
[書式つき時間位置の解析]@DateTimeParse(<string>,<format>[,<mode>])<format> (書式) よってある時間位置を表している <string> (文字列) を解析し、FME標準書式の時間位置に変換する。 <mode> に文字列 ‘repair’ を指定した場合は、<string> 内の時間位置の各要素を検証し、有効範囲を超える月、日、時、分、秒があったときは適宜繰り上げることによって有効範囲内の値になるように修復する。 | @DateTimeParse(2017-02-28,%Y-%m-%d) = 20170228 @DateTimeParse(2017-02-29,%Y-%m-%d) = null ※2017年は閏年でないので2月29日は無効。 @DateTimeParse(2017-02-29,%Y-%m-%d,repair) = 20170301 ※<mode> に ‘repair’ を指定すると有効な日付に修復される。 |
[タイムゾーンの取得]@TimeZoneGet(<temporal>)<temporal> (タイムゾーン指定子つきの日付時刻または時刻) のタイムゾーン指定子を返す。 | @TimeZoneGet(083000+09) = +09:00 |
[タイムゾーンの削除]@TimeZoneRemove(<temporal>)<temporal> (タイムゾーン指定子つきの日付時刻または時刻) からタイムゾーン指定子を削除した日付時刻または時刻を返す。 | @TimeZoneRemove(083000+09) = 083000 |
[タイムゾーンの設定または変換]@TimeZoneSet(<temporal>,<offset>)<temporal> がタイムゾーン指定子なしの日付時刻または時刻である場合は、<offset> に指定したタイムゾーン指定子つきの日付時刻または時刻を返す。 <temporal> がタイムゾーン指定子つきの日付時刻または時刻である場合は、<offset> に指定したタイムゾーンに変換した日付時刻または時刻を返す。 | @TimeZoneSet(083000,+09:00) = 083000+09:00 @TimeZoneSet(083000-03:00,+09:00) = 203000+09:00 @TimeZoneSet(083000-03:00,utc) = 113000+00:00 ※’utc’ は、世界協定時 (UTC +00:00) の代わりに指定できる。 @TimeZoneSet(20180511083000-03:00,local) = 20180511203000+09:00 ※’local’ は、システムのタイムゾーン (日本標準時であれば +09:00) の代わりに指定できる。ただし、<temporal> は、年月日を含む日付時刻でなければならない。 |
時間間隔の標準書式
時間間隔の値は、原則として、ISO 8601 で規定されている時間間隔の書式のうち PnYnMnDTnHnMnS 形式 (n は、時間間隔を構成する各要素: 年数、月数、日数、時間数、分数、秒数を表す数) の書式によって表します。
例: P1Y2M3DT4H5M6.123456789S = 1年 2ヶ月 3日 4時間 5分 6.123456789秒
- 文字 P によって、時間間隔の記述の始まりを示す (P は Period の頭文字)。
- 文字 T によって、年月日数と時分秒数の間の区切りを示す。
- T より前の文字 Y, M, D によって、それぞれの直前に記述した数が年数: years、月数: months、日数: days であることを示す。
- T より後の文字 H, M, S によって、それぞれの直前に記述した数が時間数: hours、分数: minutes、秒数: seconds であることを示す。
- 年数、月数、日数、時間数、分数は 0 以上の整数、秒数は 0 以上の整数または小数点数 (小数点以下9桁=ナノ秒まで有効) とする。
- 時間間隔を構成する要素は、年数、月数、日数、時間数、分数、秒数の順で、スペースなどをはさまずに連続して記述しなければならない。
- 値 0 の要素は省略できるが、少なくともひとつの要素は存在しなければならない (時間間隔 0 は PT0S とする。P や PT は不可)。
- 時間間隔を構成する要素が年月日数のみである場合に限って T を省略できる (例: P1M = P1MT = 1ヶ月)。
- 負の時間間隔は、P の前にマイナス符号 (-) をつけて表す。正の時間間隔にはプラス符号をつけてはならない。