Accelerating the pace of engineering and science

# 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

expand 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

expand 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

expand all

### C — Combined data of A and Bvector | 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 Acolumn 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 Bcolumn 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).