readlines

Read lines of file as string array

Syntax

S = readlines(filename)

S = readlines(filename,Name,Value)

Description

S = readlines(filename) creates an N-by-1 string array by reading an N-line file.

S = readlines(filename,Name,Value) creates a string array from a file with additional options specified by one or more name-value pair arguments. For example, 'EmptyLineRule','skip' skips empty lines.

Examples

Create String Array from Text file

Create a 4-by-1 string array by reading each line from a text file as a separate string.

lines = readlines("badpoem.txt")

lines = 4x1 string
    "Oranges and lemons,"
    "Pineapples and tea."
    "Orangutans and monkeys,"
    "Dragonflys or fleas."

Ignore Empty Lines in Text File

View the contents of the file capital_cities.txt.

type 'capital_cities.txt'

  Boston, Massachusetts

Albany, New York

  Sacramento, California

Columbus, Ohio

  Santa Fe, New Mexico

Create a 5-by-1 string array by skipping the empty lines while reading capital_cities.txt. The array still contains the space characters from the input, but not the empty lines.

lines = readlines("capital_cities.txt","EmptyLineRule","skip")

lines = 5x1 string
    "  Boston, Massachusetts"
    "Albany, New York"
    "  Sacramento, California"
    "Columbus, Ohio"
    "  Santa Fe, New Mexico"

Remove Whitespace Surrounding Text

View the contents of the file capital_cities.txt.

type 'capital_cities.txt'

  Boston, Massachusetts

Albany, New York

  Sacramento, California

Columbus, Ohio

  Santa Fe, New Mexico

Specify the value of 'WhitespaceRule' as 'trimleading' to remove the whitespace before each line of text. The array no longer contains the leading space characters from the input, but still preserves the empty lines.

lines = readlines("capital_cities.txt","WhitespaceRule","trimleading")

lines = 10x1 string
    "Boston, Massachusetts"
    ""
    "Albany, New York"
    ""
    "Sacramento, California"
    ""
    "Columbus, Ohio"
    ""
    "Santa Fe, New Mexico"
    ""

Input Arguments

filename — Name of file to read

character vector | string scalar

Name of the file to read, specified as a character vector or a string scalar.

Depending on the location of your file, filename can take on one of these forms.

Location	Form
Current folder or folder on the MATLAB® path	Specify the name of the file in filename. Example: 'myFile.txt'
File in a folder	If the file is not in the current folder or in a folder on the MATLAB path, then specify the full or relative path in filename. Example: 'C:\myFolder\myFile.txt' Example: 'dataDir\myFile.txt'
Internet URL	If the file is specified as an internet uniform resource locator (URL), then filename must contain the protocol type 'http://' or 'https://'. Example: 'http://hostname/path_to_file/my_data.csv'
Remote Location	If the file is stored at a remote location, then filename must contain the full path of the file specified with the form: scheme_name://path_to_file/my_file.ext Based on the remote location, scheme_name can be one of the values in this table. Remote Location scheme_name Amazon S3™ s3 Windows Azure® Blob Storage wasb, wasbs HDFS™ hdfs For more information, see Work with Remote Data. Example: 's3://bucketname/path_to_file/my_file.csv'

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: 'EmptyLineRule','skip' specifies to omit empty lines while importing the file.

LineEnding — End-of-line characters

{'\n','\r','\r\n'} (default) | character vector | string scalar | cell array of character vectors | string array

End-of-line characters, specified as the comma-separated pair consisting of 'LineEnding' and a character vector or string. The character vector must be '\r\n' or it must specify a single character. Common end-of-line characters are a newline character ('\n') or a carriage return ('\r'). If you specify '\r\n', then the importing function treats any of \r, \n, and the combination of the two (\r\n) as end-of-line characters.

The default end-of-line sequence is \n, \r, or \r\n, depending on the contents of your file.

Example: 'LineEnding','\n'

Example: 'LineEnding','\r\n'

Data Types: char | string | cell

Whitespace — Characters to treat as whitespace

{' ','\b','\t'} | character vector | string scalar

Characters to treat as whitespace, specified as a character vector or string scalar containing one or more characters.

Example: 'Whitespace',' _'

Example: 'Whitespace','?!.,'

WhitespaceRule — Procedure to handle whitespace

'preserve' (default) | 'trim' | 'trimleading' | 'trimtrailing'

Procedure to handle whitespace surrounding a line in the data, specified as 'preserve', 'trim', 'trimleading', or 'trimtrailing'.

Whitespace Rule	Behavior
'preserve'	Preserve the leading and trailing whitespace.
'trim'	Remove the leading and trailing whitespace.
'trimleading'	Remove the leading whitespace only.
'trimtrailing'	Remove the trailing whitespace only.

Example: 'WhitespaceRule','trim'

Data Types: char | string

EmptyLineRule — Procedure to handle empty lines

'read' (default) | 'skip' | 'error'

Procedure to handle empty lines in the data, specified as 'skip', 'read', or 'error'.

Empty Line Rule	Behavior
'read'	Import the empty lines.
'skip'	Skip the empty lines.
'error'	Display an error message and abort the import operation.

Example: 'EmptyLineRule','skip'

Data Types: char | string

Encoding — Character encoding scheme

'' (default) | 'UTF-8' | 'system' | '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. 'Encoding','system' uses the system default encoding.

When you do not specify any encoding, the function uses automatic character set detection to determine the encoding when reading the file.

Data Types: char | string

WebOptions — HTTP or HTTPS request options

weboptions object

HTTP or HTTPS request options, specified as a weboptions object. The weboptions object determines how to import data when the specified filename is an internet URL containing the protocol type "http://" or "https://".

Version History

Introduced in R2020b