tango.io.device.File

License:

BSD style: see license.txt

Version:

Mar 2004: Initial release
Dec 2006: Outback release
Nov 2008: relocated and simplified

Authors:

Kris, John Reimer, Anders F Bjorklund (Darwin patches), Chris Sauls (Win95 file support)
class File : Device, Device.Seek, Device.Truncate #
Implements a means of reading and writing a generic file. Conduits are the primary means of accessing external data, and File extends the basic pattern by providing file-specific methods to set the file size, seek to a specific file position and so on.
Serial input and output is straightforward. In this example we copy a file directly to the console:
1
2
3
4
5
// open a file for reading
auto from = new File ("test.txt");

// stream directly to console
Stdout.copy (from);

And here we copy one file to another:

1
2
3
4
5
6
7
8
9
// open file for reading
auto from = new File ("test.txt");

// open another for writing
auto to = new File ("copy.txt", File.WriteCreate);

// copy file and close
to.copy.close;
from.close;

You can use InputStream.load() to load a file directly into memory:

1
2
3
auto file = new File ("test.txt");
auto content = file.load;
file.close;

Or use a convenience static function within File:

1
auto content = File.get ("test.txt");

A more explicit version with a similar result would be:

1
2
3
4
5
6
7
8
9
// open file for reading
auto file = new File ("test.txt");

// create an array to house the entire file
auto content = new char [file.length];

// read the file content. Return value is the number of bytes read
auto bytes = file.read (content);
file.close;

Conversely, one may write directly to a File like so:

1
2
3
4
5
// open file for writing
auto to = new File ("text.txt", File.WriteCreate);

// write an array of content to it
auto bytes = to.write (content);

There are equivalent static functions, File.set() and File.append(), which set or append file content respectively.

File can happily handle random I/O. Here we use seek() to relocate the file pointer:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
// open a file for reading and writing
auto file = new File ("random.bin", File.ReadWriteCreate);

// write some data
file.write ("testing");

// rewind to file start
file.seek (0);

// read data back again
char[10] tmp;
auto bytes = file.read (tmp);

file.close;

Note that File is unbuffered by default - wrap an instance within tango.io.stream.Buffered for buffered I/O.

Compile with -version=Win32SansUnicode to enable Win95 & Win32s file support.

struct Style #
Fits into 32 bits ...
Access access #
Access rights.
Open open #
How to open.
Share share #
How to share.
Cache cache #
How to cache.
enum Access #
Read #
Is readable.
Write #
Is writable.
ReadWrite #
Both.
enum Open #
Exists #
Must exist.
Create #
Create or truncate.
Sedate #
Create if necessary.
Append #
Create if necessary.
New #
Can't exist.
enum Share #
None #
No sharing.
Read #
Shared reading.
ReadWrite #
Open for anything.
enum Cache #
None #
Don't optimize.
Random #
Optimize for random.
Stream #
Optimize for stream.
WriteThru #
Backing-cache flag.
Style ReadExisting [const] #
Read an existing file.
Style ReadShared [const] #
Read an existing file.
Style WriteExisting [const] #
Write on an existing file. Do not create.
Style WriteCreate [const] #
Write on a clean file. Create if necessary.
Style WriteAppending [const] #
Write at the end of the file.
Style ReadWriteExisting [const] #
Read and write an existing file.
Style ReadWriteCreate [const] #
Read & write on a clean file. Create if necessary.
Style ReadWriteOpen [const] #
Read and Write. Use existing file if present.
this() #
Create a File for use with open().
Note that File is unbuffered by default - wrap an instance within tango.io.stream.Buffered for buffered I/O.
this(char[] path, Style style = ReadExisting) #
Create a File with the provided path and style.
Note that File is unbuffered by default - wrap an instance within tango.io.stream.Buffered for buffered I/O.
Style style() #
Return the Style used for this file.
char[] toString() [override] #
Return the path used by this file.
void[] get(char[] path, void[] dst = null) [static] #
Convenience function to return the content of a file. Returns a slice of the provided output buffer, where that has sufficient capacity, and allocates from the heap where the file content is larger.
Content size is determined via the file-system, per File.length, although that may be misleading for some nix systems. An alternative is to use File.load which loads content until an Eof is encountered.
void set(char[] path, void[] content) [static] #
Convenience function to set file content and length to reflect the given array.
void append(char[] path, void[] content) [static] #
Convenience function to append content to a file.
bool open(char[] path, Style style, DWORD addattr) [protected] #
Low level open for sub-classes that need to apply specific attributes.

Return:

False in case of failure.
void open(char[] path, Style style = ReadExisting) #
Open a file with the provided style.
void truncate() #
Set the file size to be that of the current seek position. The file must be writable for this to succeed.
void truncate(long size) [override] #
Set the file size to be the specified length. The file must be writable for this to succeed.
long seek(long offset, Anchor anchor = Anchor.Begin) [override] #
Set the file seek position to the specified offset from the given anchor.
long position() #
Return the current file position.
long length() #
Return the total length of this file.
void sync() #
Instructs the OS to flush it's internal buffers to the disk device.

NOTE:

Due to OS and hardware design, data flushed cannot be guaranteed to be actually on disk-platters. Actual durability of data depends on write-caches, barriers, presence of battery-backup, filesystem and OS-support.