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

# Set Operations

> Unique values, membership testing, set intersection, union, difference, symmetric difference, and zero trimming.

### unique

Find the sorted unique elements of an array. Optionally return indices, inverse mapping, and counts.

```typescript theme={null}
function unique(
  ar: ArrayLike,
  returnIndex?: boolean,
  returnInverse?: boolean,
  returnCounts?: boolean,
  axis?: number
): NDArray | { values: NDArray; indices?: NDArray; inverse?: NDArray; counts?: NDArray; }
```

| Name            | Type        | Default     | Description                                                                                                                            |
| --------------- | ----------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `ar`            | `ArrayLike` | --          | Input array. It is flattened before computing unique values unless `axis` is specified.                                                |
| `returnIndex`   | `boolean`   | `false`     | If `true`, also return the indices of the first occurrences.                                                                           |
| `returnInverse` | `boolean`   | `false`     | If `true`, also return the indices to reconstruct the original from the unique array.                                                  |
| `returnCounts`  | `boolean`   | `false`     | If `true`, also return the number of times each unique value appears.                                                                  |
| `axis`          | `number`    | `undefined` | Axis along which to find unique slices. If provided, the array is not flattened; instead unique slices along the given axis are found. |

**Returns:** `NDArray` when no optional flags are `true`. Object `{ values, indices?, inverse?, counts? }` when one or more flags are `true`.

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

const a = np.array([3, 1, 2, 1, 3, 2, 3]);

np.unique(a);
// array([1, 2, 3])

const result = np.unique(a, true, true, true);
console.log(result.values.toString());   // array([1, 2, 3])
console.log(result.indices!.toString()); // first occurrence positions
console.log(result.inverse!.toString()); // reconstruct original
console.log(result.counts!.toString());  // occurrence counts

// Unique rows (axis=0)
const m = np.array([[1,2,3],[4,5,6],[1,2,3],[7,8,9]]);
const uniq = np.unique(m, false, false, false, 0);
console.log(uniq.shape);  // [3, 3]  (duplicate row removed)

// Unique columns (axis=1)
const b = np.array([[1,1,2],[3,3,4],[5,5,6]]);
const uniqCols = np.unique(b, false, false, false, 1);
console.log(uniqCols.shape);  // [3, 2]
```

***

### unique\_all

Return sorted unique values along with their first-occurrence indices, inverse mapping, and counts. This is a structured-return alternative to calling `unique` with all flags set to `true`.

```typescript theme={null}
function unique_all(x: ArrayLike): {
  values: NDArray;
  indices: NDArray;
  inverse_indices: NDArray;
  counts: NDArray;
}
```

| Name | Type        | Default | Description  |
| ---- | ----------- | ------- | ------------ |
| `x`  | `ArrayLike` | --      | Input array. |

**Returns:** An object with four properties: `values` (sorted unique elements), `indices` (first-occurrence indices), `inverse_indices` (mapping to reconstruct input), and `counts` (element counts).

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

const result = np.unique_all([3, 1, 2, 1, 3]);
// result.values          = array([1, 2, 3])
// result.indices         = array([1, 2, 0])
// result.inverse_indices = array([2, 0, 1, 0, 2])
// result.counts          = array([2, 1, 2])
```

***

### unique\_counts

Return sorted unique values and their counts.

```typescript theme={null}
function unique_counts(x: ArrayLike): {
  values: NDArray;
  counts: NDArray;
}
```

| Name | Type        | Default | Description  |
| ---- | ----------- | ------- | ------------ |
| `x`  | `ArrayLike` | --      | Input array. |

**Returns:** An object with `values` (sorted unique elements) and `counts` (number of occurrences of each).

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

const result = np.unique_counts([1, 1, 2, 3, 3, 3]);
// result.values = array([1, 2, 3])
// result.counts = array([2, 1, 3])
```

***

### unique\_inverse

Return sorted unique values and the inverse mapping to reconstruct the original array.

```typescript theme={null}
function unique_inverse(x: ArrayLike): {
  values: NDArray;
  inverse_indices: NDArray;
}
```

| Name | Type        | Default | Description  |
| ---- | ----------- | ------- | ------------ |
| `x`  | `ArrayLike` | --      | Input array. |

**Returns:** An object with `values` (sorted unique elements) and `inverse_indices` (indices into `values` that reconstruct the original).

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

const result = np.unique_inverse([3, 1, 2, 1]);
// result.values          = array([1, 2, 3])
// result.inverse_indices = array([2, 0, 1, 0])
// Reconstruct: values[inverse_indices] -> [3, 1, 2, 1]
```

***

### unique\_values

Return only the sorted unique values (no indices, inverse, or counts).

```typescript theme={null}
function unique_values(x: ArrayLike): NDArray
```

| Name | Type        | Default | Description  |
| ---- | ----------- | ------- | ------------ |
| `x`  | `ArrayLike` | --      | Input array. |

**Returns:** `NDArray` -- Sorted unique values.

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

np.unique_values([3, 1, 2, 1, 3]);
// array([1, 2, 3])
```

***

### in1d

<Warning>
  **Deprecated in v1.3.0** to match NumPy 2.4. Use [`isin`](#isin) instead — `isin` preserves the input shape and supports the same `invert` option.
</Warning>

Test whether each element of a 1D array is also present in a second array. Returns a flattened boolean array.

```typescript theme={null}
function in1d(ar1: ArrayLike, ar2: ArrayLike): NDArray
```

| Name     | Type        | Default | Description                                                                             |
| -------- | ----------- | ------- | --------------------------------------------------------------------------------------- |
| `ar1`    | `ArrayLike` | --      | Input array to test.                                                                    |
| `ar2`    | `ArrayLike` | --      | Values to test against.                                                                 |
| `invert` | `boolean`   | `false` | If `true`, invert the result: return `true` where elements of `ar1` are *not* in `ar2`. |

**Returns:** `NDArray` -- Boolean array of the same length as `ar1` (flattened).

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

np.in1d([1, 2, 3, 4], [2, 4]);
// array([false, true, false, true])

np.in1d([1, 2, 3, 4], [2, 4], true);
// array([true, false, true, false])  -- inverted
```

***

### isin

Test whether each element of an array is present in a set of test elements. Unlike `in1d`, this preserves the shape of the input.

```typescript theme={null}
function isin(element: ArrayLike, testElements: ArrayLike): NDArray
```

| Name           | Type        | Default | Description                                                          |
| -------------- | ----------- | ------- | -------------------------------------------------------------------- |
| `element`      | `ArrayLike` | --      | Input array to test.                                                 |
| `testElements` | `ArrayLike` | --      | Values to test against. Flattened internally.                        |
| `invert`       | `boolean`   | `false` | If `true`, return `true` where elements are *not* in `testElements`. |

**Returns:** `NDArray` -- Boolean array with the same shape as `element`.

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

const a = np.array([[1, 2], [3, 4]]);
np.isin(a, [2, 3]);
// array([[false, true],
//        [true, false]])
```

***

### intersect1d

Find the sorted intersection of two arrays. Optionally return the indices of the intersecting elements in the original arrays.

```typescript theme={null}
function intersect1d(
  ar1: ArrayLike,
  ar2: ArrayLike
): NDArray
```

| Name                                            | Type        | Default | Description         |
| ----------------------------------------------- | ----------- | ------- | ------------------- |
| `ar1`                                           | `ArrayLike` | --      | First input array.  |
| `ar2`                                           | `ArrayLike` | --      | Second input array. |
| **Returns:** `NDArray` of sorted common values. |             |         |                     |

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

np.intersect1d([1, 2, 3, 4], [3, 4, 5, 6]);
// array([3, 4])
```

***

### union1d

Find the sorted union of two arrays.

```typescript theme={null}
function union1d(ar1: ArrayLike, ar2: ArrayLike): NDArray
```

| Name  | Type        | Default | Description         |
| ----- | ----------- | ------- | ------------------- |
| `ar1` | `ArrayLike` | --      | First input array.  |
| `ar2` | `ArrayLike` | --      | Second input array. |

**Returns:** `NDArray` -- Sorted 1D array of unique values present in either input.

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

np.union1d([1, 2, 3], [2, 3, 4, 5]);
// array([1, 2, 3, 4, 5])
```

***

### setdiff1d

Find the set difference: elements in `ar1` that are not in `ar2`.

```typescript theme={null}
function setdiff1d(ar1: ArrayLike, ar2: ArrayLike): NDArray
```

| Name            | Type        | Default | Description                                            |
| --------------- | ----------- | ------- | ------------------------------------------------------ |
| `ar1`           | `ArrayLike` | --      | Input array.                                           |
| `ar2`           | `ArrayLike` | --      | Elements to exclude.                                   |
| `assume_unique` | `boolean`   | `false` | If `true`, assume both arrays contain unique elements. |

**Returns:** `NDArray` -- Sorted 1D array of values in `ar1` that are not in `ar2`.

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

np.setdiff1d([1, 2, 3, 4, 5], [2, 4]);
// array([1, 3, 5])
```

***

### setxor1d

Find the symmetric difference: elements that are in either of two arrays, but not in both.

```typescript theme={null}
function setxor1d(ar1: ArrayLike, ar2: ArrayLike): NDArray
```

| Name            | Type        | Default | Description                                            |
| --------------- | ----------- | ------- | ------------------------------------------------------ |
| `ar1`           | `ArrayLike` | --      | First input array.                                     |
| `ar2`           | `ArrayLike` | --      | Second input array.                                    |
| `assume_unique` | `boolean`   | `false` | If `true`, assume both arrays contain unique elements. |

**Returns:** `NDArray` -- Sorted 1D array of values in exactly one of the two inputs.

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

np.setxor1d([1, 2, 3], [2, 3, 4]);
// array([1, 4])

np.setxor1d([1, 1, 2], [2, 3, 3]);
// array([1, 3])
```

***

### trim\_zeros

Trim leading and/or trailing zeros from a 1D array.

```typescript theme={null}
function trim_zeros(filt: ArrayLike, trim?: 'f' | 'b' | 'fb'): NDArray
```

| Name   | Type        | Default | Description                                                                               |
| ------ | ----------- | ------- | ----------------------------------------------------------------------------------------- |
| `filt` | `ArrayLike` | --      | 1D input array.                                                                           |
| `trim` | `string`    | `'fb'`  | A string of `'f'` (front), `'b'` (back), or `'fb'` (both). Controls which end(s) to trim. |

**Returns:** `NDArray` -- The trimmed array.

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

np.trim_zeros([0, 0, 1, 2, 3, 0, 0]);
// array([1, 2, 3])

np.trim_zeros([0, 0, 1, 2, 0], 'f');
// array([1, 2, 0])  -- trim front only

np.trim_zeros([0, 0, 1, 2, 0], 'b');
// array([0, 0, 1, 2])  -- trim back only
```