# union

Set union of two arrays

## Syntax

• `C = union(A,B)` example
• `C = union(A,B,'rows')`
• ```[C,ia,ib] = union(A,B)``` example
• ```[C,ia,ib] = union(A,B,'rows')``` example
• ```[C,ia,ib] = union(___,setOrder)``` example
• ```[C,ia,ib] = union(A,B,'legacy')``` example
• ```[C,ia,ib] = union(A,B,'rows','legacy')``` example

## Description

example

````C = union(A,B)` returns the combined data from `A` and `B` with no repetitions.If `A` and `B` are numeric arrays, logical arrays, character arrays, categorical arrays, datetime arrays, duration arrays, or cell arrays of strings, then `union` returns the combined values from `A` and `B`. The values of `C` are in sorted order.If `A` and `B` are tables, then `union` returns the combined set of rows from both tables. The rows of table `C` are in sorted order.```
````C = union(A,B,'rows')` treats each row of `A` and each row of `B` as single entities and returns the combined rows from `A` and `B` with no repetitions. The rows of `C` are in sorted order.The `'rows'` option does not support cell arrays, unless one of the inputs is either a categorical array or a datetime array.```

example

``````[C,ia,ib] = union(A,B)``` also returns index vectors `ia` and `ib`.If `A` and `B` are numeric arrays, logical arrays, character arrays, categorical arrays, datetime arrays, duration arrays, or cell arrays of strings, then the values in `C` are a sorted combination of the values of `A(ia)` and `B(ib)`.If `A` and `B` are tables, then `C` is a sorted combination of the rows of `A(ia,:)` and `B(ib,:)`.```

example

``````[C,ia,ib] = union(A,B,'rows')``` also returns index vectors `ia` and `ib`, such that the rows of `C` are a sorted combination of the rows of `A(ia,:)` and `B(ib,:)`. ```

example

``````[C,ia,ib] = union(___,setOrder)``` returns `C` in a specific order using any of the input arguments in the previous syntaxes. `setOrder='sorted'` returns the values (or rows) of `C` in sorted order. `setOrder='stable'` returns the values (or rows) of `C` in the same order as `A`, and then `B`. If no value is specified, the default is `'sorted'`.```

example

``````[C,ia,ib] = union(A,B,'legacy')``` and ```[C,ia,ib] = union(A,B,'rows','legacy')``` preserve the behavior of the `union` function from R2012b and prior releases. The `'legacy'` option does not support categorical arrays, tables, datetime arrays, or duration arrays.```

## Examples

collapse all

### Union of Two Vectors

Define two vectors with a value in common.

`A = [5 7 1]; B = [3 1 1];`

Find the union of vectors `A` and `B`.

`C = union(A,B)`
```C = 1 3 5 7```

### Union of Two Tables

Define two tables with rows in common.

```A = table([1:5]',['A';'B';'C';'D';'E'],logical([0;1;0;1;0])) B = table([1:2:10]',['A';'C';'E';'G';'I'],logical(zeros(5,1)))```
```A = Var1 Var2 Var3 ---- ---- ----- 1 A false 2 B true 3 C false 4 D true 5 E false B = Var1 Var2 Var3 ---- ---- ----- 1 A false 3 C false 5 E false 7 G false 9 I false```

Find the union of tables `A` and `B`.

`C = union(A,B)`
```C = Var1 Var2 Var3 ---- ---- ----- 1 A false 2 B true 3 C false 4 D true 5 E false 7 G false 9 I false ```

### Union of Two Vectors and Their Indices

Define two vectors with a value in common.

`A = [5 7 1]; B = [3 1 1];`

Find the union of vectors `A` and `B`, as well as the index vectors, `ia` and `ib`.

```[C,ia,ib] = union(A,B) ```
```C = 1 3 5 7 ia = 3 1 2 ib = 1 ```

The values in `C` are the combined values of `A(ia)` and `B(ib)`.

### Union of Two Tables and Their Indices

Define a table, `A`, of gender, age, and height for three people.

```A = table(['M';'M';'F'],[27;52;31],[74;68;64],... 'VariableNames',{'Gender' 'Age' 'Height'},... 'RowNames',{'Ted' 'Fred' 'Betty'})```
```A = Gender Age Height ------ --- ------ Ted M 27 74 Fred M 52 68 Betty F 31 64 ```

Define a table, `B` with the same variables as `A`.

```B = table(['F';'M'],[64;68],[31;47],... 'VariableNames',{'Gender' 'Height' 'Age'},... 'RowNames',{'Meg' 'Joe'})```
```B = Gender Height Age ------ ------ --- Meg F 64 31 Joe M 68 47 ```

Find the union of tables `A` and `B`, as well as the index vectors, `ia` and `ib`.

`[C,ia,ib] = union(A,B)`
```C = Gender Age Height ------ --- ------ Betty F 31 64 Ted M 27 74 Joe M 47 68 Fred M 52 68 ia = 3 1 2 ib = 2```

The data for `Meg` and `Betty` are the same. `union` only returns the index from `A`, which corresponds to `Betty`.

### Union of Rows in Two Matrices

Define two matrices with a row in common.

```A = [2 2 2; 0 0 1]; B = [1 2 3; 2 2 2; 2 2 2];```

Find the combined rows of `A` and `B`, with no repetition, as well as the index vectors `ia` and `ib`.

```[C,ia,ib] = union(A,B,'rows') ```
```C = 0 0 1 1 2 3 2 2 2 ia = 2 1 ib = 1 ```

The rows of `C` are the combined rows of `A(ia,:)` and `B(ib,:)`.

### Union of Two Vectors with Specified Output Order

Use the `setOrder` argument to specify the ordering of the values in `C`.

Specify `'stable'` if you want the values in `C` to have the same order as in `A` and `B`.

```A = [5 7 1]; B = [3 1 1]; [C,ia,ib] = union(A,B,'stable')```
```C = 5 7 1 3 ia = 1 2 3 ib = 1```

Alternatively, you can specify `'sorted'` order.

```A = [5 7 1]; B = [3 1 1]; [C,ia,ib] = union(A,B,'sorted')```
```C = 1 3 5 7 ia = 3 1 2 ib = 1```

### Union of Vectors Containing NaNs

Define two vectors containing `NaN`.

`A = [5 NaN 1]; B = [4 NaN NaN];`

Find the union of vectors `A` and `B`.

`C = union(A,B)`
```C = 1 4 5 NaN NaN NaN```

`union` treats `NaN` values as distinct.

### Cell Array of Strings with Trailing White Space

Create a cell array of strings, `A`.

```A = {'dog','cat','fish','horse'}; ```

Create a cell array of strings, `B`, where some of the strings have trailing white space.

`B = {'dog ','cat','fish ','horse'};`

Combine the elements of `A` and `B`.

`[C,ia,ib] = union(A,B)`
```C = 'cat' 'dog' 'dog ' 'fish' 'fish ' 'horse' ia = 2 1 3 4 ib = 1 3```

`union` treats trailing white space in cell arrays of strings as distinct characters.

### Union of Vectors of Different Classes and Shapes

Create a column vector character array.

```A = ['A';'B';'C'], class(A) ```
```A = A B C ans = char ```

Create a row vector containing elements of numeric type `double`.

```B = [68 69 70], class(B) ```
```B = 68 69 70 ans = double ```

The `union` of `A` and `B` returns a column vector character array.

```C = union(A,B), class(C) ```
```C = A B C D E F ans = char ```

### Union of Char and Cell Array of Strings

Create a character array containing the letters `a` , `b`, and `c`.

```A = ['a';'b';'c']; class(A) ```
```ans = char ```

Create a cell array of strings containing the letters `c`, `d`, and `e`.

```B = {'c','d','e'}; class(B) ```
```ans = cell ```

Combine the elements of `A` and `B`.

```C = union(A,B) ```
```C = 'a' 'b' 'c' 'd' 'e' ```

The result, `C`, is a cell array of strings.

```class(C) ```
```ans = cell ```

### Preserve Legacy Behavior of union

Use the `'legacy'` flag to preserve the behavior of `union` from R2012b and prior releases in your code.

Find the union of `A` and `B` with the current behavior.

```A = [5 7 1]; B = [3 1 1]; [C1,ia1,ib1] = union(A,B) ```
```C1 = 1 3 5 7 ia1 = 3 1 2 ib1 = 1```

Find the union of `A` and `B`, and preserve the legacy behavior.

```A = [5 7 1]; B = [3 1 1]; [C2,ia2,ib2] = union(A,B,'legacy')```
```C2 = 1 3 5 7 ia2 = 1 2 ib2 = 3 1```

## Input Arguments

collapse all

### `A,B` — Input arraysnumeric arrays | logical arrays | character arrays | categorical arrays | datetime arrays | duration arrays | cell arrays of strings | tables

Input arrays, specified as numeric arrays, logical arrays, character arrays, categorical arrays, datetime arrays, duration arrays, cell arrays of strings, or tables.

`A` and `B` must be of the same class with the following exceptions:

• `logical`, `char`, and all numeric classes can combine with `double` arrays.

• Cell arrays of strings can combine with `char` arrays.

• Categorical arrays can combine with cell arrays of strings or single strings.

• Datetime arrays can combine with cell arrays of date strings or single date strings.

If `A` and `B` are both ordinal categorical arrays, they must have the same sets of categories, including their order. If neither `A` nor `B` are ordinal, they need not have the same sets of categories, and the comparison is performed using the category names. In this case, the categories of `C` are the sorted union of the categories from `A` and `B`.

If you specify the `'rows'` option, `A` and `B` must have the same number of columns.

If `A` and `B` are tables, they must have the same variable names. Conversely, the row names do not matter. Two rows that have the same values, but different names, are considered equal.

If `A` and `B` are datetime arrays, they must be consistent with each other in whether they specify a time zone.

Furthermore, `A` and `B` can be objects with the following class methods:

• `sort` (or `sortrows` for the `'rows'` option)

• `ne`

The object class methods must be consistent with each other. These objects include heterogeneous arrays derived from the same root class.

### `setOrder` — Order flag`'sorted'` (default) | `'stable'`

Order flag, specified as `'sorted'` or `'stable'`, indicates the order of the values (or rows) in `C`.

Order FlagMeaning
`'sorted'`The values (or rows) in `C` return in sorted order. For example: ```C = union([5 5 3],[1 2],'sorted')``` returns ```C = [1 2 3 5]```.
`'stable'`The values (or rows) in `C` return in the same order as they appear in `A` and `B`. For example: `C = union([5 5 3],[1 2],'stable')` returns `C = [5 3 1 2]`.

## Output Arguments

collapse all

### `C` — Combined data of `A` and `B`vector | matrix | table

Combined data of `A` and `B`, returned as a vector, matrix, or table. If the inputs `A` and `B` are tables, the order of the variables in the resulting table, `C`, is the same as the order of the variables in `A`.

The following describes the shape of `C` when the inputs are vector or matrices and when the `'legacy'` flag is not specified:

• If the `'rows'` flag is not specified, then `C` is a column vector unless both `A` and `B` are row vectors.

• If the `'rows'` flag is not specified and both `A` and `B` are row vectors, then `C` is a row vector.

• If the `'rows'` flag is specified, then `C` is a matrix containing the combined rows of `A` and `B`.

The class of the inputs `A` and `B` determines the class of `C`:

• If the class of `A` and `B` are the same, then `C` is the same class.

• If you combine a `char` or nondouble numeric class with `double`, then `C` is the same class as the nondouble input.

• If you combine a `logical` class with `double`, then `C` is `double`.

• If you combine a cell array of strings with `char`, then `C` is a cell array of strings.

• If you combine a categorical array with a cell array of strings or single string, then `C` is a categorical array.

• If you combine a datetime array with a cell array of date strings or single date string, then `C` is a datetime array.

### `ia` — Index to `A`column vector

Index to `A`, returned as a column vector when the `'legacy'` flag is not specified. `ia` indicates the values (or rows) in `A` that contribute to the union. If a value (or row) appears multiple times in `A`, then `ia` contains the index to the first occurrence of the value (or row). If a value appears in both `A` and `B`, then `ia` contains the index to the first occurrence in `A`.

### `ib` — Index to `B`column vector

Index to `B`, returned as a column vector when the `'legacy'` flag is not specified. `ib` indicates the values (or rows) in `B` that contribute to the union. If there is a repeated value (or row) appearing exclusively in `B`, then `ib` contains the index to the first occurrence of the value. If a value (or row) appears in both `A` and `B`, then `ib` does not contain an index to the value (or row).

collapse all

### Tips

• To find the union with respect to a subset of variables from a table, you can use column subscripting. For example, you can use `union(A(:,vars),B(:,vars))`, where `vars` is a positive integer, a vector of positive integers, a variable name, a cell array of variable names, or a logical vector.