readSeparatedNumbers

This MATLAB function, readSeparatedNumbers.m, reads numeric data from a text file and parses it into an array. The function has better performance then alternatives like fscanf() or load().

This function was originally written to speed up the loading of files in the style of the provided example file(s). A speed comparison demonstration is available here.

Documentation

Syntax:

content = readSeparatedNumbers(filepath, sizeA, options)

Description: This function reads numeric data from a text file specified by filepath and parses it into a numerical array. The data in the file should be whitespace-separated or tab-separated. You can specify the expected size of the resulting numerical array using sizeA and the data type using the Name-Value pair typename.

Input Arguments:

• filepath (char/string): The path to the input text file.

• sizeA (numeric, optional): The dimensions of the expected numerical array. You can specify it as Inf (default), a positive integer, or a two-element row vector [m, n], where m represents the number of rows, and n represents the number of columns for the output array. When sizeA is set to Inf, the function reads the input data to the end, resulting in a column vector.

• Name-Value options:

  • typename (char): The data type for the output array. It should be one of the valid MATLAB data types (e.g., single, double, int8, uint16, etc.). The default is double.

Output:

• content (numeric array): The parsed numeric data from the text file in the specified data type and dimensions [m, n].

Example:

• To read a file data.txt containing tab-separated numbers and store them as a uint16 array with dimensions [2160, 2560]: content = readSeparatedNumbers('data.txt', [2160, 2560], typename = 'uint16');

• To read the entire file content into a double-precision column vector: content = readSeparatedNumbers('data.txt');

• To read only the first 100 numbers from the file and store them as int32: content = readSeparatedNumbers('data.txt', 100, typename = 'int32');