Main Content

readlines

Read lines of file as string array

Since R2020b

collapse all in page

    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.

    example

    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.

    example

    Examples

    collapse all

    Open Live Script

    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."
    Open Live Script

    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"
    Open Live Script

    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

    collapse all

    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 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.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.

    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

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

    Example: 'Whitespace',' _'

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

    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

    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

    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

    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

    See Also

    | | | |