writecell

Write cell array to file

Description

example

writecell(C) writes cell array C to a comma delimited text file. The file name is the workspace name of the cell array, appended with the extension .txt. If writecell cannot construct the file name from the input cell array name, then it writes to the file cell.txt.

Each column of each variable in C becomes a column in the output file. The writecell function overwrites any existing file.

example

writecell(C,filename) writes to a file with the name and extension specified by filename.

writecell determines the file format based on the specified extension. The extension must be one of the following:

  • .txt, .dat, or .csv for delimited text files

  • .xls, .xlsm, or .xlsx for Excel® spreadsheet files

  • .xlsb for Excel spreadsheet files supported on systems with Excel for Windows®

example

writecell(___,Name,Value) writes the cell array to a file with additional options specified by one or more Name,Value pair arguments and can include any of the input arguments in previous syntaxes.

Examples

collapse all

Create a cell array, write it to a comma-separated text file, and then write the cell array to another text file with a different delimiter character.

Create a simple cell array in the workspace.

C =  {1,2,3;
     'text',datetime('today'),hours(1)}
C = 2×3 cell array
    {[   1]}    {[          2]}    {[   3]}
    {'text'}    {[09-Jan-2019]}    {[1 hr]}

Write the cell array to a comma delimited text file and display the file contents. The writecell function outputs a text file named C.txt.

writecell(C)
type 'C.txt'
1,2,3
text,09-Jan-2019,1 hr

To write the same cell array to a text file with a different delimiter character, use the 'Delimiter' name-value pair.

writecell(C,'C_tab.txt','Delimiter','tab')
type 'C_tab.txt'
1	2	3
text	09-Jan-2019	1 hr

Create a cell array, write it to a spreadsheet file, and then read and display the contents of the file.

Create a cell array in the workspace.

C =  {1,2,3;
     'text',datetime('today'),hours(1)}
C = 2×3 cell array
    {[   1]}    {[          2]}    {[   3]}
    {'text'}    {[09-Jan-2019]}    {[1 hr]}

Write the cell array to a spreadsheet file.

writecell(C,'C.xls')

Read and display the matrix from C.xls.

readcell('C.xls')
ans = 2×3 cell array
    {[   1]}    {[          2]}    {[   3]}
    {'text'}    {[09-Jan-2019]}    {'1 hr'}

Create a cell array and write it to a specified sheet and range in a spreadsheet file.

Create a cell array in the workspace.

C =  {1,2,3;
     'text',datetime('today'),hours(1)}
C = 2×3 cell array
    {[   1]}    {[          2]}    {[   3]}
    {'text'}    {[09-Jan-2019]}    {[1 hr]}

Write the cell array to the file C.xls, in the second worksheet in the file, starting at the third row.

writecell(C,'C.xls','Sheet',2,'Range','A3:C5')

Read and display the cell array.

readcell('C.xls','Sheet',2,'Range','A3:C5')
ans = 2×3 cell array
    {[   1]}    {[          2]}    {[   3]}
    {'text'}    {[09-Jan-2019]}    {'1 hr'}

Input Arguments

collapse all

Input data, specified as a cell array.

File name, specified as a character vector or string scalar.

Depending on the location you are writing to, filename can take on one of these forms.

Location

Form

Current folder

To write to the current folder, specify the name of the file in filename.

Example: 'myTextFile.csv'

Other folders

To write to a folder different from the current folder, specify the full or relative path name in filename.

Example: 'C:\myFolder\myTextFile.csv'

Example: 'myFolder\myExcelFile.xlsx'

Remote Location

To write to a remote location, filename must contain the full path of the file specified as a uniform resource locator (URL) of the form:

scheme_name://path_to_file/my_file.ext

Based on your remote location, scheme_name can be one of the values in this table.

Remote Locationscheme_name
Amazon S3™s3
Windows Azure® Blob Storagewasb, wasbs
HDFS™hdfs

For more information, see Work with Remote Data.

Example: 's3://bucketname/path_to_file/my_file.xlsx'

  • If filename includes the file extension, then the writing function determines the file format from the extension. Otherwise, the writing function creates a comma separated text file and appends the extension .txt. Alternatively, you can specify filename without the file’s extension, and then include the 'FileType' name-value pair arguments to indicate the type of file.

  • If filename does not exist, then the writing function creates the file.

  • If filename is the name of an existing text file, then the writing function overwrites the file.

  • If filename is the name of an existing spreadsheet file, then the writing function writes the data to the specified location, but does not overwrite any values outside the range of the input data.

Data Types: char | string

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 quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: 'FileType',text indicates that the variable names should not be included as the first row of the output file.

Text and Spreadsheet Files

collapse all

Type of file, specified as the comma-separated pair consisting of 'FileType' and a character vector or string containing 'text' or 'spreadsheet'.

The 'FileType' name-value pair must be used with the filename input argument. You do not need to specify the 'FileType' name-value pair argument if the filename input argument includes a standard file extension. The following standard file extensions are recognized by the writing function:

  • .txt, .dat, or .csv for delimited text files

  • .xls, .xlsm, or .xlsx for Excel spreadsheet files

  • .xlsb for Excel spreadsheet files supported on systems with Excel for Windows

Example: 'FileType','spreadsheet'

Data Types: char | string

Locale for writing dates, specified as the comma-separated pair consisting of 'DateLocale' and a character vector or a string scalar. When writing datetime values to the file, use DateLocale to specify the locale in which writetable should write month and day-of-week names and abbreviations. The character vector or string takes the form xx_YY, where xx is a lowercase ISO 639-1 two-letter code indicating a language, and YY is an uppercase ISO 3166-1 alpha-2 code indicating a country. For a list of common values for the locale, see the Locale name-value pair argument for the datetime function.

The writing function ignores the 'DateLocale' parameter value whenever dates can be written as Excel-formatted dates.

Example: 'DateLocale','ja_JP'

Data Types: char | string

Text Files Only

collapse all

Field delimiter character, specified as the comma-separated pair consisting of 'Delimiter' and a character vector or string scalar containing one of the following specifiers.

Specifier

Field Delimiter

','

'comma'

Comma. This is the default behavior.

' '

'space'

Space

'\t'

'tab'

Tab

';'

'semi'

Semicolon

'|'

'bar'

Vertical bar

You can use the 'Delimiter' name-value pair only for delimited text files.

Example: 'Delimiter','space'

Data Types: char | string

Indicator for writing quoted text, specified as the comma-separated pair consisting of 'QuoteStrings' and either false or true. If 'QuoteStrings' is true, then the writing function encloses the text in double quotation marks, and replaces any double-quote characters that appear as part of that text with two double-quote characters.

You can use the 'QuoteStrings' name-value pair only with delimited text files.

Character encoding scheme associated with the file, specified as the comma-separated pair consisting of 'Encoding' and 'system' or a standard character encoding scheme name like one of the values in this table. When you do not specify any encoding or specify encoding as 'system', the writing function uses your system default encoding to write the file.

'Big5'

'ISO-8859-1'

'windows-874'

'Big5-HKSCS'

'ISO-8859-2'

'windows-949'

'CP949'

'ISO-8859-3'

'windows-1250'

'EUC-KR'

'ISO-8859-4'

'windows-1251'

'EUC-JP'

'ISO-8859-5'

'windows-1252'

'EUC-TW'

'ISO-8859-6'

'windows-1253'

'GB18030'

'ISO-8859-7'

'windows-1254'

'GB2312'

'ISO-8859-8'

'windows-1255'

'GBK'

'ISO-8859-9'

'windows-1256'

'IBM866'

'ISO-8859-11'

'windows-1257'

'KOI8-R'

'ISO-8859-13'

'windows-1258'

'KOI8-U'

'ISO-8859-15'

'US-ASCII'

 

'Macintosh'

'UTF-8'

 

'Shift_JIS'

 

Example: 'system' uses the system default encoding.

Data Types: char | string

Spreadsheet Files Only

collapse all

Worksheet to write to, specified as the comma-separated pair consisting of 'Sheet' and a character vector or a string scalar containing the worksheet name or a positive integer indicating the worksheet index. The worksheet name cannot contain a colon (:). To determine the names of sheets in a spreadsheet file, use sheets = sheetnames(filename). For more information, see sheetnames.

Specify the worksheet to write to by name or index:

  • name — If the specified sheet name does not exist in the file, then the writing function adds a new sheet at the end of the worksheet collection.

  • index — If the specified sheet index is an index larger than the number of worksheets, then the writing function appends empty sheets until the number of worksheets in the workbook equals the sheet index. The writing function also generates a warning indicating that it has added a new worksheet.

You can use the 'Sheet' name-value pair only with spreadsheet files.

Example: 'Sheet',2

Example: 'Sheet', 'MySheetName'

Data Types: char | string | single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Rectangular portion of worksheet to write to, specified as the comma-separated pair consisting of 'Range' and a character vector or string scalar in one of the following forms.

Form of the Value of Range Description
'Corner1'

Corner1 specifies the first cell of the region to write. The writing function writes the data starting at this cell.

Example: 'Range','D2'

'Corner1:Corner2'

Corner1 and Corner2 are two opposing corners that define the region to write. For example, 'D2:H4' represents the 3-by-5 rectangular region between the two corners D2 and H4 on the worksheet. The 'Range' name-value pair argument is not case sensitive, and uses Excel A1 reference style (see Excel help).

Example: 'Range','D2:H4'

  • If the range you specify is smaller than the size of the input data, then the writing function writes only a subset of the input data that fits into the range.

  • If the range you specify is larger than the size of the input data, then the writing function leaves the remainder of the region as it is.

The 'Range' name-value pair can only be used with Excel files.

Example: 'Range', 'A1:F10'

Data Types: char | string

Flag to start an instance of Microsoft® Excel for Windows when writing spreadsheet data, specified as the comma-separated pair consisting of 'UseExcel' and either true, or false.

You can set the 'UseExcel' parameter to one of these values:

  • true — The writing function starts an instance of Microsoft Excel when writing the file.

  • false — The writing function does not start an instance of Microsoft Excel when writing the file. When operating in this mode, functionality for writing differs in the support of file formats and interactive features, such as formulas and macros.

UseExcel

true

false

Supported file formats

.xls, .xlsx, .xlsm, .xltx, .xltm, .xlsb, .ods

.xls, .xlsx, .xlsm, .xltx, .xltm

Support for interactive features, such as formulas and macros

Yes

No

When writing to spreadsheet files on Windows platforms, if you want to start an instance of Microsoft Excel, then set the 'UseExcel' parameter to true.

Algorithms

There are some instances where the writecell function creates a file that does not represent the input data exactly. You will notice this when you use the readcell function to read that file. The resulting data might not have the exact same format or contents as the original data. If you need to save your cell array and retrieve it at a later time to exactly match the original cell array, with the same data and organization, then save it as a MAT-file. writecell writes an inexact table in the following instances:

  • writecell writes out numeric data using long g format, and categorical or character data as unquoted text.

  • writecell writes out cell arrays that have more than two dimensions as two dimensional arrays, with the trailing dimensions collapsed.

Introduced in R2019a