Documentation

This is machine translation

Translated by Microsoft
Mouseover text to see original. Click the button below to return to the English verison of the page.

Note: This page has been translated by MathWorks. Please click here
To view all translated materals including this page, select Japan from the country navigator on the bottom of this page.

join

Combine strings, or merge two tables or timetables by rows using key variables

Syntax

newStr = join(str)
newStr = join(str,delimiter)
newStr = join(str,dim)
newStr = join(str,delimiter,dim)
tblC = join(tblA,tblB)
tblC = join(tblA,tblB,Name,Value)
[tblC,ib] = join(___)

Description

example

newStr = join(str) concatenates the text in the input array str, placing a space character between consecutive elements, and returns the result as newStr. The input array str can be a string array or a cell array of character vectors. newStr has the same data type as str.

  • If str is a 1-by-N or an N-by-1 string array or cell array, then newStr is a string scalar or a cell array that contains one character vector.

  • If str is an M-by-N string array, then newStr is an M-by-1 string array or cell array.

For a string or cell array of any size, join concatenates elements along the last dimension of str with a size that does not equal 1.

example

newStr = join(str,delimiter) combines the text in str and places the elements of delimiter between the elements of str instead of a space character.

If the delimiter argument is an array of different delimiters, and str has N elements along the dimension that is joined, then delimiter must have N-1 elements along the same dimension. The other dimensions of delimiter must have either a size of 1 or the same size as the corresponding dimension of str.

example

newStr = join(str,dim) combines the elements in str along the dimension dim.

newStr = join(str,delimiter,dim) combines the elements in str along the dimension dim and places the elements of delimiter between the elements of str.

example

tblC = join(tblA,tblB) merges tblA and tblB by matching up rows, using all the variables with the same names as key variables. The key values must be common to both tblA and tblB, but can appear in different orders. tblA and tblB can be both tables, both timetables, or one of each.

  • If tblA is a table, then join returns tblC as a table.

  • If tblA is a timetable, then join returns tblC as a timetable.

join retains all the variables from tblA and appends the corresponding contents from the nonkey variables of tblB.

The row labels of tblA and tblB can be key variables. Row labels are the row names of a table, or the row times of a timetable.

example

tblC = join(tblA,tblB,Name,Value) joins the tables or timetables with additional options specified by one or more Name,Value pair arguments.

For example, you can specify which variables to use as key variables.

example

[tblC,ib] = join(___) also returns an index vector ib such that each element of ib identifies the row in tblB that corresponds to that row in tblC. You can use this syntax with any of the input arguments of the previous syntaxes for tables.

Examples

collapse all

Concatenate the strings in a string array. The join function concatenates the strings from str and places a space character between them. join concatenates along the second dimension because it is the last dimension with a size that does not equal one.

Starting in R2017a, you can create strings using double quotes instead of the string function.

str = ["John","Smith";
       "Mary","Jones";
       "Alice","White"]
str = 3×2 string array
    "John"     "Smith"
    "Mary"     "Jones"
    "Alice"    "White"

Concatenate the strings using the join function. join concatenates the strings from str and places a space character between them. join concatenates along the second dimension because it is the last dimension with a size that does not equal one.

newStr = join(str)
newStr = 3×1 string array
    "John Smith"
    "Mary Jones"
    "Alice White"

Concatenate the strings in a string array. Instead of spaces, insert different pieces of text between the strings in str.

Starting in R2017a, you can create strings using double quotes instead of the string function.

str = ["x","y","z";
       "a","b","c"]
str = 2×3 string array
    "x"    "y"    "z"
    "a"    "b"    "c"

Concatenate the strings with dashes between them.

newStr = join(str,"-")
newStr = 2×1 string array
    "x-y-z"
    "a-b-c"

Concatenate the strings with symbols that make the output strings represent equations. The delimiters argument must be a 2-by-2 array because str is a 2-by-3 array.

delimiters = [" + "," = ";
              " - "," = "];
newStr = join(str,delimiters)
newStr = 2×1 string array
    "x + y = z"
    "a - b = c"

Starting in R2017a, you can create strings using double quotes instead of the string function.

str = ["John","Smith";
       "Mary","Jones";
       "Alice","White"]
str = 3×2 string array
    "John"     "Smith"
    "Mary"     "Jones"
    "Alice"    "White"

Combine the strings in str along the first dimension. By default, the join function combines strings along the last dimension with a size that does not equal one. To combine the strings along the first dimension, specify it as an additional input argument.

newStr = join(str,1)
newStr = 1×2 string array
    "John Mary Alice"    "Smith Jones White"

Create a table, A.

A = table({'John','Jane','Jim','Jerry','Jill'}',[1;2;1;2;1],...
    'VariableNames',{'Employee' 'Department'})
A = 5×2 table
    Employee    Department
    ________    __________

    'John'      1         
    'Jane'      2         
    'Jim'       1         
    'Jerry'     2         
    'Jill'      1         

Create a table, B, with a variable in common with A.

B = table([1 2]',{'Mary' 'Mike'}',...
    'VariableNames',{'Department' 'Manager'})
B = 2×2 table
    Department    Manager
    __________    _______

    1             'Mary' 
    2             'Mike' 

Create a new table, C, containing data from tables A and B. Use the join function to repeat and append Manager data from table B to the data from table A based on the key variable, Department.

C = join(A,B)
C = 5×3 table
    Employee    Department    Manager
    ________    __________    _______

    'John'      1             'Mary' 
    'Jane'      2             'Mike' 
    'Jim'       1             'Mary' 
    'Jerry'     2             'Mike' 
    'Jill'      1             'Mary' 

Create a table, A.

A = table([5;12;23;2;6],...
    {'cereal';'pizza';'salmon';'cookies';'pizza'},...
    'VariableNames',{'Age','FavoriteFood'},...
    'RowNames',{'Amy','Bobby','Holly','Harry','Sally'})
A = 5×2 table
             Age    FavoriteFood
             ___    ____________

    Amy       5     'cereal'    
    Bobby    12     'pizza'     
    Holly    23     'salmon'    
    Harry     2     'cookies'   
    Sally     6     'pizza'     

Create a table, B, with one variable in common with A.

B = table({'cereal';'cookies';'pizza';'salmon';'cake'},...
    [110;160;140;367;243],...
    {'B';'D';'B-';'A';'C-'},...
    'VariableNames',{'FavoriteFood','Calories','NutritionGrade'})
B = 5×3 table
    FavoriteFood    Calories    NutritionGrade
    ____________    ________    ______________

    'cereal'        110         'B'           
    'cookies'       160         'D'           
    'pizza'         140         'B-'          
    'salmon'        367         'A'           
    'cake'          243         'C-'          

Create a new table, C, with data from tables A and B. Use FavoriteFood as a key variable to the join function.

C = join(A,B)
C = 5×4 table
             Age    FavoriteFood    Calories    NutritionGrade
             ___    ____________    ________    ______________

    Amy       5     'cereal'        110         'B'           
    Bobby    12     'pizza'         140         'B-'          
    Holly    23     'salmon'        367         'A'           
    Harry     2     'cookies'       160         'D'           
    Sally     6     'pizza'         140         'B-'          

Table C does not include information from the last row of table B about 'cake' since there is no corresponding entry in table A.

Create a table, A.

A = table([10;4;2;3;7],[5;4;9;6;1],[10;3;8;8;4])
A = 5×3 table
    Var1    Var2    Var3
    ____    ____    ____

    10      5       10  
     4      4        3  
     2      9        8  
     3      6        8  
     7      1        4  

Create a table, B, giving Var2 the same contents as Var2 from table A.

B = table([6;1;1;6;8],[5;4;9;6;1])
B = 5×2 table
    Var1    Var2
    ____    ____

    6       5   
    1       4   
    1       9   
    6       6   
    8       1   

Create a new table, C, containing data from tables A and B. Use Var2 in tables A and B as the key variable to the join function.

C = join(A,B,'Keys','Var2')
C = 5×4 table
    Var1_A    Var2    Var3    Var1_B
    ______    ____    ____    ______

    10        5       10      6     
     4        4        3      1     
     2        9        8      1     
     3        6        8      6     
     7        1        4      8     

join adds a unique suffix to the nonkey variable Var1 to distinguish the data from tables A and B.

Create a new table with data from tables A and B. If any nonkey variables have the same name in both tables, keep only the copy from table A.

Create a table, A.

A = table([10;4;2;3;7],[5;4;9;6;1])
A = 5×2 table
    Var1    Var2
    ____    ____

    10      5   
     4      4   
     2      9   
     3      6   
     7      1   

Create a table, B, giving Var2 the same contents as Var2 from table A.

B = table([6;1;1;6;8],[5;4;9;6;1],[10;3;8;8;4])
B = 5×3 table
    Var1    Var2    Var3
    ____    ____    ____

    6       5       10  
    1       4        3  
    1       9        8  
    6       6        8  
    8       1        4  

Create a new table, C, with data from tables A and B. Use Var2 as a key variable to the join function and keep only the copy of Var1 from table A.

C = join(A,B,'Keys','Var2','KeepOneCopy','Var1')
C = 5×3 table
    Var1    Var2    Var3
    ____    ____    ____

    10      5       10  
     4      4        3  
     2      9        8  
     3      6        8  
     7      1        4  

C does not contain the Var1 data from table B.

Create a table, A.

A = table(['M';'M';'F';'F';'F'],[38;43;38;40;49],...
    'VariableNames',{'Gender' 'Age'},...
    'RowNames',{'Smith' 'Johnson' 'Williams' 'Jones' 'Brown'})
A = 5×2 table
                Gender    Age
                ______    ___

    Smith       M         38 
    Johnson     M         43 
    Williams    F         38 
    Jones       F         40 
    Brown       F         49 

Create a table, B, such that there is a one-to-one correspondence between the rows of A and the rows of B.

B = table([64;69;67;71;64],...
    [119;163;133;176;131],...
    [122 80; 109 77; 117 75; 124 93; 125 83],...
    'VariableNames',{'Height' 'Weight' 'BloodPressure'},...
    'RowNames',{'Brown' 'Johnson' 'Jones' 'Smith' 'Williams'})
B = 5×3 table
                Height    Weight    BloodPressure
                ______    ______    _____________

    Brown       64        119       122     80   
    Johnson     69        163       109     77   
    Jones       67        133       117     75   
    Smith       71        176       124     93   
    Williams    64        131       125     83   

Create a new table, C, with data from tables A and B. Use the row names as keys to the join function.

C = join(A,B,'Keys','RowNames')
C = 5×5 table
                Gender    Age    Height    Weight    BloodPressure
                ______    ___    ______    ______    _____________

    Smith       M         38     71        176       124     93   
    Johnson     M         43     69        163       109     77   
    Williams    F         38     64        131       125     83   
    Jones       F         40     67        133       117     75   
    Brown       F         49     64        119       122     80   

The rows of C are in the same order as A.

Create a table, A.

A = table([10;4;2;3;7],[5;4;9;6;1],[10;3;8;8;4])
A = 5×3 table
    Var1    Var2    Var3
    ____    ____    ____

    10      5       10  
     4      4        3  
     2      9        8  
     3      6        8  
     7      1        4  

Create a table, B, giving Var2 the same contents as Var1 from table A, except for order.

B = table([6;1;1;6;8],[2;3;4;7;10])
B = 5×2 table
    Var1    Var2
    ____    ____

    6        2  
    1        3  
    1        4  
    6        7  
    8       10  

Create a new table, C, containing data from tables A and B. Use Var1 from table A with Var2 from table B as key variables to the join function.

[C,ib] = join(A,B,'LeftKeys',1,'RightKeys',2)
C = 5×4 table
    Var1_A    Var2    Var3    Var1_B
    ______    ____    ____    ______

    10        5       10      8     
     4        4        3      1     
     2        9        8      6     
     3        6        8      1     
     7        1        4      6     

ib = 

     5
     3
     1
     2
     4

C is the horizontal concatenation of A and B(ib,2).

Create two timetables that have the same row times and traffic data.

Traffic = [0.8 0.9 0.1 0.7 0.9]';
Noise = [0 1 1.5 2 2.3]';
A = timetable(hours(1:5)',Traffic,Noise)
A = 5×2 timetable
    Time    Traffic    Noise
    ____    _______    _____

    1 hr    0.8          0  
    2 hr    0.9          1  
    3 hr    0.1        1.5  
    4 hr    0.7          2  
    5 hr    0.9        2.3  

Distance = [0.88 0.86 0.91 0.9 0.86]';
B = timetable(hours(1:5)',Distance)
B = 5×1 timetable
    Time    Distance
    ____    ________

    1 hr    0.88    
    2 hr    0.86    
    3 hr    0.91    
    4 hr     0.9    
    5 hr    0.86    

Merge the timetables. join uses the row times as the key variables.

C = join(A,B)
C = 5×3 timetable
    Time    Traffic    Noise    Distance
    ____    _______    _____    ________

    1 hr    0.8          0      0.88    
    2 hr    0.9          1      0.86    
    3 hr    0.1        1.5      0.91    
    4 hr    0.7          2       0.9    
    5 hr    0.9        2.3      0.86    

Create a timetable and a table.

Measurements = [0.13 0.22 0.31 0.42 0.53 0.57 0.67 0.81 0.90 1.00]';
Device = ['A';'B';'A';'B';'A';'B';'A';'B';'A';'B'];
A = timetable(seconds(1:10)',Measurements,Device)
A = 10×2 timetable
     Time     Measurements    Device
    ______    ____________    ______

     1 sec    0.13            A     
     2 sec    0.22            B     
     3 sec    0.31            A     
     4 sec    0.42            B     
     5 sec    0.53            A     
     6 sec    0.57            B     
     7 sec    0.67            A     
     8 sec    0.81            B     
     9 sec     0.9            A     
    10 sec       1            B     

Device = ['A';'B'];
Accuracy = [0.023;0.037];
B = table(Device,Accuracy)
B = 2×2 table
    Device    Accuracy
    ______    ________

    A         0.023   
    B         0.037   

Merge the timetable and table. Device is the key variable because both A and B have a variable with that name. C is a timetable.

C = join(A,B)
C = 10×3 timetable
     Time     Measurements    Device    Accuracy
    ______    ____________    ______    ________

     1 sec    0.13            A         0.023   
     2 sec    0.22            B         0.037   
     3 sec    0.31            A         0.023   
     4 sec    0.42            B         0.037   
     5 sec    0.53            A         0.023   
     6 sec    0.57            B         0.037   
     7 sec    0.67            A         0.023   
     8 sec    0.81            B         0.037   
     9 sec     0.9            A         0.023   
    10 sec       1            B         0.037   

Input Arguments

collapse all

Input text, specified as a string array or a cell array of character vectors.

Delimiting characters for joining strings, specified as a character vector, a cell array of character vectors, or a string array. join forms the output string array by combining string elements with delimiters between them.

join inserts all characters in delimiter as literal text, including escaped character sequences.

Dimension along which to join strings, specified as a positive integer scalar. If dim is not specified, then the default is the last dimension with a size that does not equal 1.

Input tables, specified as tables, timetables, or as one of each. For all key variables, each row of tblA must match exactly one row in tblB.

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside single quotes (' '). You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: 'Keys',2 uses the second variable in tblA and the second variable in tblB as key variables.

collapse all

Variables to use as keys, specified as the comma-separated pair consisting of 'Keys' and a positive integer, vector of positive integers, character vector, cell array of character vectors, logical vector, or 'RowNames'.

You cannot use the 'Keys' name-value pair argument with the 'LeftKeys' and 'RightKeys' name-value pair arguments.

Row labels can be key variables. Row labels are the row names of a table or the row times of a timetable. You can specify 'Keys' as the row labels only, as one or more variables in tblA and tblB, or as row labels and variables together.

If you specify the value 'RowNames', then join uses the row names of tblA and row names of tblB as keys. In this case, there must be a row in tblB for every row in tblA. You cannot specify 'RowNames' when tblA is a timetable.

Example: 'Keys',[1 3] uses the first and third variables from tblA and tblB as a key variables.

Variables to use as keys in tblA, specified as the comma-separated pair consisting of 'LeftKeys' and a positive integer, vector of positive integers, character vector, cell array of character vectors, or logical vector.

You must use the 'LeftKeys' name-value pair argument in conjunction with the 'RightKeys' name-value pair argument. 'LeftKeys' and 'RightKeys' both must specify the same number of key variables. join pairs key values based on their order.

Row labels can be key variables. Row labels are the row names of a table or the row times of a timetable. You can specify 'LeftKeys' as the row labels of tblA, as one or more variables in tblA, or as row labels and variables together.

Example: 'LeftKeys',1 uses only the first variable in tblA as a key variable.

Variables to use as keys in tblB, specified as the comma-separated pair consisting of 'RightKeys' and a positive integer, vector of positive integers, character vector, cell array of character vectors, or logical vector.

You must use the 'RightKeys' name-value pair argument in conjunction with the 'LeftKeys' name-value pair argument. 'LeftKeys' and 'RightKeys' both must specify the same number of key variables. join pairs values in tblA and tblB based on their order.

Row labels can be key variables. Row labels are the row names of a table or the row times of a timetable. You can specify 'RightKeys' as the row labels of tblB, as one or more variables in tblB, or as row labels and variables together.

Example: 'RightKeys',3 uses only the third variable in tblB as a key variable.

Variables from tblA to include in tblC, specified as the comma-separated pair consisting of 'LeftVariables' and a positive integer, vector of positive integers, character vector, cell array of character vectors, or logical vector.

You can use 'LeftVariables' to include or exclude key variables, as well as nonkey variables from the output, tblC. However, you cannot include row names or row times from tblA, because they are not variables.

By default, join includes all variables from tblA.

Variables from tblB to include in tblC, specified as the comma-separated pair consisting of 'RightVariables' and a positive integer, vector of positive integers, character vector, cell array of character vectors, or logical vector.

You can use 'RightVariables' to include or exclude key variables, as well as nonkey variables from the output, tblC. However, you cannot include row names or row times from tblB, because they are not variables.

By default, join includes all the variables from tblB except the key variables.

Variables for which join retains only the copy from tblA, specified as the comma-separated pair consisting of 'KeepOneCopy' and a character vector or a cell array of character vectors that specify variable names.

Key variables appear once in tblC, but if nonkey variables with identical names occur in tblA and tblB, then join retains both copies in tblC by default. Use the 'KeepOneCopy' name-value pair to retain only the copy from tblA.

Example: 'KeepOneCopy',Var2 keeps only the copy from tblA of the nonkey variable Var2.

Output Arguments

collapse all

Output text, returned as a string array or a cell array of character vectors. newStr has a size of 1 along the dimension being joined.

newStr has the same data type as the input text.

Merged data from tblA and tblB, returned as a table or a timetable. The table, tblC, contains one row for each row in tblA, appearing in the same order.

join creates tblC by horizontally concatenating tblA(:,LeftVars) and tblB(ib,RightVars). By default, LeftVars is all the variables of tblA, and RightVars is all the nonkey variables from tblB. Otherwise, LefttVars consists of the variables specified by the 'LeftVariables' name-value pair argument, and RightVars consists of the variables specified by the 'RightVariables' name-value pair argument.

If tblA and tblB contain nonkey variables with the same name, join adds a unique suffix to the corresponding variable names in tblC, unless you specify the 'KeepOneCopy' name-value pair argument.

If tblA is a table, then tblC is also a table. If tblA is a timetable and tblB is either a timetable or a table, then tblC is a timetable.

You can store additional metadata such as descriptions, variable units, variable names, and row names in tblC. For more information, see Table Properties or Timetable Properties.

Index to tblB, returned as a column vector. Each element of ib identifies the row in tblB that corresponds to that row in the output table or timetable, tblC.

More About

collapse all

Key Variable

Variable used to match and combine data between the input tables, tblA and tblB.

Key Value

Entry in a key variable of tblA.

Algorithms

The join function first finds one or more key variables. Then, join uses the key variables to find the row in input table tblB that matches each row in input table tblA, and combines those rows to create a row in output table tblC.

  • If there is a one-to-one mapping between key values in tblA and tblB, then join sorts the data in tblB and appends it to table tblA.

  • If there is a many-to-one mapping between key values in tblA and tblB, then join sorts and repeats the data in tblB before appending it to table tblA.

  • If there is data in a key variable of tblB that does not map to a key value in tblA, then join does not include that data in the output table, tblC.

Extended Capabilities

Introduced in R2013b

Was this topic helpful?