fluorite-7　日本語リファレンス　日付


[日本語チュートリアルトップ](https://qiita.com/MirrgieRiana/items/a0906c72ebfb46693ab5)

# 基礎

日付は根本的にはエポックミリ秒（UNIX時間）で管理される。
エポックミリ秒はUTCである。

`NOW()`で現在の時刻が取得できる。

```bash:
$ fl7 'NOW()'
1600056336747
```

----

日付の操作を行うための日付オブジェクトが存在する。

`DATE()`で現在の時刻の日付オブジェクトが得られる。
`DATE(epochMilliseconds)`でエポックミリ秒に対応する日付オブジェクトが得られる。

```bash:
$ fl7 'DATE()'
2020-09-14T13:10:06.650

$ fl7 'DATE(1600056336747)'
2020-09-14T13:05:36.747
```

日付オブジェクトは通常のオブジェクトと同じように使うことができる。

```bash:
$ fl7 'DATE(1600056336747).hour'
13

$ fl7 'DATE(1600056336747)[]'
{key:utcYear;value:2020}
{key:utcMonth;value:9}
{key:utcDay;value:14}
{key:utcHour;value:4}
{key:utcMinute;value:5}
{key:utcSecond;value:36}
{key:utcMillisecond;value:747}
{key:utcWeekday;value:1}
{key:year;value:2020}
{key:month;value:9}
{key:day;value:14}
{key:hour;value:13}
{key:minute;value:5}
{key:second;value:36}
{key:millisecond;value:747}
{key:weekday;value:1}
{key:epochMillisecond;value:1600056336747}
{key:timezoneOffset;value:-540}
{key:TO_NUMBER;value:[FluoriteFunction]}
{key:TO_STRING;value:[FluoriteFunction]}
```

# エポックミリ秒

エポックミリ秒（UNIX時間）は常にUTCである。

## 日付の加減算

エポックミリ秒はただの数値であるため、期間の計算が得意である。

次のコードは2000年1月1日の87日後を求めるサンプルである。

```bash:
$ fl7 '+LOCAL(2000; 1; 1) + 87DAYS => DATE'
2000-03-28T00:00:00.000
```

# 日付オブジェクト

日付オブジェクトは日付系API関数から返されるオブジェクトである。
オブジェクトの特性としては通常のオブジェクトと違いはない。

```bash:
$ fl7 'DATE(1600056336747)[]'
{key:utcYear;value:2020}
{key:utcMonth;value:9}
{key:utcDay;value:14}
{key:utcHour;value:4}
{key:utcMinute;value:5}
{key:utcSecond;value:36}
{key:utcMillisecond;value:747}
{key:utcWeekday;value:1}
{key:year;value:2020}
{key:month;value:9}
{key:day;value:14}
{key:hour;value:13}
{key:minute;value:5}
{key:second;value:36}
{key:millisecond;value:747}
{key:weekday;value:1}
{key:epochMillisecond;value:1600056336747}
{key:timezoneOffset;value:-540}
{key:TO_NUMBER;value:[FluoriteFunction]}
{key:TO_STRING;value:[FluoriteFunction]}
```

`month`および`utcMonth`は1月が1である。
`weekday`および`utcWeekday`は日曜日が0である。

## UTCとローカル時刻

日付オブジェクトはUTCとローカル時刻の両方のフィールドを保持している。

タイムゾーンはシステムのタイムゾーンに依存する。

## 数値化でエポックミリ秒が得られる

`+DATE()`は`NOW()`と等価である。

```bash
$ fl7 'NOW(), +DATE()'
1600057056467
1600057056467
```

## 文字列化でローカル時刻の文字列表現になる

フォーマットは常にISOっぽい表記である。

```bash
$ fl7 '&DATE()'
2020-09-14T13:18:53.424
```

# API

## `NOW()`関数

現在のエポックミリ秒を数値で返す。

```bash
$ fl7 'NOW()'
1600056336747
```

## `DATE([epochMilliseconds])`関数

指定したエポックミリ秒に対応する時間を取り扱うオブジェクトを返す。
引数を省略すると現在の時刻の時間オブジェクトを返す。

```bash
$ fl7 'DATE()'
2020-09-14T13:07:11.883

$ fl7 'DATE(1600056336747)'
2020-09-14T13:05:36.747
```

## `LOCAL(year; month; day[; hour; minute; second[; millisecond]])`関数

ローカル時刻で時間オブジェクトを得る。

```bash:
$ fl7 'LOCAL(2020; 1; 2)'
2020-01-02T00:00:00.000

$ fl7 'LOCAL(2020; 1; 2; 3; 4; 5)'
2020-01-02T03:04:05.000

$ fl7 'LOCAL(2020; 1; 2; 3; 4; 5; 6)'
2020-01-02T03:04:05.006
```

## `UTC(year; month; day[; hour; minute; second[; millisecond]])`関数

UTCで時間オブジェクトを得る。

```bash:
$ fl7 'UTC(2020; 1; 2)'
2020-01-02T09:00:00.000

$ fl7 'UTC(2020; 1; 2; 3; 4; 5)'
2020-01-02T12:04:05.000

$ fl7 'UTC(2020; 1; 2; 3; 4; 5; 6)'
2020-01-02T12:04:05.006
```

上記のコードのタイムゾーンは日本（+9時間）である。

## 日付単位系関数

以下の10個の関数が該当。

- `DAYS(number[; other])`関数
- `HOURS(number[; other])`関数
- `MINUTES(number[; other])`関数
- `SECONDS(number[; other])`関数
- `MILLISECONDS(number[; other])`関数
- `UNIT_D(number[; other])`関数
- `UNIT_H(number[; other])`関数
- `UNIT_M(number[; other])`関数
- `UNIT_S(number[; other])`関数
- `UNIT_MS(number[; other])`関数

それぞれ、第一引数に所定の係数をかけた値を返す。

```bash:
$ fl7 'DAYS(1), HOURS(1), MINUTES(1), SECONDS(1), MILLISECONDS(1)'
86400000
3600000
60000
1000
1

$ fl7 'UNIT_D(1), UNIT_H(1), UNIT_M(1), UNIT_S(1), UNIT_MS(1)'
86400000
3600000
60000
1000
1
```

第2引数が指定された場合、戻り値にそれを加算する。

```bash:
$ fl7 'HOURS(1; 2)'
3600002

$ fl7 'HOURS(1; MINUTES(2; SECONDS(3)))'
3723000
```

**Tips** 呼び出しにはコンポジットを利用するとより簡潔である。

```bash:
$ fl7 'DATE(NOW()), DATE(NOW() + 1H2M3S)'
2020-09-18T10:30:11.300
2020-09-18T11:32:14.300
```