union

Union of two sets of data

Syntax

C = union(A,B)

C = union(A,B,setOrder)

C = union(A,B,___,'rows')

C = union(A,B,'rows',___)

[C,ia,ib] = union(___)

[C,ia,ib] = union(A,B,'legacy')

[C,ia,ib] = union(A,B,'rows','legacy')

Description

C = union(A,B) returns the combined data from A and B with no repetitions. C is in sorted order.

• If A and B are tables or timetables, then union returns the combined set of rows from both tables. For timetables, union takes row times into account to determine equality, and sorts the output timetable C by row times.

C = union(A,B,setOrder) returns C in a specific order. setOrder can be 'sorted' or 'stable'.

C = union(A,B,___,'rows') and C = union(A,B,'rows',___) treat each row of A and each row of B as single entities and return the combined rows from A and B, with no repetitions. You must specify A and B and optionally can specify setOrder.

The 'rows' option does not support cell arrays, unless one of the inputs is either a categorical array or a datetime array.

[C,ia,ib] = union(___) also returns index vectors ia and ib using any of the previous syntaxes.

• Generally, the values in C are a sorted combination of the elements of A(ia) and B(ib).

• If the 'rows' option is specified, then the rows of C are a sorted combination of the rows of A(ia,:) and B(ib,:).

• If A and B are tables or timetables, then C is a sorted combination of the rows of A(ia,:) and B(ib,:).

[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, datetime arrays, duration arrays, tables, or timetables.

Examples

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×4

     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]))

A=5×3 table
    Var1    Var2    Var3 
    ____    ____    _____

     1       A      false
     2       B      true 
     3       C      false
     4       D      true 
     5       E      false

B = table([1:2:10]',['A';'C';'E';'G';'I'],logical(zeros(5,1)))

B=5×3 table
    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=7×3 table
    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×4

     1     3     5     7

ia = 3×1

     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=3×3 table
             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=2×3 table
           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=4×3 table
             Gender    Age    Height
             ______    ___    ______

    Betty      F       31       64  
    Ted        M       27       74  
    Joe        M       47       68  
    Fred       M       52       68  

ia = 3×1

     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 = 3×3

     0     0     1
     1     2     3
     2     2     2

ia = 2×1

     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 = 1×4

     5     7     1     3

ia = 3×1

     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×4

     1     3     5     7

ia = 3×1

     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×6

     1     4     5   NaN   NaN   NaN

union treats NaN values as distinct.

Cell Array of Character Vectors with Trailing White Space

Create a cell array of character vectors, A.

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

Create a cell array of character vectors, B, where some of the vectors have trailing white space.

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

Combine the elements of A and B.

[C,ia,ib] = union(A,B)

C = 1x6 cell
    {'cat'}    {'dog'}    {'dog '}    {'fish'}    {'fish '}    {'horse'}

ia = 4×1

     2
     1
     3
     4

ib = 2×1

     1
     3

union treats trailing white space in cell arrays of character vectors as distinct characters.

Union of Vectors of Different Classes and Shapes

Create a column vector character array.

A = ['A';'B';'C']

A = 3x1 char array
    'A'
    'B'
    'C'

class(A)

ans = 
'char'

Create a row vector containing elements of numeric type double.

B = [68 69 70]

B = 1×3

    68    69    70

class(B)

ans = 
'double'

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

C = union(A,B)

C = 6x1 char array
    'A'
    'B'
    'C'
    'D'
    'E'
    'F'

class(C)

ans = 
'char'

Union of Char and Cell Array of Character Vectors

Create a character vector containing the letters a , b, and c.

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

ans = 
'char'

Create a cell array of character vectors 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 = 5x1 cell
    {'a'}
    {'b'}
    {'c'}
    {'d'}
    {'e'}

The result, C, is a cell array of character vectors.

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×4

     1     3     5     7

ia1 = 3×1

     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×4

     1     3     5     7

ia2 = 1×2

     1     2

ib2 = 1×2

     3     1

Input Arguments

A,B — Input arrays

arrays

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

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

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

• String arrays can combine with character vectors and cell arrays of character vectors.

• Categorical arrays can combine with string scalars and character vectors.

• Datetime and duration arrays can combine with string scalars and character vectors that are formatted to represent dates and times.

There are additional requirements for A and B based on data type:

• 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 consist of the categories of A followed by the categories of B that are not in A. The categories are in the same order as in A and B, and the category order is used for sorting C.

• If A and B are tables or timetables, they must have the same variable names (except for order). For tables, row names are ignored, so that two rows that have the same values, but different names, are considered equal. For timetables, row times are taken into account, so that two rows that have the same values, but different times, are not considered equal.

• If A and B are datetime arrays, then both arrays must either specify time zones or be unzoned.

A and B also 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. For example, A and B can be arrays of handles to graphics objects.

setOrder — Order flag

'sorted' (default) | 'stable'

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

Flag	Description
'sorted'	The values (or rows) in C return in sorted order as returned by sort. Example C = union([5 5 3],[1 2 5],'sorted') C = 1 2 3 5
'stable'	The values (or rows) in C return in the same order as they appear in A, then B. Example C = union([5 5 3],[1 2 5],'stable') C = 5 3 1 2

Data Types: char | string

Output Arguments

C — Combined data of A and B

vector | matrix | table | timetable

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

The following describes the shape of C when the inputs are vectors 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, in which case C is a row vector. For example, union([],[1 2]) returns a column 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 character vectors with char, then C is a cell array of character vectors.

• If you combine a categorical array with a character vector, cell array of character vectors, or string, then C is a categorical array.

• If you combine a datetime array with a cell array of date character vectors or single date character vector, then C is a datetime array.

• If you combine a string array with a character vector or cell array of character vectors, then C is a string 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).

Tips

• To find the union with respect to a subset of variables from a table or timetable, 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. Alternatively, you can use vartype to create a subscript that selects variables of a specified type.

Extended Capabilities

Tall Arrays

Calculate with arrays that have more rows than fit in memory.

The union function supports tall arrays with the following usage notes and limitations:

• The 'stable' sorting order is not supported.

• The 'legacy' flag is not supported.

• Inputs of type char are not supported.

• Ordinal categorical arrays are not supported.

For more information, see Tall Arrays.

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• Code generation does not support cell arrays for the first or second arguments.

• Code generation does not support union between a variable-size rows and columns. A and B must be variable-size vector inputs with the same orientation.

• When you do not specify the 'rows' option:

  • Inputs A and B must be vectors with the same orientation. If you specify the 'legacy' option, then inputs A and B must be row vectors.

  • The first dimension of a variable-size row vector must have fixed length 1. The second dimension of a variable-size column vector must have fixed length 1.

  • The input[] is not supported. Use a 1-by-0 or 0-by-1 input, for example , zeros(1,0), to represent the empty set.

  • If you specify the 'legacy' option, then empty outputs are row vectors, 1-by-0. They are never 0-by-0.

• When you specify both the 'legacy' option and the 'rows' option, the outputs ia and ib are column vectors. If these outputs are empty, they are 0-by-1. They are never 0-by-0, even if the output C is 0-by-0.

• When the setOrder is not 'stable' or when you specify the 'legacy' option, the inputs must already be sorted in ascending order. The first output, C, is sorted in ascending order.

• Complex inputs must be single or double.

• When one input is complex and the other input is real, do one of the following:

  • Set setOrder to 'stable'.

  • Sort the real input in complex ascending order (by absolute value). Suppose the real input is x. Use sort(complex(x))or sortrows(complex(x)).

• See Code Generation for Complex Data with Zero-Valued Imaginary Parts (MATLAB Coder).

Thread-Based Environment
Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

GPU Arrays

Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

The union function supports GPU array input with these usage notes and limitations:

• The 'legacy' flag is not supported.

• 64-bit integers are not supported.

For more information, see Run MATLAB Functions on a GPU (Parallel Computing Toolbox).

Distributed Arrays

Partition large arrays across the combined memory of your cluster using Parallel Computing Toolbox™.

Usage notes and limitations:

• The 'legacy' flag is not supported.

• Table, timetable, categorical, datetime and duration inputs are not supported.

• Inputs of type char and string are not supported when A or B is a cell array of character vectors. Convert cell arrays of character vectors input arguments to string arrays instead.

For more information, see Run MATLAB Functions with Distributed Arrays (Parallel Computing Toolbox).

Version History

Introduced before R2006a