writecell
Write cell array to file
Description
writecell(
writes cell array
C
)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.
writecell(
writes to a file with the name and extension specified by
C
,filename
)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®
writecell(___,
writes
the cell array to a file with additional options specified by one or more
Name,Value
)Name,Value
pair arguments and can include any of the input arguments
in previous syntaxes.
Examples
Write Cell Array to Text File
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
Write Cell Array to Spreadsheet File
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'}
Write Cell Array to Specified Sheet and Range
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'}
Append Cell Array Below Existing Data in Spreadsheet
Append a cell array to the bottom of a spreadsheet file containing existing data.
Create two cell arrays in the workspace.
C = {1,2,3; 'text',datetime('today'),hours(1)}
C=2×3 cell array
{[ 1]} {[ 2]} {[ 3]}
{'text'} {[20-Jul-2024]} {[1 hr]}
rgb = {'red','green','blue'}
rgb = 1x3 cell
{'red'} {'green'} {'blue'}
Write the cell array C
to a spreadsheet file called C.xls
.
writecell(C,'C.xls')
Append the cell array rgb
below the existing data in the spreadsheet file.
writecell(rgb,'C.xls','WriteMode','append')
Read and display the cell array.
readcell('C.xls')
ans=3×3 cell array
{[ 1]} {[ 2]} {[ 3]}
{'text'} {[20-Jul-2024]} {'1 hr'}
{'red' } {'green' } {'blue'}
Append Cell Array to Bottom of Text File
Append cell arrays to the bottom of a text file containing existing data.
Create three cell arrays in the workspace.
states = {"Massachusetts","New York","Maryland","Virginia"}
states=1×4 cell array
{["Massachusetts"]} {["New York"]} {["Maryland"]} {["Virginia"]}
stateBird = {"Black-capped chickadee","Eastern bluebird",... "Baltimore oriole","Cardinal"}
stateBird=1×4 cell array
{["Black-capped chickadee"]} {["Eastern bluebird"]} {["Baltimore oriole"]} {["Cardinal"]}
stateFlower = {"Trailing arbutus","Rose",... "Black-eyed Susan","Flowering dogwood"}
stateFlower=1×4 cell array
{["Trailing arbutus"]} {["Rose"]} {["Black-eyed Susan"]} {["Flowering dogwood"]}
Write the cell array states
to the file states.txt
. Then write the arrays stateBird
and stateFlower
below the existing entries in the text file.
writecell(states,'states.txt') writecell(stateBird,'states.txt','WriteMode','append') writecell(stateFlower,'states.txt','WriteMode','append')
Read and display the cell array.
readcell('states.txt')
ans = 3x4 cell
{'Massachusetts' } {'New York' } {'Maryland' } {'Virginia' }
{'Black-capped chickadee'} {'Eastern bluebird'} {'Baltimore oriole'} {'Cardinal' }
{'Trailing arbutus' } {'Rose' } {'Black-eyed Susan'} {'Flowering dogwood'}
Input Arguments
C
— Input cell array
cell array
Input data, specified as a cell array.
filename
— File name
character vector | string scalar
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 Example: | ||||||||
Other folders | To write to a folder different from the current folder, specify the full or relative path name in Example: Example: | ||||||||
Remote Location | To write to a remote location,
Based on the remote location,
For more information, see Work with Remote Data. Example:
|
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 specifyfilename
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 Arguments
Specify optional pairs of arguments as
Name1=Value1,...,NameN=ValueN
, where Name
is
the argument name and Value
is the corresponding value.
Name-value arguments must appear after other arguments, but the order of the
pairs does not matter.
Before R2021a, use commas to separate each name and value, and enclose
Name
in quotes.
Example: 'FileType',text
indicates that the variable names should not
be included as the first row of the output file.
FileType
— Type of file
'text'
| 'spreadsheet'
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
DateLocale
— Locale for writing dates
character vector | string scalar
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
writecell
should write month and day-of-week names and
abbreviations. The character vector or string takes the form
,
where xx
_YY
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
WriteMode
— Writing mode
character vector | string scalar
Writing mode, specified as the comma-separated pair consisting of 'WriteMode'
and a character vector or a string scalar. Select a write mode based on the file type.
File Type | Write Mode |
---|---|
Text Files |
If the file you specified does not exist, then the writing function creates and writes data to a new file. |
Spreadsheet Files |
|
When
WriteVariableNames
is set totrue
, the writing function does not support the write mode'append'
.For spreadsheet files:
When the write mode is
'append'
, the writing function does not support theRange
parameter.If the file you specified does not exist, then the writing function performs the same actions as
'replacefile'
.
Example: 'WriteMode','append'
Data Types: char
| string
Delimiter
— Field delimiter character
character vector | string scalar
Field delimiter character, specified as the comma-separated pair consisting of
'Delimiter'
and a character vector or string scalar containing
one of these specifiers:
Specifier | Field Delimiter |
---|---|
| Comma. This is the default behavior. |
| Space |
| Tab |
| Semicolon |
| Vertical bar |
You can use the 'Delimiter'
name-value pair only for delimited text files.
Example: 'Delimiter','space'
Data Types: char
| string
QuoteStrings
— Indicator for writing quoted text
"minimal"
(default) | "all"
| "none"
Indicator for writing quoted text, specified as "minimal"
,
"all"
, or "none"
.
If
QuoteStrings
is"minimal"
, then the function encloses any variables containing the delimiter, line ending, or double-quote character in double-quote characters.If
QuoteStrings
is"all"
, then the function encloses all text, categorical, datetime, and duration variables in double-quote characters.If
QuoteStrings
is"none"
, then the function does not enclose variables in double-quote characters.
You can use the QuoteStrings
name-value argument only with delimited text
files.
Encoding
— Character encoding scheme
'UTF-8'
(default) | 'ISO-8859-1'
| 'windows-1251'
| 'windows-1252'
| ...
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. When you
do not specify any encoding, the writing function uses UTF-8 to write the file.
Example: 'Encoding','UTF-8'
uses UTF-8 as the
encoding.
Data Types: char
| string
Sheet
— Worksheet to write to
character vector | string scalar | positive integer
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
Range
— Rectangular portion of worksheet to write to
character vector | string scalar
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 |
---|---|
' |
Example: |
' |
Example:
|
The 'Range'
name-value pair can only be used with Excel files.
Example: 'Range'
, 'A1:F10'
Data Types: char
| string
UseExcel
— Flag to start instance of Microsoft®
Excel for Windows
false
(default) | true
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 |
|
|
---|---|---|
Supported file formats |
|
|
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
.
UseExcel
is not supported in noninteractive, automated
environments.
AutoFitWidth
— Automatically adjust column width
true
(default) | false
Automatically adjust column width, specified as true
or
false
. If you specify a value of 0
or
false
, then writecell
will not
automatically adjust the column widths to fit the data in the cells.
Example: 'AutoFitWidth'
,0
PreserveFormat
— Preserve cell formatting
true
(default) | false
Preserve cell formatting of existing spreadsheet, specified as true
or false
. If you specify false
,
writecell
will not preserve the cell formatting of the
spreadsheet. Formatting includes elements such as fonts, cell borders, and color-shaded
cells.
When writing datetime
data to a spreadsheet file, you must set both
'PreserveFormat'
and the 'UseExcel'
Name-Value
pair to true
to preserve the existing cell formatting. If
'UseExcel'
is set to false
and
'PreserveFormat'
is set to true
when writing
datetime
data to the file, writecell
will
not preserve the existing cell formatting of the file.
Example: 'PreserveFormat'
,false
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 thereadcell
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 usinglong 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.
Excel converts
Inf
values to65535
. MATLAB® convertsNaN
,NaT
,<undefined>
categorical values, and<missing>
string values to empty cells.
Version History
Introduced in R2019a
See Also
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)