# `Feel.Builtin.Temporal`
[🔗](https://github.com/FeeJai/BDM/blob/feel-v0.1.0/apps/feel/lib/feel/builtin/temporal.ex#L1)

The functions of FEEL that read date and time values: `is` (section 10.3.4.6),
`day of week`, `day of year`, `week of year`, and `month of year` (section
10.3.4.8), and `now` and `today` (section 10.3.4.11).

`is` is printed under the date and time functions, but it compares any two values
for identity in the semantic domain, and `time("23:00:50z")` is not
`time("23:00:50")` for it. A date and time with and without an offset is D-54.

`now` and `today` read the clock of the run, which is read once per run so that
repeated calls agree (see the `:clock` option of `Feel.run/3`).

## What is written (D-56)

All seven.

| Call | Result |
| ---- | ------ |
| `now()` | the clock as a date and time, with the offset it has (`DateTime.utc_now/0` has 0), in microseconds |
| `today()` | the date of the clock, in its own zone |
| `day of week(date)` | `"Monday"` to `"Sunday"` |
| `day of year(date)` | 1 to 366 |
| `week of year(date)` | the week of ISO 8601, 1 to 53: week 1 is the one with the first Thursday of the year, so `2010-01-01` is in week 53 (of 2009) |
| `month of year(date)` | `"January"` to `"December"` |
| `is(value1, value2)` | `true` for two values that are the same element of the semantic domain, and never `null` |

The argument of the calendar functions is a date or a date and time, whose fields are read as
they are written. Anything else, `null` included, is out of the domain: the call is `null` with an
`:argument_out_of_domain` error.

`is` is identity, not equality: two numbers or two durations of one kind are the same when they have
the same value, but a time or a date and time is the same only with the same fields **and the same
zone**. So `is(@"23:00:50Z", @"23:00:50+00:00")` is `true` (both are the offset 0), and
`is(@"23:00:50@Etc/GMT", @"23:00:50Z")` and `is(@"2002-04-02T12:00:00-01:00", @"2002-04-02T17:00:00+04:00")` are
`false`, as is `is(@"P0Y", @"P0D")` (the kinds differ). Lists and contexts are the same when their
elements are. The TCK (0103) has all of it.

# `functions`

```elixir
@spec functions() :: [Feel.Builtin.Function.t()]
```

The functions of this module that are written, as `Feel.Builtin.Function`s.

# `names`

```elixir
@spec names() :: [Feel.Name.t()]
```

Returns the canonical names of the functions of this module, sorted.

    iex> "today" in Feel.Builtin.Temporal.names()
    true

---

*Consult [api-reference.md](api-reference.md) for complete listing*