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

# Text I/O

> Read and write delimited text formats (CSV, TSV, whitespace-separated) in the browser and Node.js.

numpy-ts provides NumPy-compatible text parsing and serialization, split into environment-agnostic buffer functions and file I/O functions. File I/O functions are available from the main `numpy-ts` entry point and work on Node.js, Bun, and Deno. They throw in browser environments.

> [!WARNING]
>
> The `numpy-ts/node` entry point is deprecated. Imports from it still work but you should migrate to `numpy-ts`.

## Browser API

These functions work with strings and can be used in any JavaScript environment.

### parseTxt

Parse a text string into an NDArray. Each row must have the same number of values.

```typescript theme={null}
function parseTxt(text: string, options?: ParseTxtOptions): NDArray
```

| Name | Type | Default | Description |
| - | - | - | - |
| `text` | `string` | -- | The text content to parse. |
| `options` | `ParseTxtOptions` | `{}` | Parsing options (see table below). |

**Returns:** `NDArray` -- 2-D array (or 1-D if a single row/column).

```typescript theme={null}
import { parseTxt } from 'numpy-ts';

const csv = `1,2,3
4,5,6
7,8,9`;

const arr = parseTxt(csv, { delimiter: ',' });
// shape [3, 3]
```

***

### serializeTxt

Serialize an NDArray to a text string.

```typescript theme={null}
function serializeTxt(arr: NDArray, options?: SerializeTxtOptions): string
```

| Name | Type | Default | Description |
| - | - | - | - |
| `arr` | `NDArray` | -- | Array to serialize (must be 1-D or 2-D). |
| `options` | `SerializeTxtOptions` | `{}` | Serialization options (see table below). |

**Returns:** `string` -- Text representation of the array.

```typescript theme={null}
import * as np from 'numpy-ts';
import { serializeTxt } from 'numpy-ts';

const arr = np.array([[1, 2, 3], [4, 5, 6]]);
const csv = serializeTxt(arr, { delimiter: ',', fmt: '%d' });
// "1,2,3\n4,5,6\n"
```

***

### genfromtxt

Parse a text string with flexible handling of missing values. Replaces missing values with a fill value instead of throwing. This is a **buffer-based** function that works with strings in any environment.

```typescript theme={null}
function genfromtxt(text: string, options?: ParseTxtOptions): NDArray
```

| Name | Type | Default | Description |
| - | - | - | - |
| `text` | `string` | -- | The text content to parse. |
| `options` | `ParseTxtOptions` | `{}` | Parsing options. Use `missing_values` and `filling_values` to handle gaps. |

**Returns:** `NDArray` -- Parsed array with missing values filled in.

```typescript theme={null}
import { genfromtxt } from 'numpy-ts';

const csv = `1,2,3
4,,6
7,8,`;

const arr = genfromtxt(csv, {
  delimiter: ',',
  missing_values: [''],
  filling_values: 0,
});
// array([[1, 2, 3],
//        [4, 0, 6],
//        [7, 8, 0]])
```

***

### fromregex

Extract data from a text string using a regular expression with capture groups. This is a **buffer-based** function that works with strings in any environment.

```typescript theme={null}
function fromregex(text: string, regexp: RegExp | string, dtype?: DType): NDArray
```

| Name | Type | Default | Description |
| - | - | - | - |
| `text` | `string` | -- | The text content to search. |
| `regexp` | `RegExp \| string` | -- | Regular expression with capture groups. Each match produces one row; each group produces one column. |
| `dtype` | `DType` | `'float64'` | Data type of the resulting array. |

**Returns:** `NDArray` -- Array with one row per match and one column per capture group.

```typescript theme={null}
import { fromregex } from 'numpy-ts';

const log = `x=1.5, y=2.3
x=3.0, y=4.1
x=5.5, y=6.7`;

const arr = fromregex(log, /x=([\d.]+), y=([\d.]+)/);
// array([[1.5, 2.3],
//        [3.0, 4.1],
//        [5.5, 6.7]])
```

***

## Options Reference

### ParseTxtOptions

| Name | Type | Default | Description |
| - | - | - | - |
| `delimiter` | `string` | whitespace | String used to separate values. By default, any consecutive whitespace acts as delimiter. |
| `comments` | `string` | `'#'` | Character indicating the start of a comment line. |
| `skiprows` | `number` | `0` | Number of lines to skip at the beginning of the file. |
| `usecols` | `number \| number[]` | all | Which columns to read (0-indexed). |
| `max_rows` | `number` | all | Maximum number of data rows to read (after `skiprows`). |
| `dtype` | `DType` | `'float64'` | Data type of the resulting array. |
| `encoding` | `string` | `'utf-8'` | Character encoding (only relevant for file I/O operations). |
| `missing_values` | `string \| string[]` | `undefined` | String representation(s) of missing values (used by `genfromtxt`). |
| `filling_values` | `number` | `NaN` (float) / `0` (int) | Replacement value for missing entries. |

### LoadTxtOptions

Alias for `ParseTxtOptions`. Used by `loadtxt`, `genfromtxt`, and their file-based variants.

### SerializeTxtOptions

| Name | Type | Default | Description |
| - | - | - | - |
| `fmt` | `string` | `'%.18e'` | Printf-style format string. Examples: `'%.6f'` (6 decimals), `'%.2e'` (scientific), `'%d'` (integer). |
| `delimiter` | `string` | `' '` | String separating columns. |
| `newline` | `string` | `'\n'` | String written at the end of each row. |
| `header` | `string` | `undefined` | Text written at the beginning of the file. Automatically prefixed with the comment character. |
| `footer` | `string` | `undefined` | Text written at the end of the file. |
| `comments` | `string` | `'# '` | String prepended to header and footer lines. |

### SaveTxtOptions

Alias for `SerializeTxtOptions`. Used by `savetxt` and its file-based variants.

***

## File I/O API

> [tab] Async
>
> ### loadtxt
>
> Load data from a text file on disk.
>
> ```typescript theme={null}
> function loadtxt(path: string, options?: LoadTxtOptions): Promise<NDArray>
> ```
>
> | Name | Type | Default | Description |
> | - | - | - | - |
> | `path` | `string` | -- | Path to the text file. |
> | `options` | `LoadTxtOptions` | `{}` | Parsing options. |
>
> **Returns:** `Promise<NDArray>` -- The parsed array.
>
> ```typescript theme={null}
> import * as np from 'numpy-ts';
>
> // Load CSV
> const data = await np.loadtxt('data.csv', { delimiter: ',' });
>
> // Load with column selection and header skip
> const subset = await np.loadtxt('data.txt', {
>   usecols: [0, 2],
>   skiprows: 1,
> });
> ```
>
> ***
>
> ### savetxt
>
> Save an array to a text file.
>
> ```typescript theme={null}
> function savetxt(
>   path: string,
>   arr: NDArray,
>   options?: SaveTxtOptions
> ): Promise<void>
> ```
>
> | Name | Type | Default | Description |
> | - | - | - | - |
> | `path` | `string` | -- | Output file path. |
> | `arr` | `NDArray` | -- | Array to save (must be 1-D or 2-D). |
> | `options` | `SaveTxtOptions` | `{}` | Serialization options. |
>
> **Returns:** `Promise<void>`
>
> ```typescript theme={null}
> import * as np from 'numpy-ts';
>
> const arr = np.array([[1, 2, 3], [4, 5, 6]]);
>
> // Save as CSV
> await np.savetxt('output.csv', arr, { delimiter: ',', fmt: '%d' });
>
> // Save with header
> await np.savetxt('output.txt', arr, {
>   header: 'x y z',
>   fmt: '%.4f',
> });
> ```
>
> ***
>
> ### genfromtxtFile
>
> Load and parse a text file from disk with flexible handling of missing values. This is the **file-based** equivalent of `genfromtxt`.
>
> ```typescript theme={null}
> function genfromtxtFile(path: string, options?: LoadTxtOptions): Promise<NDArray>
> ```
>
> | Name | Type | Default | Description |
> | - | - | - | - |
> | `path` | `string` | -- | Path to the text file. |
> | `options` | `LoadTxtOptions` | `{}` | Parsing options. Use `missing_values` and `filling_values` to handle gaps. |
>
> **Returns:** `Promise<NDArray>` -- Parsed array with missing values filled in.
>
> ```typescript theme={null}
> import * as np from 'numpy-ts';
>
> const arr = await np.genfromtxtFile('data.csv', {
>   delimiter: ',',
>   missing_values: [''],
>   filling_values: 0,
> });
> ```
>
> ***
>
> ### fromregexFile
>
> Extract data from a text file on disk using a regular expression with capture groups. This is the **file-based** equivalent of `fromregex`.
>
> ```typescript theme={null}
> function fromregexFile(path: string, regexp: RegExp | string, dtype?: DType): Promise<NDArray>
> ```
>
> | Name | Type | Default | Description |
> | - | - | - | - |
> | `path` | `string` | -- | Path to the text file. |
> | `regexp` | `RegExp \| string` | -- | Regular expression with capture groups. |
> | `dtype` | `DType` | `'float64'` | Data type of the resulting array. |
>
> **Returns:** `Promise<NDArray>`
>
> ```typescript theme={null}
> import * as np from 'numpy-ts';
>
> const arr = await np.fromregexFile('points.log', /x=([\d.]+), y=([\d.]+)/);
> ```

> [tab] Sync
>
> Every file function above has a synchronous counterpart taking the same arguments and returning the array directly rather than a `Promise`. They are Node-only -- they read and write through `node:fs` -- so use the async forms in the browser.
>
> ```typescript theme={null}
> function loadtxtSync(path: string, options?: LoadTxtOptions): NDArray
>
> function savetxtSync(path: string, arr: NDArray, options?: SaveTxtOptions): void
>
> function genfromtxtFileSync(path: string, options?: LoadTxtOptions): NDArray
>
> function fromregexFileSync(path: string, regexp: RegExp | string, dtype?: DType): NDArray
> ```
>
> Usage:
>
> ```typescript theme={null}
> import * as np from 'numpy-ts';
>
> // loadtxt / savetxt
> const data = np.loadtxtSync('data.csv', { delimiter: ',' });
> np.savetxtSync('output.csv', data, { delimiter: ',', fmt: '%d' });
>
> // genfromtxt / fromregex (file-based)
> const filled = np.genfromtxtFileSync('data.csv', {
>   delimiter: ',',
>   missing_values: [''],
>   filling_values: 0,
> });
> const matched = np.fromregexFileSync('points.log', /x=([\d.]+), y=([\d.]+)/);
> ```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.