# parseMonthDayWithPattern

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

## Signature

```ts
parseMonthDayWithPattern(value: string, pattern: string, locale?: string | string[]): string
```

Parse a month-day string against a caller-supplied token pattern (e.g. `"MM-dd"`, `"d MMMM"`) and return it as an ISO month-day string, `--MM-DD`.

- **Decoding, not display.** This reads a *known, fixed* producer format. A pattern with a year, weekday, era or time token returns `""` — use `parseDateWithPattern` for a full date.
- `--02-29` is valid: the month-day has no year, so 29 February exists. `--02-30` and `--04-31` do not, and return `""`.
- Digits are ASCII, as in the other pattern parsers. ### Token table

  | Token | Field | Width | Range | Notes |
  |---|---|---|---|---|
  | `MM` | month | 2 digits | 01–12 | |
  | `M` | month | 1-2 digits | 1–12 | |
  | `MMMM` | month name (long) | locale | — | Reads the format-context name ("марта") or the stand-alone name ("март"); UTS #35 Part 4, Parsing Dates and Times |
  | `MMM` | month name (short) | locale | — | Reads either context, as `MMMM` |
  | `LL` | month | 2 digits | 01–12 | Stand-alone context; read as `MM` |
  | `L` | month | 1-2 digits | 1–12 | Stand-alone context; read as `M` |
  | `LLLL` | month name (long) | locale | — | Same names as `MMMM` |
  | `LLL` | month name (short) | locale | — | Same names as `MMM` |
  | `dd` | day | 2 digits | 01–31 | |
  | `d` | day | 1-2 digits | 1–31 | |

- Literal text follows the Unicode UTS #35 date format pattern rules: text in `'single quotes'` is a literal, `''` is one literal quote, and a quote that never closes makes the pattern malformed (`""`).
- Adjacent variable-width numeric tokens with no literal separator (e.g. `"Md"`) are ambiguous: `parseMonthDayWithPattern("111", "Md")` gives `"--01-11"`, a split picked by regex backtracking, not by any rule. Prefer zero-padded tokens (`MM`, `dd`) or a separator.
- Any character other than A–Z and a–z is a literal (UTS #35), which is what makes `"d בMMMM"` and `"M月d日"` work.
- Month names match case-insensitively (UTS #35 Part 4, Parsing: "case variants should be accepted"): `"december 25"` against `"MMMM d"` gives `"--12-25"`.
- A `-u-ca-` locale extension is overridden to Gregorian: `parseMonthDayWithPattern("September 1", "MMMM d", "en-u-ca-islamic")` gives `"--09-01"`, and `"Ramadan 1"` gives `""`. A `-u-nu-` extension changes the names of a locale that writes its months with digits, as that locale prints them: in `"ja-JP-u-nu-hanidec"`, `"一二月25日"` against `"MMMMd日"` gives `"--12-25"` and `"12月25日"` gives `""`. Day digits are always ASCII.
- The pattern needs both a month and a day, otherwise `""`.
- Name tokens are locale-aware. If `locale` is omitted (or an empty list) and the pattern uses one, GMT reads English names in `"en"`. An ill-formed tag returns `""`.

## Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `value` | `string` | The string to decode (e.g. "25 December") |
| `pattern` | `string` | The token pattern describing `value`'s shape (e.g. "d MMMM") |
| `locale` | `string` \| `string[]` | Optional BCP 47 locale tag, or a preference list of tags, for name-based tokens (default "en") |

## Returns

the `--MM-DD` string, or "" on no match, malformed pattern, or invalid input

## Examples

```ts
import { parseMonthDayWithPattern } from "@northguild/gmt/plain/parse";

parseMonthDayWithPattern("12-25", "MM-dd") // "--12-25"
```

## Source

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