# Functions

Free functions in the `nominal` namespace.

## nominal.fromNanos(nanos)

Convert int64 nanoseconds since the Unix epoch to a UTC datetime.

The inverse of nominal.toNanos.

datetime does not resolve to nanoseconds, so the conversion is not exact
at that level. Keep the raw int64 if you need the exact instant.

Parameters:
:   **nanos**

    int64 nanoseconds since the Unix epoch.

Returns:
:   *datetime* – Always UTC. Set its TimeZone to view it locally.

> **See also**
>
> [`nominal.toNanos()`](https://dev.nominal.io/matlab/ref/functions.md#nominal.toNanos "nominal.toNanos"), [`nominal.now()`](https://dev.nominal.io/matlab/ref/functions.md#nominal.now "nominal.now")

## nominal.now()

Current time as int64 nanoseconds since the Unix epoch.

Use this instead of datetime(“now”) when you need full precision for
streaming timestamps. datetime does not resolve to nanoseconds.

```matlab
t0 = nominal.now();
t  = t0 + int64(0:999)' * 1000000;   % 1 ms apart
```

Returns:
:   *int64* – Nanoseconds since the Unix epoch.

> **See also**
>
> [`nominal.toNanos()`](https://dev.nominal.io/matlab/ref/functions.md#nominal.toNanos "nominal.toNanos"), [`nominal.fromNanos()`](https://dev.nominal.io/matlab/ref/functions.md#nominal.fromNanos "nominal.fromNanos")

## nominal.shutdown()

Shut the toolbox down, closing every connection.

You do not need to call this. It runs automatically on
clear mex, clear all, or exit.

Call it when you want the shutdown at a known point, such as the end of
a long-running script that should not hold a connection open.

Every nominal object you hold stops working, and using one raises
nominal:invalidHandle. Deleting one is still safe. New objects work as
normal.

> **See also**
>
> `clear`

## nominal.toNanos(value)

Convert a time to int64 nanoseconds since the Unix epoch.

Used wherever the toolbox takes a single instant, so callers can write
either

```matlab
r = a.run("burn-12", datetime("now", TimeZone="UTC"));
r = a.run("burn-12", int64(1735689600000000000));
```

Parameters:
:   **value**

    A zoned datetime or an int64 nanosecond count, taken
    literally: int64(0) is 1970-01-01T00:00:00Z. A plain double is
    refused: doubles lose integer precision past 2^53 nanoseconds,
    which is 1970 plus 104 days, so any present-day timestamp passed
    as one would be silently rounded.

Returns:
:   *int64* – Nanoseconds since the Unix epoch.

> **See also**
>
> [`nominal.fromNanos()`](https://dev.nominal.io/matlab/ref/functions.md#nominal.fromNanos "nominal.fromNanos"), [`nominal.now()`](https://dev.nominal.io/matlab/ref/functions.md#nominal.now "nominal.now")

## nominal.toNanosVector(value)

Convert a vector of times to int64 nanoseconds.

The vector counterpart of nominal.toNanos, used by the push methods.

Parameters:
:   **value**

    An int64 vector or a zoned datetime vector.

Returns:
:   *int64* – Column vector of nanoseconds since the Unix epoch.

> **See also**
>
> [`nominal.toNanos()`](https://dev.nominal.io/matlab/ref/functions.md#nominal.toNanos "nominal.toNanos"), [`nominal.Stream`](https://dev.nominal.io/matlab/ref/Stream.md#nominal.Stream "nominal.Stream")