Difference between revisions of "ChucK/Dev/IO/FileIO"

From CSWiki
Jump to: navigation, search
 
(20 intermediate revisions by the same user not shown)
Line 2: Line 2:
  
 
==FileIO Class==
 
==FileIO Class==
The <tt>FileIO</tt> class is a subclass of the [[ChucK/Dev/IO#IO_Class|<tt>IO</tt>]] class.
+
The <tt>FileIO</tt> class is a subclass of the [[ChucK/Dev/IO#IO_Class|<tt>IO</tt>]] class. Only elements of the <tt>FileIO</tt> class that extend or override the parent class are listed here. Only files of up to 2 GiB in size are supported by this class.
 +
 
 
===Methods===
 
===Methods===
===Events===
+
; <code>fun int open(string path[, int flags])</code> : Opens the specified file, returning true on success and false otherwise. The flags can optionally be used to specify the mode in which to open the file (<code>FileIO.MODE_READ_WRITE | FileIO.MODE_ASCII</code> by default).
 +
; <code>fun void seek(int pos)</code> : Seeks to the specified byte offset from the start of the file.
 +
; <code>fun int tell()</code> : Returns the current position in the file in bytes, or -1 if a file is not open.
 +
; <code>fun int size()</code> : Returns the size of the file in bytes, or -1 if a file is not open.
 +
 
 +
====Directories====
 +
; <code>fun int isDir()</code> : Returns true if the opened file is a directory, false otherwise.
 +
; <code>fun string[] dirList()</code> : Returns an array containing the names of each file in the opened directory, or an empty array if the opened file is not a directory.
 +
 
 
===Constants===
 
===Constants===
; <code>FileIO.stdin</code><br /><code>FileIO.stdout</code> : Pre-created files for reading from and writing to <tt>stdin</tt> and <tt>stdout</tt>.
+
; <code>FileIO.FLAG_READ_WRITE</code><br /><code>FileIO.FLAG_READONLY</code><br /><code>FileIO.FLAG_WRITEONLY</code><br /><code>FileIO.FLAG_APPEND</code> : These flags can optionally be passed to the <code>open</code> function to specify the mode in which to open the file.
 +
; <code>FileIO.TYPE_ASCII</code><br /><code>FileIO.TYPE_BINARY</code> : These flags can optionally be passed to the <code>open</code> function to specify whether reading and writing should proceed in ASCII (readable text) or binary mode.
 +
 
 +
===Examples===
 +
1. Functions to read and write an array of integers in binary mode.
 +
<code><pre>
 +
fun void writeInts(int integers[], string path) {
 +
 
 +
    // open the file
 +
    FileIO file;
 +
    if (!file.open(path, FileIO.MODE_WRITEONLY | FileIO.MODE_BINARY))
 +
        return; // error opening the specified file
 +
   
 +
    // write out the size and contents of the array
 +
    file <~ integers.size();
 +
    for (0 => int i; i < integers.size(); i++)
 +
        file <~ integers[i];
 +
       
 +
    // and we're done
 +
    file.close(); // automatically calls file.finish()
 +
 
 +
}
 +
 
 +
fun int[] readInts(string path) {
 +
   
 +
    // open the file
 +
    FileIO file;
 +
    if (!file.open(path, FileIO.MODE_READONLY | FileIO.MODE_BINARY)) {
 +
        int ret[0]; // error opening the specified file
 +
        return ret;
 +
    }
 +
   
 +
    // read the size of the array
 +
    file ~> int size;
 +
    file.finish(); // wait for the read to finish without advancing time
 +
                  // before continuing
 +
   
 +
    // now read in the contents
 +
    int ret[size];
 +
    for (0 => int i; i < size; i++)
 +
        file ~> ret[i];
 +
       
 +
    // and we're done
 +
    file.close(); // automatically calls file.finish()
 +
    return ret;
 +
   
 +
}
 +
</pre></code>
 +
2. Function to append a string to the end of a log file (uses <tt>seek</tt> and <tt>size</tt>).
 +
<code><pre>
 +
fun void logAppend(FileIO log, string entry) {
 +
 
 +
    // file already given to us...make sure it is open
 +
    if (log.isClosed())
 +
        return;
 +
       
 +
    log.size() => log.seek; // move to end of file
 +
    log <~ entry <~ "\n"; // write the entry, terminate with newline
 +
   
 +
    // don't close the file or wait for the queued I/O to
 +
    // finish--that's up to the calling function
 +
 
 +
}
 +
</pre></code>
 +
3. TODO: Using directories

Latest revision as of 20:02, 21 April 2008

The following is subject to change.

FileIO Class

The FileIO class is a subclass of the IO class. Only elements of the FileIO class that extend or override the parent class are listed here. Only files of up to 2 GiB in size are supported by this class.

Methods

fun int open(string path[, int flags]) 
Opens the specified file, returning true on success and false otherwise. The flags can optionally be used to specify the mode in which to open the file (FileIO.MODE_READ_WRITE | FileIO.MODE_ASCII by default).
fun void seek(int pos) 
Seeks to the specified byte offset from the start of the file.
fun int tell() 
Returns the current position in the file in bytes, or -1 if a file is not open.
fun int size() 
Returns the size of the file in bytes, or -1 if a file is not open.

Directories

fun int isDir() 
Returns true if the opened file is a directory, false otherwise.
fun string[] dirList() 
Returns an array containing the names of each file in the opened directory, or an empty array if the opened file is not a directory.

Constants

FileIO.FLAG_READ_WRITE
FileIO.FLAG_READONLY
FileIO.FLAG_WRITEONLY
FileIO.FLAG_APPEND 
These flags can optionally be passed to the open function to specify the mode in which to open the file.
FileIO.TYPE_ASCII
FileIO.TYPE_BINARY 
These flags can optionally be passed to the open function to specify whether reading and writing should proceed in ASCII (readable text) or binary mode.

Examples

1. Functions to read and write an array of integers in binary mode.

fun void writeInts(int integers[], string path) {

    // open the file
    FileIO file;
    if (!file.open(path, FileIO.MODE_WRITEONLY | FileIO.MODE_BINARY))
        return; // error opening the specified file
    
    // write out the size and contents of the array
    file <~ integers.size();
    for (0 => int i; i < integers.size(); i++)
        file <~ integers[i];
        
    // and we're done
    file.close(); // automatically calls file.finish()

}

fun int[] readInts(string path) {
    
    // open the file
    FileIO file;
    if (!file.open(path, FileIO.MODE_READONLY | FileIO.MODE_BINARY)) {
        int ret[0]; // error opening the specified file
        return ret;
    }
    
    // read the size of the array
    file ~> int size;
    file.finish(); // wait for the read to finish without advancing time
                   // before continuing
    
    // now read in the contents
    int ret[size];
    for (0 => int i; i < size; i++)
        file ~> ret[i];
        
    // and we're done
    file.close(); // automatically calls file.finish()
    return ret;
    
}

2. Function to append a string to the end of a log file (uses seek and size).

fun void logAppend(FileIO log, string entry) {

    // file already given to us...make sure it is open
    if (log.isClosed())
        return;
        
    log.size() => log.seek; // move to end of file
    log <~ entry <~ "\n"; // write the entry, terminate with newline
    
    // don't close the file or wait for the queued I/O to
    // finish--that's up to the calling function

}

3. TODO: Using directories