> ## Documentation Index
> Fetch the complete documentation index at: https://persian-tools.usestrict.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Capital by Province

> Look up the capital city of an Iranian province by its Persian name.

`findCapitalByProvince` returns the capital city of an Iranian province given its Persian name.

## Function

```ts theme={null}
findCapitalByProvince(state: string): string
```

```ts theme={null}
import { findCapitalByProvince } from "@persian-tools/persian-tools";

findCapitalByProvince("خراسان رضوی"); // "مشهد"
findCapitalByProvince("تهران"); // "تهران"
findCapitalByProvince("اصفهان"); // "اصفهان"
```

## Behaviour

1. Normalize the input via `toPersianChars` — Arabic-keyboard `ك`/`ي` are tolerated.
2. Look up in `IRAN_STATES` (a `Map<string, string>`).
3. Return the capital, or **throw** `PersianToolsError("findCapitalByProvince", "no province found")` if unknown.

> Return type is `string`. The function **throws** on unknown input; it does not return `undefined`. Wrap calls in `try/catch` or pre-validate against the keys.

## Pitfalls

* **Throws** on unknown province.
* **Input must be Persian.** Latin transliterations like `"Tehran"` won't match.
* **Equality is exact after `toPersianChars`** — extra whitespace, ZWNJ, or diacritics will miss. Normalize upstream if input is user-typed.
* **To list all provinces** for autocomplete, iterate `Array.from(IRAN_STATES.keys())`.

## Composition

```ts theme={null}
import { findProvinceFromCoordinate, findCapitalByProvince } from "@persian-tools/persian-tools";

const province = findProvinceFromCoordinate({ longitude: 51.4, latitude: 35.7 });
const capital = findCapitalByProvince(province.fa);
```

## Source

`src/modules/findCapitalByProvince/index.ts`, `states.ts` · Tests: `test/findCapitalByProvince.spec.ts`