# subtractYearMonth

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

## Signature

```ts
subtractYearMonth(value: string, units: { years?: number; months?: number; }): string
```

Return a year-month string moved backward by `units`.

- The same rules as `addYearMonth`: years and months only (`{ days: 1 }` and `{ weeks: 1 }` return `""`), nothing to clamp, and `""` for invalid input.
- The amounts are not negated here, so the sign rules (mixed signs, `-0`) are Temporal's.
- The subtraction starts from day 1 of the month, as the specification's AddDurationToYearMonth does with operation `subtract` (it negates the duration, then sets [[Day]] to 1), so `+275760-09` minus a month is `+275760-08` and `-271821-05` minus a month is `""` (day 1 of `-271821-04` is out of range).

## Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `value` | `string` | year-month string |

## Options

**units**

the amounts to move the year-month by

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `years?` | `number` | no years; at least one of `years` and `months` must be given. | Whole years to subtract. |
| `months?` | `number` | no months; at least one of `years` and `months` must be given. | Whole months to subtract. |

## Returns

the year-month string after the subtraction, or "" on invalid input

## Examples

```ts
import { subtractYearMonth } from "@northguild/gmt/plain/calculate";

subtractYearMonth("2026-10", { months: 10 }) // "2025-12"
```

## Source

[plain/calculate/subtractYearMonth.ts](https://github.com/northguild/gmt/blob/main/packages/gmt/src/plain/calculate/subtractYearMonth.ts)