Main Content

readlines

Read lines of file as string array

    Description

    example

    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.

    Examples

    collapse all

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

    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"
    
    

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

    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

    Introduced in R2020b