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.xlsx' Example: 'dataDir\myFile.txt'
Remote Location	If the file is stored at a remote location, then filename must be a uniform resource locator (URL) of this 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 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 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: '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