Bob Nystrom
60fc3ff59c
Implement File.create() and File.delete() static methods with async libuv operations, add writeBytes() instance method for writing at offsets, introduce FileFlags constants class mirroring POSIX open() flags, refactor File.open() to accept flag parameters via openWithFlags(), and update documentation and module registration accordingly.
118 lines
2.8 KiB
Markdown
118 lines
2.8 KiB
Markdown
^title File Class
|
|
|
|
Lets you work with files on the file system. An instance of this class
|
|
represents an open file with a file descriptor.
|
|
|
|
When you are done with a file object, it's a good idea to explicitly close it.
|
|
If you don't, the GC will close it when the file is no longer used and gets
|
|
finalized, but that may take a while. In the meantime, leaving it open wastes
|
|
a file descriptor.
|
|
|
|
## Static Methods
|
|
|
|
### File.**create**(path, fn)
|
|
|
|
Opens the file at `path` for writing and passes it to `fn`. If there is already
|
|
a file at that path, it is truncated. After the function returns, the file is
|
|
automatically closed.
|
|
|
|
:::wren
|
|
File.create("numbers.txt") {|file|
|
|
file.writeBytes("one two three")
|
|
}
|
|
|
|
### File.**delete**(path)
|
|
|
|
Deletes the file at `path`.
|
|
|
|
### File.**open**(path, fn)
|
|
|
|
Opens the file at `path` for reading and passes it to `fn`. After the function
|
|
returns, the file is automatically closed.
|
|
|
|
:::wren
|
|
File.open("words.txt") {|file|
|
|
file.readBytes(5)
|
|
}
|
|
|
|
### File.**read**(path)
|
|
|
|
Reads the entire contents of the file at `path` and returns it as a string.
|
|
|
|
:::wren
|
|
File.read("words.txt")
|
|
|
|
The encoding or decoding is done. If the file is UTF-8, then the resulting
|
|
string will be a UTF-8 string. Otherwise, it will be a string of bytes in
|
|
whatever encoding the file uses.
|
|
|
|
### File.**size**(path)
|
|
|
|
Returns the size in bytes of the contents of the file at `path`.
|
|
|
|
## Constructors
|
|
|
|
### File.**create**(path)
|
|
|
|
Opens the file at `path` for writing. If there is already a file at that path,
|
|
it is truncated.
|
|
|
|
:::wren
|
|
var file = File.create("colors.txt")
|
|
file.writeBytes("chartreuse lime teal")
|
|
file.close()
|
|
|
|
### File.**open**(path)
|
|
|
|
Opens the file at `path` for reading. You are responsible for closing it when
|
|
done with it.
|
|
|
|
## Methods
|
|
|
|
### **descriptor**
|
|
|
|
The numeric file descriptor used to access the file.
|
|
|
|
### **isOpen**
|
|
|
|
Whether the file is still open or has been closed.
|
|
|
|
### **size**
|
|
|
|
The size of the contents of the file in bytes.
|
|
|
|
### **close**()
|
|
|
|
Closes the file. After calling this, you can read or write from it.
|
|
|
|
### **readBytes**(count)
|
|
|
|
Reads up to `count` bytes starting from the beginning of the file.
|
|
|
|
:::wren
|
|
// Assume this file contains "I am a file!".
|
|
File.open("example.txt") {|file|
|
|
System.print(file.readBytes(6)) //> I am a
|
|
}
|
|
|
|
### **readBytes**(count, offset)
|
|
|
|
Reads up to `count` bytes starting at `offset` bytes from the beginning of
|
|
the file.
|
|
|
|
:::wren
|
|
// Assume this file contains "I am a file!".
|
|
File.open("example.txt") {|file|
|
|
System.print(file.readBytes(6, 2)) //> am a f
|
|
}
|
|
|
|
### **writeBytes**(bytes)
|
|
|
|
Writes the raw bytes of the string `bytes` to the end of the file.
|
|
|
|
### **writeBytes**(bytes, offset)
|
|
|
|
Writes the raw bytes of the string `bytes` to the to the file, starting at
|
|
`offset`. Any overlapping bytes already in the file at the offset are
|
|
overwritten.
|