# parseFixUtcTimestamp

Industry: Finance

:::caution[Unreleased]
Not in `@northguild/gmt` 1.21.0 on npm yet. It is on `main` and ships in the next release.
:::

## Signature

```ts
parseFixUtcTimestamp(value: string): FixUtcTimestamp | null
```

Read a FIX `UTCTimestamp` as a UTC instant and the precision its digits state.

- The format is `YYYYMMDD-HH:MM:SS` or `YYYYMMDD-HH:MM:SS.fraction`. FIX Latest: "colons, dash, and period required"; "The fractions of seconds may be empty when no fractions of seconds are conveyed (in such a case the period is not conveyed)". A period needs digits.
- The fraction digits state the precision (FIX Latest: "3 digits to convey milliseconds, 6 digits to convey microseconds, 9 digits to convey nanoseconds, 12 digits to convey picoseconds"):

  | Fraction digits | `precision`     |
  | --------------- | --------------- |
  | none            | `"second"`      |
  | 3               | `"millisecond"` |
  | 6               | `"microsecond"` |
  | 9               | `"nanosecond"`  |
  | 12              | `"picosecond"`  |

- These are the FIX Latest widths. FIX 4.2 and 4.4 define only whole seconds and `.sss`; this function still reads 6, 9 and 12 digits, and does not return `null` for them.
- Precision is reported, never widened: `instant` keeps the digits sent, trailing zeros included, so `.100` stays `.100Z`.
- Temporal holds nanoseconds. For a 12-digit fraction the first nine digits go in `instant` and the last three in `picoseconds`; nothing is dropped.
- A second of `60` is read only for one of the 27 inserted leap seconds in the IERS table built into GMT (Leap_Second.dat through Bulletin C 72; the table is closed). `instant` is then `…T23:59:60…Z`, which `formatFixUtcTimestamp`, `toTAI` and `isLeapSecond` read back and other GMT functions refuse. A `60` on any other day, at any other hour or minute, or before 1972 returns `null`.
- Fields are checked, not clamped: 30 February, hour 24, minute 60 and month 13 return `null`. The year is the four digits as written, `0000` to `9999`.
- Another number of digits is FIX's "bilateral agreement" and returns `null`; read it with `parseDateTimeWithPattern` or your own code, knowing the agreed precision.
- Which FIX field carries the stamp (`SendingTime`, `TransactTime`) is the FIX dictionary's concern, not this function's.
- Returns `null` for a non-string argument.

## Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `value` | `string` | A FIX `UTCTimestamp` (e.g. "20240615-14:30:00.123") |

## Returns

the instant, precision, leap-second flag and picoseconds, or `null` on invalid input

## Types

### FixUtcTimestamp

A FIX `UTCTimestamp` (`YYYYMMDD-HH:MM:SS[.fraction]`) read as an instant plus what the digits stated. Returned by `parseFixUtcTimestamp`.

```ts
import type { FixUtcTimestamp } from "@northguild/gmt";
```

| Member | Type | Description |
| --- | --- | --- |
| `instant` | `string` | The moment as an ISO 8601 instant string ending in `Z`, with the fraction digits that were sent, up to the ninth. It keeps the digits sent, so `.100` stays `.100Z`; it is therefore not always the string `Temporal.Instant#toString()` writes. In a leap second it is `…T23:59:60…Z`, which only the `timescale/`, `gnss/` and `finance/` functions read back. |
| `precision` | `"second"` \| `"millisecond"` \| `"microsecond"` \| `"nanosecond"` \| `"picosecond"` ([`FixPrecision`](/gmt/reference/types/FixPrecision/)) | The precision the digit count stated: 0, 3, 6, 9 or 12 fraction digits. |
| `leapSecond` | `boolean` | Whether the second was `60`, an inserted leap second. |
| `picoseconds` | `number` | Digits 10 to 12 of a 12-digit fraction, 0 to 999. `0` for every other precision. Temporal holds nanoseconds, so these are returned apart from `instant`. |

## Related types

- [`FixPrecision`](/gmt/reference/types/FixPrecision/)

## Examples

```ts
import { parseFixUtcTimestamp } from "@northguild/gmt/finance/parse";

parseFixUtcTimestamp("20240615-14:30:00.123456") // { instant: "2024-06-15T14:30:00.123456Z", precision: "microsecond", leapSecond: false, picoseconds: 0 }
```

## Source

[finance/parse/parseFixUtcTimestamp.ts](https://github.com/northguild/gmt/blob/main/packages/gmt/src/finance/parse/parseFixUtcTimestamp.ts)
