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)
    example
  • newStr = join(str,delimiter)
    example
  • newStr = join(str,dim)
    example
  • newStr = join(str,delimiter,dim)

Description

example

newStr = join(str) concatenates the strings in str, placing a space character between consecutive strings, and returns the result as a string array.

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

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

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

example

newStr = join(str,delimiter) combines the strings in str and places the elements of delimiter between the strings 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 strings in str along the dimension dim.

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

example

tblC = join(tblA,tblB) merges tables 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.

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

If both tblA and tblB are timetables, then the key variables are the vectors of row times from tblA and tblB. If tblA is a timetable and tblB is a table, then the key variables are all the variables from tblA and tblB with the same names. The output argument, tblC, is a timetable that has the same row times as tblA. If tblA is a table, then tblB cannot be 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.

str = string({'John','Smith';
              'Mary','Jones';
              'Alice','White'})
str = 

  3×2 string array

    "John"     "Smith"
    "Mary"     "Jones"
    "Alice"    "White"

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.

Concatenate the strings with dashes between them.

str = string({'x','y','z';
              'a','b','c'})
str = 

  2×3 string array

    "x"    "y"    "z"
    "a"    "b"    "c"

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"

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.

str = string({'John','Smith';...
              'Mary','Jones';...
              'Alice','White'})
str = 

  3×2 string array

    "John"     "Smith"
    "Mary"     "Jones"
    "Alice"    "White"

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 = 

    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 = 

    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 = 

    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 = 

             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 = 

    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 = 

             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 = 

    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 = 

    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 Var1 in table A and Var2 in table B as key variables to the join function.

C = join(A,B,'Keys','Var2')
C = 

    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 = 

    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 = 

    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 = 

    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 = 

                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 = 

                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 = 

                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 = 

    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 = 

    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 = 

    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 = 

    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 = 

    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 = 

    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 = 

     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 = 

    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 = 

     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 a timetable and a table. For all key variables, each row of tblA must match exactly one row in tblB.

If tblA is a timetable, then tblB can be either a timetable or a table. However, if tblA is a table, then tblB cannot be a timetable.

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

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.

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

If both tblA and tblB are timetables, then 'Keys' must specify the row times of tblA and tblB.

If tblA is a timetable and tblB is a table, then you can specify the key variables as any variables that tblA and tblB both have, but you cannot specify the row times of tblA.

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.

If both tblA and tblB are timetables, then the value of 'LeftKeys' must specify the row times of tblA.

If tblA is a timetable and tblB is a table, then the value of 'LeftKeys' can specify variables of tblA, but not the row times of tblA.

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.

If both tblA and tblB are timetables, then the value of 'RightKeys' must specify the row times of tblB.

If tblA is a timetable and tblB is a table, then the value of 'RightKeys' can specify variables of tblB.

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.

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.

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. newStr has a size of 1 along the dimension being joined.

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 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 the output table. 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.

Tall Array Support

This function supports tall arrays with the limitations:

  • join can join together a tall table with a regular table. You cannot join two tall tables.

  • The two-output syntax [C,iB] = join(...) is not supported.

  • Unlike with tall tables, joining tall string arrays has no limitations.

For more information, see Tall Arrays.

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.

Introduced in R2013b

Was this topic helpful?