horzcat

Concatenate arrays horizontally

Syntax

C = horzcat(A,B)

C = horzcat(A1,A2,…,An)

Description

C = horzcat(A,B) concatenates B horizontally to the end of A when A and B have compatible sizes (the lengths of the dimensions match except in the second dimension).

C = horzcat(A1,A2,…,An) concatenates A1, A2, … , An horizontally.

horzcat is equivalent to using square brackets to horizontally concatenate or append arrays. For example, [A,B] and [A B] is the same as horzcat(A,B) when A and B are compatible arrays.

Examples

Two Matrices

Concatenate two matrices horizontally.

Create two matrices, and horizontally append the second matrix to the first by using square bracket notation.

A = [1 2; 3 4]

A = 2×2

     1     2
     3     4

B = [4 5 6; 7 8 9]

B = 2×3

     4     5     6
     7     8     9

C = [A,B]

C = 2×5

     1     2     4     5     6
     3     4     7     8     9

Now, horizontally append the second matrix to the first by using horzcat.

D = horzcat(A,B)

D = 2×5

     1     2     4     5     6
     3     4     7     8     9

Two Tables

Create a table A with three rows and two variables.

A = table([5;6;5],['M';'M';'M'],...
    'VariableNames',{'Age' 'Gender'},...
    'RowNames',{'Thomas' 'Gordon' 'Percy'})

A=3×2 table
              Age    Gender
              ___    ______

    Thomas     5       M   
    Gordon     6       M   
    Percy      5       M   

Create a table B with three rows and three variables.

B = table([45;41;40],[45;32;34],{'NY';'CA';'MA'},...
    'VariableNames',{'Height' 'Weight' 'Birthplace'},...
    'RowNames',{'Percy' 'Gordon' 'Thomas'})

B=3×3 table
              Height    Weight    Birthplace
              ______    ______    __________

    Percy       45        45        {'NY'}  
    Gordon      41        32        {'CA'}  
    Thomas      40        34        {'MA'}  

Horizontally concatenate A and B. The order of rows in C matches the order in A.

C = horzcat(A,B)

C=3×5 table
              Age    Gender    Height    Weight    Birthplace
              ___    ______    ______    ______    __________

    Thomas     5       M         40        34        {'MA'}  
    Gordon     6       M         41        32        {'CA'}  
    Percy      5       M         45        45        {'NY'}  

Dates with Different Types

Concatenate a date character vector, a string date, and a datetime into a single row of dates. The result is a datetime row vector.

chardate = '2016-03-24';
strdate = "2016-04-19";
t = datetime('2016-05-10','InputFormat','yyyy-MM-dd');
C = horzcat(chardate,strdate,t)

C = 1x3 datetime
   24-Mar-2016   19-Apr-2016   10-May-2016

String Array

Concatenate three string arrays into a single array.

A1 = ["str1"; "str2"];
A2 = ["str3"; "str4"];
A3 = ["str5"; "str6"];
C = horzcat(A1,A2,A3)

C = 2x3 string
    "str1"    "str3"    "str5"
    "str2"    "str4"    "str6"

Matrices in a Cell Array

Create a cell array containing two matrices. Horizontally concatenate the matrices from the cell array into one matrix.

M1 = [1 2; 3 4];
M2 = [5 6 7; 8 9 10];
A1 = {M1,M2};
C = horzcat(A1{:})

C = 2×5

     1     2     5     6     7
     3     4     8     9    10

Input Arguments

A — First input

scalar | vector | matrix | multidimensional array | table | timetable

First input, specified as a scalar, vector, matrix, multidimensional array, table, or timetable.

B — Second input

scalar | vector | matrix | multidimensional array | table | timetable

Second input, specified as a scalar, vector, matrix, multidimensional array, table, or timetable.

• The elements of B are concatenated to the end of the first input along the second dimension. The sizes of the input arguments must be compatible. For example, if the first input is a matrix of size 3-by-2, then B must have 3 rows.

• All table inputs must have unique variable names. If row names are present in the table inputs, they must be the same, but they can be in a different order. horzcat concatenates by matching row names when present, or by matching table positions if row names are not present. For table inputs, horzcat also concatenates property values that are related to the table variables. Other property values of the output table are assigned using the first nonempty (or nondefault) property values of the corresponding inputs.

• All timetable inputs must have unique variable names. Row times in each timetable input must be the same, but they can be in a different order. horzcat concatenates by matching row times. For timetable inputs, horzcat also concatenates property values that are related to the timetable variables and events that are attached to the inputs. Other property values of the output timetable are assigned using the first nonempty (or nondefault) property values of the corresponding inputs.

• You can concatenate valid combinations of different types. For more information about concatenating character arrays, logical arrays, and numeric types, see Valid Combinations of Unlike Classes.

A1,A2,…,An — List of inputs

comma-separated list

List of inputs, specified as a comma-separated list of elements to concatenate in the order they are specified.

• The inputs must have compatible sizes. For example, if A1 is a column vector of length m, then the remaining inputs must each have m rows to concatenate horizontally.

• All table inputs must have unique variable names. If row names are present in the table inputs, they must be the same, but they can be in a different order. horzcat concatenates by matching row names when present, or by matching table positions if row names are not present. For table inputs, horzcat also concatenates property values that are related to the table variables. Other property values of the output table are assigned using the first nonempty (or nondefault) property values of the corresponding inputs.

• All timetable inputs must have unique variable names. Row times in each timetable input must be the same, but they can be in a different order. horzcat concatenates by matching row times. For timetable inputs, horzcat also concatenates property values that are related to the timetable variables and events that are attached to the inputs. Other property values of the output timetable are assigned using the first nonempty (or nondefault) property values of the corresponding inputs.

• You can concatenate valid combinations of different types. For more information about concatenating character arrays, logical arrays, and numeric types, see Valid Combinations of Unlike Classes.

Tips

• To construct text by horizontally concatenating strings, character vectors, or cell arrays of character vectors, use the strcat function.

• To construct a single piece of delimited text from a cell array of character vectors or a string array, use the strjoin function.

Algorithms

When concatenating an empty array to a nonempty array, horzcat omits the empty array in the output. For example, horzcat([1 2],[]) returns the row vector [1 2].

If all input arguments are empty and have compatible sizes, then horzcat returns an empty array whose size is equal to the output size as when the inputs are nonempty. For example, horzcat(zeros(0,1),zeros(0,2)) returns a 0-by-3 empty array. If the input sizes are not compatible, then horzcat returns a 0-by-0 empty array.

Extended Capabilities

Tall Arrays

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

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

• Concatenation of ordinal categorical arrays is not supported.

For more information, see Tall Arrays.

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

Thread-Based Environment

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

This function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.

GPU Arrays

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

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

• Sparse matrices 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™.

This function fully supports distributed arrays. For more information, see Run MATLAB Functions with Distributed Arrays (Parallel Computing Toolbox).

Version History

Introduced before R2006a