Last modified: 2012-12-5
Class File
The File object provides a means of reading and writing files from Javasccript. See also Folder.
File in Cycling '74 Reference
Constructor Attributes | Constructor Name and Description |
---|---|
File(filename, access, typelist)
filename can be a file in the Max search path, an absolute path, or a relative path.
|
Field Attributes | Field Name and Description |
---|---|
String get/set |
File access permissions: "read", "write", or "readwrite".
|
String get/set |
The assumed file byteorder (endianness): "big", "little", or "native".
|
Number get/set |
The location of the end of file, in bytes.
|
String get/set |
The current filename.
|
String get/set |
The four-character code associated.
|
String get |
The absolute path to parent folder.
|
Boolean get |
Is file open? A useful test to determine if the File constructor was successful in finding and opening the file.
|
String get/set |
The line break convention to use when writing lines: "dos", "mac", "unix", or "native".
|
Number get/set |
The current file position, in bytes.
|
Array get/set |
An array file type codes to filter by when opening a file.
|
Method Attributes | Method Name and Description |
---|---|
void |
close()
Closes the currently open file.
|
void |
open(filename)
Opens the file specified by the filename argument.
|
Byte Array |
readbytes(byte_count)
Reads and returns an array containing up to byte_count numbers,
read as bytes from the file, starting at the current file position.
|
Char Array |
readchars(char_count)
Reads and returns an array containing the single character strings,
read as characters from the file, starting at the current file position.
|
Float32 Array |
readfloat32(float32_count)
Reads and returns an array containing the numbers read as 32-bit floating point numbers from the file starting
at the current file position.
|
Float64 Array |
readfloat64(float64_count)
Reads and returns an array containing the numbers read as 64-bit floating point numbers from the file
starting at the current file position.
|
Int16 Array |
readint16(int16_count)
Reads and returns an array containing the numbers read as signed 16-bit integers from the file
starting at the current file position.
|
Int32 Array |
readint32(int32_count)
Reads and returns an array containing the numbers read as signed 32-bit integers from the file
starting at the current file position.
|
String |
readline(maximum_count)
Reads and returns a string containing up to maximum_count characters or up to the
first line break as read from the file, starting at the current file position.
|
String |
readstring(char_count)
Reads and returns a string containing up to char_count characters as read from the file,
starting at the current file position.
|
void |
writebytes(byte_array)
Writes the numbers contained in the byte_array argument as bytes to the file,
starting at the current file position.
|
void |
writechars(char_array)
Writes the single character strings contained in the char_array argument as characters to the file,
starting at the current file position.
|
void |
writefloat32(float32_array)
Writes the numbers contained in the float32_array argument as 32-bit floating point numbers to the file,
starting at the current file position.
|
void |
writefloat64(float64_array)
Writes the numbers contained in the float64_array argument as 64-bit floating point numbers to the file,
starting at the current file position.
|
void |
writeint16(int16_array)
Writes the numbers contained in the int16_array argument as signed 16-bit integers to the file,
starting at the current file position.
|
void |
writeint32(int32_array)
Writes the numbers contained in the int32_array argument as signed 32-bit integers to the file,
starting at the current file position.
|
void |
writeline(line)
Writes the characters contained in the string argument as characters to the file,
starting at the current file position, and inserts a line break appropriate to the
linebreak property.
|
void |
writestring(content)
Writes the characters contained in the string argument as characters to the file,
starting at the current file position.
|
Class Detail
File
(filename, access, typelist)
filename can be a file in the Max search path, an absolute path, or a relative path.
Acceptable values for access can be "read", "write", or "readwrite". The default value for
access is "read". Acceptable values for typelist are four character filetype codes listed
in the file max-fileformats.txt, which is located at /Library/Application Support/Cycling ’74
on Macintosh and C:\Program Files\Common Files\Cycling ’74 on Windows. By default, typelist
is empty. If able to, the File constructor opens the file specified by filename, provided it
is one of the types in typelist.
- Example:
filename = "/path/to/file.txt"; access = "readwrite"; typelist = new Array("iLaF" , "maxb" , "TEXT" ); f = new File(filename, access, typelist);
- Parameters:
- {String} filename
- filename can be a file in the Max search path, an absolute path, or a relative path.
- {String} access
- "read", "write" or "readwrite"
- {String} typelist
- Acceptable values for typelist are four character filetype codes listed in the file max-fileformats.txt, which is located at /Library/Application Support/Cycling ’74 on Macintosh and C:\Program Files\Common Files\Cycling ’74 on Windows. By default, typelist is empty.
Field Detail
{String get/set}
access
File access permissions: "read", "write", or "readwrite". By default, this value is "read".
- Example:
filename = "/path/to/file.txt"; access = "readwrite"; typelist = new Array("iLaF" , "maxb" , "TEXT" ); f = new File(filename, access, typelist);
- Default Value:
- "read"
{String get/set}
byteorder
The assumed file byteorder (endianness): "big", "little", or "native". By default, this value is "native".
- Example:
filename = "/path/to/file.txt"; access = "readwrite"; typelist = new Array("iLaF" , "maxb" , "TEXT" ); f = new File(filename, access, typelist); f.byteorder = "big";
- Default Value:
- "native"
{Number get/set}
eof
The location of the end of file, in bytes.
- Example:
filename = "/path/to/file.txt"; access = "readwrite"; typelist = new Array("iLaF" , "maxb" , "TEXT" ); f = new File(filename, access, typelist); var content = ""; while(f.isopen && f.position < f.eof){ post(f.readline() + "\n"); } f.close();
{String get/set}
filename
The current filename.
- Example:
filename = "/path/to/file.txt"; access = "readwrite"; typelist = new Array("iLaF" , "maxb" , "TEXT" ); f = new File(filename, access, typelist); post(f.filename);
{String get/set}
filetype
The four-character code associated. See c74:/init/max-fileformats.txt for possible values.
- Example:
filename = "/path/to/file.txt"; access = "readwrite"; typelist = new Array("iLaF" , "maxb" , "TEXT" ); f = new File(filename, access, typelist); post(f.filetype);
{String get}
foldername
The absolute path to parent folder.
- Example:
filename = "/path/to/file.txt"; access = "readwrite"; typelist = new Array("iLaF" , "maxb" , "TEXT" ); f = new File(filename, access, typelist); post(f.flodername);
{Boolean get}
isopen
Is file open? A useful test to determine if the File constructor was successful in finding and opening the file.
- Example:
filename = "/path/to/file.txt"; access = "readwrite"; typelist = new Array("iLaF" , "maxb" , "TEXT" ); f = new File(filename, access, typelist); post(f.isopen);
{String get/set}
linebreak
The line break convention to use when writing lines: "dos", "mac", "unix", or "native". By default, this value is "native".
- Example:
filename = "/path/to/file.txt"; access = "readwrite"; typelist = new Array("iLaF" , "maxb" , "TEXT" ); f = new File(filename, access, typelist); post(f.linebreak);
- Default Value:
- "native"
{Number get/set}
position
The current file position, in bytes.
- Example:
filename = "/path/to/file.txt"; access = "readwrite"; typelist = new Array("iLaF" , "maxb" , "TEXT" ); f = new File(filename, access, typelist); while(f.isopen && f.position < f.eof){ post(f.readline() + "\n"); post(f.position + "\n"); } f.close();
{Array get/set}
typelist
An array file type codes to filter by when opening a file. By default, this is the empty array.
- Example:
filename = "/path/to/file.txt"; access = "readwrite"; typelist = new Array("iLaF" , "maxb" , "TEXT" ); f = new File(filename, access, typelist); f.typelist = new Array("maxb" , "TEXT" ); post(f.typelist);
Method Detail
{void}
close
()
Closes the currently open file.
- Example:
function bang(){ filename = "/path/to/file.txt"; access = "readwrite"; f = new File(filename, access, typelist); f.close(); f.open("/path/to/file2.txt"); while(f.isopen && f.position < f.eof ){ post(f.readline() + "\n"); } f.close(); }
{void}
open
(filename)
Opens the file specified by the filename argument. If no argument is specified, it will open the last opened file.
- Example:
function bang(){ filename = "/path/to/file.txt"; access = "readwrite"; f = new File(filename, access, typelist); f.close(); f.open("FileTest2.txt"); while(f.isopen && f.position < f.eof ){ post(f.readline() + "\n"); } f.close(); }
- Parameters:
- {String} filename
{Byte Array}
readbytes
(byte_count)
Reads and returns an array containing up to byte_count numbers,
read as bytes from the file, starting at the current file position.
The file position is updated accordingly.
- Example:
function bang(){ filename = "/path/to/file.txt"; access = "readwrite"; typelist = new Array("iLaF" , "maxb" , "TEXT" ); f = new File(filename, access, typelist); while(f.isopen && f.position < f.eof ){ post(f.readbytes(10) + "\n"); } f.close(); }
- Parameters:
- {Number} byte_count
{Char Array}
readchars
(char_count)
Reads and returns an array containing the single character strings,
read as characters from the file, starting at the current file position.
The file position is updated accordingly.
- Example:
function bang(){ filename = "/path/to/file.txt"; access = "readwrite"; typelist = new Array("iLaF" , "maxb" , "TEXT" ); f = new File(filename, access, typelist); while(f.isopen && f.position < f.eof ){ post(f.readchars(10) + "\n"); } f.close(); }
- Parameters:
- {Number} char_count
{Float32 Array}
readfloat32
(float32_count)
Reads and returns an array containing the numbers read as 32-bit floating point numbers from the file starting
at the current file position. The byteorder property is taken into account when reading these values.
The file position is updated accordingly.
- Example:
function bang(){ filename = "/path/to/file.txt"; access = "readwrite"; typelist = new Array("iLaF" , "maxb" , "TEXT" ); f = new File(filename, access, typelist); while(f.isopen && f.position < f.eof ){ post(f.readfloat32(10) + "\n"); } f.close(); }
- Parameters:
- {Number} float32_count
{Float64 Array}
readfloat64
(float64_count)
Reads and returns an array containing the numbers read as 64-bit floating point numbers from the file
starting at the current file position. The byteorder property is taken into account when reading these
values. The file position is updated accordingly.
- Example:
function bang(){ filename = "/path/to/file.txt"; access = "readwrite"; typelist = new Array("iLaF" , "maxb" , "TEXT" ); f = new File(filename, access, typelist); while(f.isopen && f.position < f.eof ){ post(f.readfloat64(10) + "\n"); } f.close(); }
- Parameters:
- {Number} float64_count
{Int16 Array}
readint16
(int16_count)
Reads and returns an array containing the numbers read as signed 16-bit integers from the file
starting at the current file position. The byteorder property is taken into account when reading
these values. The file position is updated accordingly.
- Example:
function bang(){ filename = "/path/to/file.txt"; access = "readwrite"; typelist = new Array("iLaF" , "maxb" , "TEXT" ); f = new File(filename, access, typelist); while(f.isopen && f.position < f.eof ){ post(f.readint16(10) + "\n"); } f.close(); }
- Parameters:
- {Number} int16_count
{Int32 Array}
readint32
(int32_count)
Reads and returns an array containing the numbers read as signed 32-bit integers from the file
starting at the current file position. The byteorder property is taken into account when reading
these values. The file position is updated accordingly.
- Example:
function bang(){ filename = "/path/to/file.txt"; access = "readwrite"; typelist = new Array("iLaF" , "maxb" , "TEXT" ); f = new File(filename, access, typelist); while(f.isopen && f.position < f.eof ){ post(f.readint32(10) + "\n"); } f.close(); }
- Parameters:
- {Number} int32_count
{String}
readline
(maximum_count)
Reads and returns a string containing up to maximum_count characters or up to the
first line break as read from the file, starting at the current file position.
The file position is updated accordingly.
- Example:
function bang(){ filename = "/path/to/file.txt"; access = "readwrite"; typelist = new Array("iLaF" , "maxb" , "TEXT" ); f = new File(filename, access, typelist); while(f.isopen && f.position < f.eof ){ post(f.readline() + "\n"); } f.close(); }
- Parameters:
- {Number} maximum_count
{String}
readstring
(char_count)
Reads and returns a string containing up to char_count characters as read from the file,
starting at the current file position. Unlike readline(), line breaks are not considered.
The file position is updated accordingly.
- Example:
function bang(){ filename = "/path/to/file.txt"; access = "readwrite"; typelist = new Array("iLaF" , "maxb" , "TEXT" ); f = new File(filename, access, typelist); while(f.isopen && f.position < f.eof ){ post(f.readstring(10) + "\n"); } f.close(); }
- Parameters:
- {Number} char_count
{void}
writebytes
(byte_array)
Writes the numbers contained in the byte_array argument as bytes to the file,
starting at the current file position. The file position is updated accordingly.
- Example:
function bang(){ filename = "/path/to/file.txt"; access = "readwrite"; typelist = new Array("iLaF" , "maxb" , "TEXT" ); f = new File(filename, access, typelist); var myvalues = [116,101,115,116,87,114,105,116,101,108]; f.position = f.eof; if(f.isopen){ f.writebytes(myvalues); } f.position = 0; while(f.isopen && f.position < f.eof ){ post(f.readbytes(10) + "\n"); } f.close(); }
- Parameters:
- {Array} byte_array
{void}
writechars
(char_array)
Writes the single character strings contained in the char_array argument as characters to the file,
starting at the current file position. The file position is updated accordingly.
- Example:
function bang(){ filename = "/path/to/file.txt"; access = "readwrite"; typelist = new Array("iLaF" , "maxb" , "TEXT" ); f = new File(filename, access, typelist); var myvalues = ['t','e','s','t']; f.position = f.eof; if(f.isopen){ f.writechars(myvalues); } f.position = 0; while(f.isopen && f.position < f.eof ){ post(f.readchars(10) + "\n"); } f.close(); }
- Parameters:
- {Array} char_array
{void}
writefloat32
(float32_array)
Writes the numbers contained in the float32_array argument as 32-bit floating point numbers to the file,
starting at the current file position. The byteorder property is taken into account when writing these values.
The file position is updated accordingly.
- Example:
function bang(){ filename = "/path/to/file.txt"; access = "readwrite"; typelist = new Array("iLaF" , "maxb" , "TEXT" ); f = new File(filename, access, typelist); var myvalues = [0.0, 1.0, 0.25, 0.5, 0.75]; f.position = f.eof; if(f.isopen){ f.writefloat32(myvalues); } f.position = 0; while(f.isopen && f.position < f.eof ){ post(f.readfloat32(10) + "\n"); } f.close(); }
- Parameters:
- {Float32 Array} float32_array
{void}
writefloat64
(float64_array)
Writes the numbers contained in the float64_array argument as 64-bit floating point numbers to the file,
starting at the current file position. The byteorder property is taken into account when writing these values.
The file position is updated accordingly.
- Example:
function bang(){ filename = "/path/to/file.txt"; access = "readwrite"; typelist = new Array("iLaF" , "maxb" , "TEXT" ); f = new File(filename, access, typelist); var myvalues = [0.0, 1.0, 0.25, 0.5, 0.75]; f.position = f.eof; if(f.isopen){ f.writefloat64(myvalues); } f.position = 0; while(f.isopen && f.position < f.eof ){ post(f.readfloat64(10) + "\n"); } f.close(); }
- Parameters:
- {Float64 Array} float64_array
{void}
writeint16
(int16_array)
Writes the numbers contained in the int16_array argument as signed 16-bit integers to the file,
starting at the current file position. The byteorder property is taken into account when writing
these values. The file position is updated accordingly.
- Example:
function bang(){ filename = "/path/to/file.txt"; access = "readwrite"; typelist = new Array("iLaF" , "maxb" , "TEXT" ); f = new File(filename, access, typelist); var myvalues = [116,101,115,116,87,114,105,116,101,108]; f.position = f.eof; if(f.isopen){ f.writeint16(myvalues); } f.position = 0; while(f.isopen && f.position < f.eof ){ post(f.readint16(10) + "\n"); } f.close(); }
- Parameters:
- {Int16 Array} int16_array
{void}
writeint32
(int32_array)
Writes the numbers contained in the int32_array argument as signed 32-bit integers to the file,
starting at the current file position. The byteorder property is taken into account when writing
these values. The file position is updated accordingly.
- Example:
function bang(){ filename = "/path/to/file.txt"; access = "readwrite"; typelist = new Array("iLaF" , "maxb" , "TEXT" ); f = new File(filename, access, typelist); var myvalues = [116,101,115,116,87,114,105,116,101,108]; f.position = f.eof; if(f.isopen){ f.writeint32(myvalues); } f.position = 0; while(f.isopen && f.position < f.eof ){ post(f.readint32(10) + "\n"); } f.close(); }
- Parameters:
- {Int32 Array} int32_array
{void}
writeline
(line)
Writes the characters contained in the string argument as characters to the file,
starting at the current file position, and inserts a line break appropriate to the
linebreak property. The file position is updated accordingly.
- Example:
function bang(){ filename = "/path/to/file.txt"; access = "readwrite"; typelist = new Array("iLaF" , "maxb" , "TEXT" ); f = new File(filename, access, typelist); if(f.isopen){ f.writeline("testWriteline() succeeded..."); } f.position = 0; while(f.isopen && f.position < f.eof ){ post(f.readline() + "\n"); } f.close(); }
- Parameters:
- {String} line
{void}
writestring
(content)
Writes the characters contained in the string argument as characters to the file,
starting at the current file position. Unlike writeline(), no line break is inserted.
The file position is updated accordingly.
- Example:
function bang(){ filename = "/path/to/file.txt"; access = "readwrite"; typelist = new Array("iLaF" , "maxb" , "TEXT" ); f = new File(filename, access, typelist); // append string at end of file f.position = f.eof; if(f.isopen){ f.writestring("testWritestring() succeeded..."); } f.position = 0; while(f.isopen && f.position < f.eof ){ post(f.readline() + "\n"); } f.close(); }
- Parameters:
- {String} content