# TextApi

Reading and searching text. Both members need the `extract` feature and refuse with `FEATURE_NOT_LICENSED` without it. To _change_ text, use [`viewer.tools.editText`](https://kernstra.com/docs/web-sdk/api/viewer-tools-edittext).

This search is distinct from `viewer.search()`: that one drives the search UI and highlights matches on screen, while this one returns data and needs no viewer at all. Each match carries `rects`, the rectangles it covers, as [`Rect`](https://kernstra.com/docs/web-sdk/api/types#ty-rect)s in page space; a match broken across lines has one rectangle per line, which is why it is not a single box. Extraction order follows the order in which the page content draws the text. That usually matches reading order, but a PDF carries no guarantee of one.

- Kind: namespace
- Access: `doc.text`

## Usage

```ts
const hits = await doc.text.search('Invoice', { matchCase: true, limit: 50 });

for (const hit of hits) {
  console.log('page ' + (hit.pageIndex + 1) + ': ' + hit.text);
}
```

## Text

### `extract`

```ts
extract(pageIndex: number): Promise<string>
```

All text on a page, as a string; lines end with `\n`. Needs the `extract` feature.

- Kind: method
- Since: 1.0.0

| Parameter | Type | Description |
| --- | --- | --- |
| `pageIndex` | `number` | Zero-based page index. |

Returns `Promise<string>`: Lines end with `\n`.

Throws:

- `INVALID_ARGUMENT` — a page index out of range.
- `PAGE_ERROR` — the page or its text could not be loaded.
- `DOCUMENT_CLOSED` — the document has been closed.
- `FEATURE_NOT_LICENSED` — the license lacks `extract`.

```ts
const pages = [];
for (let i = 0; i < doc.pageCount; i++) pages.push(await doc.text.extract(i));
```

Page: https://kernstra.com/docs/web-sdk/api/doc-text/extract

### `search`

```ts
search(query: string, options?: SearchOptions): Promise<SearchMatch[]>
```

Every match, as `SearchMatch[]`. Needs the `extract` feature.

- Kind: method
- Since: 1.0.0

| Parameter | Type | Description |
| --- | --- | --- |
| `query` | `string` | The text to find. Must not be empty. |
| `options?` | `SearchOptions` | `matchCase` and `matchWholeWord` (both default to `false`), `pages` (zero-based; restrict the search) and `limit` (stop after N matches). |

Returns `Promise<SearchMatch[]>`: Each `{ pageIndex, text, rects }`.

Throws:

- `INVALID_ARGUMENT` — an empty query, or an index in `pages` out of range.
- `PAGE_ERROR` — a page or its text could not be loaded.
- `DOCUMENT_CLOSED` — the document has been closed.
- `FEATURE_NOT_LICENSED` — the license lacks `extract`.

```ts
const onCover = await doc.text.search('Total', { pages: [0], matchWholeWord: true });
```

Page: https://kernstra.com/docs/web-sdk/api/doc-text/search

Web page: https://kernstra.com/docs/web-sdk/api/doc-text