char, ' '

Character array

Description

A character array is a sequence of characters, just as a numeric array is a sequence of numbers. A typical use is to store a short piece of text as a row of characters in a character vector.

Creation

You can create a character vector using single quotation marks.

C = 'Hello, world'

C =

    'Hello, world'

If you have an array of a different data type, you can convert it to a character array using the char function, described below.

Syntax

C = 'text'

C = char(A)

C = char(A1,...,An)

C = char(D,datefmt)

C = char(D,datefmt,locale)

Description

Create Character Vector

C = 'text' creates a character vector of text enclosed in single quotes.

Convert Arrays

C = char(A) converts the input array, A, to a character array. For instance, if A is a string, "foo", c is a character array, 'foo'.

C = char(A1,...,An) converts the arrays A1,...,An into a single character array. After conversion to characters, the input arrays become rows in C. The char function pads rows with blank spaces as needed. If any input array is an empty character array, then the corresponding row in C is a row of blank spaces.

The input arrays A1,...,An cannot be string arrays, cell arrays, or categorical arrays.

A1,...,An can be of different sizes and shapes.

Convert Dates and Times

C = char(D,datefmt), where A is a datetime or duration array, applies the specified format, such as "HH:mm:ss".

C = char(D,datefmt,locale) specifies the locale, such as "en_US".

Input Arguments

A — Input array

array

Input array. The data type of A determines how char converts A to a character array.

Input Type	Conversion Notes	Sample Input	Sample Output
string	Each element of the input array becomes a row in the new character array, automatically padded with blank spaces as needed. If A is empty, "", the output is an empty character array, a 0-by-0 character vector.	1×1 string array "foo"	1×3 char array 'foo'
		2×1 string array "foo" "bar"	2×3 char array 'foo' 'bar'
Numeric array	char converts numbers into characters. Valid numeric values range from 0 to 65535 and correspond to Unicode® code units. Values from 0 to 127 also correspond to 7-bit ASCII characters. The char function: Rounds nonintegers toward zero. Treats values less than 0 as 0. Treats values greater than 65535 as 65535.	[102 111 111 33 ]	'foo!'
Cell array of character vectors	If the input is a cell array of character vectors or categorical array, then char converts the input to a character array. Each row from each element of the input array becomes a row in the new character array, automatically padded with blank spaces as needed.	{'foo','bar'}	2×3 char array 'foo' 'bar'
Categorical array		1x3 categorical array red green blue	3×5 char array 'red ' 'green' 'blue '

Converted missing values, such as NaN, NaT, and <undefined> categorical values, display as ' ', 'NaT', and '<undefined>', respectively.

D — Date or duration array

datetime array | duration array | calendarDuration array

Date or duration array, specified as a datetime, duration, or calendarDuration array. The data type of D determines how char converts D to character vectors.

Input Type	Conversion Notes	Sample Input	Sample Output
datetime array	Converts each element to a character vector. Each element of the input array becomes a row in the new character array, automatically padded with blank spaces as needed. To specify a format and locale, see datefmt.	datetime(2020,6,1)	'01-Jun-2020'
duration array	Converts each element to a character vector. Each element of the input array becomes a row in the new character array, automatically padded with blank spaces as needed. To specify a format and locale, see datefmt.	duration(5:6,12,21)	2×8 char array '05:12:21' '06:12:21'
calendarDuration array	Converts each element to a character vector. Each element of the input array becomes a row in the new character array, automatically padded with blank spaces as needed. To specify a format and locale, see datefmt.	calmonths(15) + caldays(8) + hours(1.2345)	'1y 3mo 8d 1h 14m 4.2s'

datefmt — Date Format and Locale

character vectors | string scalars

Date format and locale, specified as separate character vectors or string scalars. Input A must be of type datetime, duration, or calendarDuration.

If you do not specify a format, char uses the value in the Format property of A.

Example: char(A,"yyyy-MM-dd")

The supported formats depend on the data type of A.

• datetime formats can include combinations of units and delimiters, such as "yyyy-MMM-dd HH:mm:ss.SSS". For details, see the Format property for datetime arrays.

• duration formats are either single characters (y, d, h, m, or s) or one of these combinations:

  • "dd:hh:mm:ss"

  • "hh:mm:ss"

  • "mm:ss"

  • "hh:mm"

  • Any of the above, with up to nine S characters to indicate fractional second digits, such as "hh:mm:ss.SSSS"

• calendarDuration formats can include combinations of the characters y, q, m, w, d, and t in order from largest to smallest unit of time, such as "ym". For more information on the duration and calendarDuration formats, see Set Date and Time Display Format.

locale — Locale

character vector | string scalar

Locale, specified as one of these values:

• "system", to specify your system locale.

• A string scalar in the form xx_YY, where xx is a lowercase ISO 639-1 two-letter code that specifies a language, and YY is an uppercase ISO 3166-1 alpha-2 code that specifies a country. For sample values, see the Locale name-value argument for the datetime function.

To specify only the locale, use an empty array as a placeholder for the format, [].

Example: char(A,"yyyy-MM-dd","en_US")

Example: char(A,[],"en_US")

The locale affects the language used to represent certain components of dates and times, such as month names. Valid values are:

This table lists some common values for the locale.

Locale	Language	Country
"de_DE"	German	Germany
"en_GB"	English	United Kingdom
"en_US"	English	United States
"es_ES"	Spanish	Spain
"fr_FR"	French	France
"it_IT"	Italian	Italy
"ja_JP"	Japanese	Japan
"ko_KR"	Korean	Korea
"nl_NL"	Dutch	Netherlands
"zh_CN"	Chinese (simplified)	China

Output Arguments

C — Output array

character array

Output array, returned as a character array. Character arrays can have any size, but their most typical use is for storing pieces of text as character vectors.

MATLAB^® stores all characters as Unicode characters using the UTF-16 encoding. For more information on Unicode, see Unicode.

Examples

Create Character Vector

Create a character vector using single quotation marks.

C = 'Hello, world'

C = 
'Hello, world'

Convert Integers to Characters

Convert a numeric array to a character array.

A = [77 65 84 76 65 66];
C = char(A)

C = 
'MATLAB'

The integers from 32 to 127 correspond to printable ASCII characters. However, the integers from 0 to 65535 also correspond to Unicode® characters. You can convert integers to their corresponding Unicode representations using the char function.

For example, the number 8451 corresponds to the symbol for degrees Celsius. Convert 8451 using char.

C = char(8451)

C = 
'℃'

Convert Multiple Arrays to Character Array

Convert multiple arrays into a single character array. The input arrays need not have the same shape.

A1 = [65 66; 67 68];
A2 = 'abcd';
C = char(A1,A2)

C = 3x4 char array
    'AB  '
    'CD  '
    'abcd'

Because the input arrays do not have the same number of columns, char pads the rows from A1 with blanks.

whos C

  Name      Size            Bytes  Class    Attributes

  C         3x4                24  char               

Convert String to Character Vector

Create a string scalar. You can create string scalars using double quotes. MATLAB® also displays strings with double quotes.

A = "Pythagoras"

A = 
"Pythagoras"

Convert A to a character vector using the char function. MATLAB displays character vectors with single quotes.

C = char(A)

C = 
'Pythagoras'

Convert Duration Array to Character Array

Convert from a duration array to char. For more information related to converting from common data types to char see Convert Between Text and datetime or duration Values.

Create a duration array.

D = hours(23:25) + minutes(8) + seconds(1.2345)

D = 1x3 duration
   23.134 hr   24.134 hr   25.134 hr

Convert D to a character array.

C = char(D)

C = 3x9 char array
    '23.134 hr'
    '24.134 hr'
    '25.134 hr'

C is a character array that represents one duration value per row.

Specify the format of the duration values represented by C.

C = char(D,'hh:mm')

C = 3x5 char array
    '23:08'
    '24:08'
    '25:08'

Convert Localized Datetime to Character Array

Create a datetime.

D = datetime

D = datetime
   05-Sep-2024 15:21:16

Convert the datetime to a character vector that is formatted and localized to france.

C = char(D,'eeee, MMMM d, yyyy HH:mm:ss',"fr_FR")

C = 
'jeudi, septembre 5, 2024 15:21:16'

Tips

• Converting a char array to a numeric type will produce an array of the corresponding Unicode code values. Text in strings does not convert in this way. Converting a string that does not represent a single numeric value to double will produce a NaN result. For more information, see Unicode and ASCII Values.

Extended Capabilities

Tall Arrays

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

This function supports tall arrays with the limitations:

• For the syntax C = char(A), the input A must be a tall numeric column vector.

• Syntaxes with more than one input are not supported.

For more information, see Tall Arrays for Out-of-Memory Data.

C/C++ Code Generation

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

Usage notes and limitations:

• For the syntax C = char(A), the input A must be a string scalar, a numeric array, or a character array.

• Enumeration inputs must be scalar at compile time. Arrays of enumerations are not supported.

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.

Distributed Arrays

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

Usage notes and limitations:

• The multiple input syntax C = char(A1,...,An) is not supported.

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

Version History

Introduced before R2006a