> ## 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`.
</Warning>

## 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?: LoadTxtOptions): NDArray
```

| Name      | Type             | Default | Description                                                                |
| --------- | ---------------- | ------- | -------------------------------------------------------------------------- |
| `text`    | `string`         | --      | The text content to parse.                                                 |
| `options` | `LoadTxtOptions` | `{}`    | 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

<Tabs>
  <Tab title="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>

  <Tab title="Sync">
    Synchronous versions of all file I/O functions:

    ```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.]+)/);
    ```
  </Tab>
</Tabs>