Main Content

union

Set union of two arrays

collapse all in page

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

example

C= union(A,B)returns the combined data fromAandBwith no repetitions.Cis in sorted order.

  • IfAandBare tables or timetables, thenunionreturns the combined set of rows from both tables. For timetables,uniontakes row times into account to determine equality, and sorts the output timetableCby row times.

example

C= union(A,B,setOrder)returnsCin a specific order.setOrdercan be'sorted'or'stable'.

C= union(A,B,___,'rows')andC= union(A,B,'rows',___)treat each row ofAand each row ofBas single entities and return the combined rows fromAandB, with no repetitions. You must specifyAandBand optionally can specifysetOrder.

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(___)also returns index vectorsiaandibusing any of the previous syntaxes.

  • Generally, the values inCare a sorted combination of the elements ofA(ia)andB(ib).

  • If the'rows'option is specified, then the rows ofCare a sorted combination of the rows ofA(ia,:)andB(ib,:).

  • IfAandBare tables or timetables, thenCis a sorted combination of the rows ofA(ia,:)andB(ib,:).

example

[C,ia,ib] = union(A,B,'legacy')and[C,ia,ib] = union(A,B,'rows','legacy')preserve the behavior of theunionfunction from R2012b and prior releases.

The'legacy'option does not support categorical arrays, datetime arrays, duration arrays, tables, or timetables.

Examples

collapse all

Open Live Script

定义两个向量的值共同之处。

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

Find the union of vectorsAandB.

C = union(A,B)
C =1×41 35 7
Open Live Script

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 tableVar1 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 tableVar1 Var2 Var3 ____ ____ _____ 1 A false 3 C false 5 E false 7 G false 9 I false

Find the union of tablesAandB.

C = union(A,B)
C=7×3 tableVar1 Var2 Var3 ____ ____ _____ 1 A false 2 B true 3 C false 4 D true 5 E false 7 G false 9 I false
Open Live Script

定义两个向量的值共同之处。

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

Find the union of vectorsAandB, as well as the index vectors,iaandib.

[C,ia,ib] = union(A,B)
C =1×41 35 7
ia =3×13 1 2
ib = 1

The values inCare the combined values ofA(ia)andB(ib).

Open Live Script

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 tableGender Age Height ______ ___ ______ Ted M 27 74 Fred M 52 68 Betty F 31 64

Define a table,Bwith the same variables asA.

B = table(['F';'M'],[64;68],[31;47],...'VariableNames',{'Gender''Height''Age'},...'RowNames',{'Meg''Joe'})
B=2×3 tableGender Height Age ______ ______ ___ Meg F 64 31 Joe M 68 47

Find the union of tablesAandB, as well as the index vectors,iaandib.

[C,ia,ib] = union(A,B)
C=4×3 tableGender Age Height ______ ___ ______ Betty F 31 64 Ted M 27 74 Joe M 47 68 Fred M 52 68
ia =3×13 1 2
ib = 2

The data forMegandBettyare the same.uniononly returns the index fromA, which corresponds toBetty.

Open Live Script

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 ofAandB, with no repetition, as well as the index vectorsiaandib.

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

The rows ofCare the combined rows ofA(ia,:)andB(ib,:).

Open Live Script

Use thesetOrderargument to specify the ordering of the values inC.

Specify'stable'if you want the values inCto have the same order as inAandB.

A = [5 7 1]; B = [3 1 1]; [C,ia,ib] = union(A,B,'stable')
C =1×45 7 1 3
ia =3×11 23
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×41 35 7
ia =3×13 1 2
ib = 1
Open Live Script

Define two vectors containingNaN.

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

Find the union of vectorsAandB.

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

uniontreatsNaNvalues as distinct.

Open Live Script

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 ofAandB.

[C,ia,ib] = union(A,B)
C =1x6 cell{'cat'} {'dog'} {'dog '} {'fish'} {'fish '} {'horse'}
ia =4×12 1 3 4
ib =2×11 3

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

Open Live Script

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 typedouble.

B = [68 69 70]
B =1×368 69 70
class(B)
ans ='double'

TheunionofAandBreturns a column vector character array.

C = union(A,B)
C =6x1 char array'A' 'B' 'C' 'D' 'E' 'F'
class(C)
ans ='char'
Open Live Script

Create a character vector containing the lettersa,b, andc.

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

Create a cell array of character vectors containing the lettersc,d, ande.

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

Combine the elements ofAandB.

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'
Open Live Script

Use the'legacy'flag to preserve the behavior ofunionfrom R2012b and prior releases in your code.

Find the union ofAandBwith the current behavior.

A = [5 7 1]; B = [3 1 1]; [C1,ia1,ib1] = union(A,B)
C1 =1×41 35 7
ia1 =3×13 1 2
ib1 = 1

Find the union ofAandB, and preserve the legacy behavior.

A = [5 7 1]; B = [3 1 1]; [C2,ia2,ib2] = union(A,B,'legacy')
C2 =1×41 35 7
ia2 =1×21 2
ib2 =1×23 1

Input Arguments

collapse all

Input arrays. If you specify the'rows'option, thenAandBmust have the same number of columns.

AandBmust be of the same class with the following exceptions:

  • logical,char, and all numeric classes can combine withdoublearrays.

  • Cell arrays of character vectors can combine with character arrays or string arrays.

  • Categorical arrays can combine with character arrays, cell arrays of character vectors, or string arrays.

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

There are additional requirements forAandBbased on data type:

  • IfAandBare both ordinal categorical arrays, they must have the same sets of categories, including their order. If neitherAnorBare ordinal, they need not have the same sets of categories, and the comparison is performed using the category names. In this case, the categories ofCconsist of the categories ofAfollowed by the categories ofBthat are not inA. The categories are in the same order as inAandB秩序是用于排序和类别C.

  • IfAandBare 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.

  • IfAandBare datetime arrays, they must be consistent with each other in whether they specify a time zone.

AandBalso can be objects with the following class methods:

  • sort(orsortrowsfor 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,AandBcan be arrays of handles to graphics objects.

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

Flag Description
'sorted'

The values (or rows) inCreturn in sorted order as returned bysort.

Example

C = union([5 5 3],[1 2 5],'sorted')
C = 1 2 3 5
'stable'

The values (or rows) inCreturn in the same order as they appear inA, thenB.

Example

C = union([5 5 3],[1 2 5],'stable')
C = 5 3 1 2

Data Types:char|string

Output Arguments

collapse all

Combined data ofAandB, returned as a vector, matrix, table, or timetable. If the inputsAandBare tables or timetables, then the order of the variables inCis the same as the order of the variables inA.

The following describes the shape ofCwhen the inputs are vectors or matrices and when the'legacy'flag is not specified:

  • If the'rows'flag is not specified, thenCis a column vector unless bothAandB在这种情况下,行向量吗Cis a row vector. For example,union([],[1 2])returns a column vector.

  • If the'rows'flag is specified, thenCis a matrix containing the combined rows ofAandB.

The class of the inputsAandBdetermines the class ofC:

  • If the class ofAandBare the same, thenCis the same class.

  • If you combine acharor nondouble numeric class withdouble, thenCis the same class as the nondouble input.

  • If you combine alogicalclass withdouble, thenCisdouble.

  • If you combine a cell array of character vectors withchar, thenCis a cell array of character vectors.

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

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

  • If you combine a string array with a character vector or cell array of character vectors, thenCis a string array.

Index toA, returned as a column vector when the'legacy'flag is not specified.iaindicates the values (or rows) inAthat contribute to the union. If a value (or row) appears multiple times inA, theniacontains the index to the first occurrence of the value (or row). If a value appears in bothAandB, theniacontains the index to the first occurrence inA.

Index toB, returned as a column vector when the'legacy'flag is not specified.ibindicates the values (or rows) inBthat contribute to the union. If there is a repeated value (or row) appearing exclusively inB, thenibcontains the index to the first occurrence of the value. If a value (or row) appears in bothAandB, thenibdoes 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 useunion(A(:,vars),B(:,vars)), wherevarsis a positive integer, a vector of positive integers, a variable name, a cell array of variable names, or a logical vector. Alternatively, you can usevartypeto create a subscript that selects variables of a specified type.

Extended Capabilities

Version History

Introduced before R2006a

See Also

||||||

Topics