MathPad provides read and write functions for saving results and for importing or exporting data.
The function write("filename",array) writes the elements of the 1D or 2D array to the named file. An entire array is written by a single write rather than making multiple calls to write individual elements. The file is written to the folder of the source document unless a pathname is specified.
A write from an array created by an assignment is typically faster than from a defined array but any finite array can be written out.
The function read("filename") returns an array of values read from the named data file. The data file is assumed to be in the same folder as the source document. Mac style pathnames such as "Hard Disk:DataFolder:file47" are allowed. Aliases for data files are resolved. Aliased folders within the pathname, however, are not allowed.
The entire array is read in the first time any element is needed. MathPad can handle very large arrays but you can keep the total memory usage lower by avoiding multiple copies of the array.
Do not use the := assignment with read unless it is really needed.
  d := read("hugedata")
A large buffer gets allocated for the read(), another large buffer is allocated for "d" and the data gets copied into "d". If you use = instead, the total usage is much less.
  d = read("hugedata") -- definition. no allocation yet
  d[200]:42 -- first access. read buffer is allocated
  d2 = d*2 -- no extra memory needed for d2
  d2[200]:84
  d3 := d*3 -- a large buffer is needed for d3
Memory and processing requirements can also be drastically reduced by using optional parameters to extract only a portion of the data.
There are several data file formats supported. The default is text with tab separated values. This format is useable by many programs for exchanging numeric data.
For large data files it may be better to read and write a more compact binary form. MathPad supports several different binary formats. The numbers are stored in the file's data fork. There is no header or other special formatting. Matrix column information is stored in the resource fork.
The Preferences... dialog allows you to select which format will be used by write. The format can also be specified directly as an optional third parameter to to the write function.
Data files written by MathPad in any of its formats can automatically be handled properly by read. It learns the data format from the file's type.
type | bytes/value | description |
---|---|---|
TEXT | 2 to 13 | float |
FLT4 | 4 | 32-bit float |
FLT8 | 8 | 64-bit double |
INT4 | 4 | 32-bit integer |
INT2 | 2 | 16-bit integer |
BYT1 | 1 | 8-bit unsigned |
TEXT data files can be written or read by many applications. MathPad's read function is very flexible about how the numbers are formatted and delimited. Commas, tabs, spaces, letters or anything except -.? or digits can be used to delimit numbers.
MathPad does assign some meaning to line formatting. The number of values in the first line is taken as the number of columns in the matrix. If the file consists of a single row or a single column of numbers it is treated as a one dimensional array rather than a matrix. If the file starts with a return (empty first line) then it is treated as a one dimensional array regardless of how the rest of the lines are formatted.
The write function uses a single tab to delimit each number. Matrix values are output as one row per line. This format is compatible with many spreadsheet programs. Numbers are written with 7 digit precision regardless of the current numeric format. A '?' is used to represent missing data.
The write function will write out strings for the special case of a 2D array of strings and a TEXT file. Each string is written out with no quotes or separators. A line in the output file corresponds to a row in the 2D array.
TEXT data files are not distinguished from MathPad source files. They can be edited directly as text by MathPad. The changes must be saved before they will be seen by read.
This is a compact and general purpose binary format. It stores 4 bytes/element. It is probably the best choice for most cases. It has good dynamic range and precision. It is an IEEE standard and can be read by some other applications.
This is a double precision format. It stores 8 bytes/element so it is not as compact as 'FLT4' but is available if the extra precision is needed. This is the native double precision format for the PowerPC processor.
This format provides very compact representation. It is however limited to integers in the range -32767 to +32767. The value -32768 is used to represent missing data. This format stores 2 bytes/element.
This format uses 4 bytes/element . It is limited to integers but has more range than 'INT2'.
This format is extremely compact but is limited to integers in the range 0 to 255. The limited range makes it impractical for most data but since it allows directly writing bytes, it may be useful as a brute force way to create any desired binary file.
Other special floating point codes such as Inf
and -Inf
are only preserved with the floating point formats FLT4 and FLT8.
The read function has several optional parameters to help with importing data files created by other programs.
  read(filename,fmt,cols,len,skip,intvl)
Only the file name is required. Any or all of the other parameters can be omitted. A parameter can be defaulted by using a ? at its place in the list or by omitting it from the end of the list.
fmt -- When importing data, the data file's type may not be set correctly. This is especially true of binary data since there are no standard macintosh file types defined for binary files. The read function allows an optional format specification that will override the file's type.
  read("efile","INT2") -- force "efile" to be read as 16-bit
cols -- Binary data files created by other applications will not have MathPad's dimension resource. In this case the file is treated as a 1D array. An optional third parameter to can be used to provide or override column information.
  read("efile","INT2",4) -- force "efile" to be a 4 column matrix
  read("efile",?,4) -- use the file's type but force 4 columns
  read("efile","TEXT",0) -- ignore the columns in the file and force 1D
len -- MathPad normally reads the entire file into memory. This parameter can be used to read only the first len values from the file. This can be useful for accessing part of a very large file.
skip -- Sometimes files from other programs have header information before the actual data. This parameter can be used to skip any number of bytes before reading the first value.
intvl -- Only values at this interval are read in. For example if intvl is 10, every 10th value is read in and the others are ignored. BYT1, INT2 and INT4 formats support the intvl parameter.
This parameter can be combined with skip to allow efficient extraction of a single column from a multi column data file. The skip parameter is specified in bytes so the proper value depends on the data element size of the format. The general formula for the byte offset is:
skip = header+datasize*(col-1)
Where header is any header size in bytes and datasize is the bytes/element for the format being used.
  -- read the 4th col from a 10 col matrix
  weight = read("efile","INT2",0,?,2*(4-1),10)
  -- read the 5th col from a 10 col matrix
  cost = read("efile","INT2",0,?,2*(5-1),10)
Each read supports a single data file for each evaluation of the document. The entire array is read in the first time any element is accessed. Changing the parameters after the file is read in will have no effect. Separate read calls are used to create different arrays from the same file.
The use of the intvl parameter is simply for efficiency especially in cases where only a subset of the data in the file is of interest. A more general technique is to read the entire file and make separate array definitions for each column.
  d = read("efile","INT2",10) -- read in a 10 col matrix
  weight[i] = d[i,4] dim[count(d)] -- 4th col
  cost[i] = d[i,5] dim[count(d)] -- 5th col