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:
// 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:
// 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:
auto file = new File ("test.txt");
auto content = file.load;
file.close;
Or use a convenience static function within File:
auto content = File.get ("test.txt");
A more explicit version with a similar result would be:
// 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:
// 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:
// 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;
- Read an existing file.
- Style ReadShared;
- Read an existing file.
- Style WriteExisting;
- Write on an existing file. Do not create.
- Style WriteCreate;
- Write on a clean file. Create if necessary.
- Style WriteAppending;
- Write at the end of the file.
- Style ReadWriteExisting;
- Read and write an existing file.
- Style ReadWriteCreate;
- Read & write on a clean file. Create if necessary.
- Style ReadWriteOpen;
- 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(const(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.
- const const @property Style style();
- Return the Style used for this file.
- immutable(char)[] toString();
- Return the path used by this file.
- static void[] get(const(char)[] path, void[] dst = null);
- 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.
- static void set(const(char)[] path, const(void)[] content);
- Convenience function to set file content and length to
reflect the given array.
- static void append(const(char)[] path, const(void)[] content);
- Convenience function to append content to a file.
- protected bool open(const(char[]) path, Style style, int addflags, int access = octal!(666));
- Low level open for sub-classes that need to apply specific
attributes.
Return:
False in case of failure.
Unix-specific code. Note that some methods are 32bit only.
- void open(const(char[]) path, Style style = ReadExisting);
- Open a file with the provided style.
Note that files default to no-sharing. That is,
they are locked exclusively to the host process
unless otherwise stipulated. We do this in order
to expose the same default behaviour as Win32.
No file locking for borked POSIX.
Unix-specific code. Note that some methods are 32bit only.
- void truncate();
- Set the file size to be that of the current seek
position. The file must be writable for this to
succeed.
Unix-specific code. Note that some methods are 32bit only.
- void truncate(long size);
- Set the file size to be the specified length. The
file must be writable for this to succeed.
Unix-specific code. Note that some methods are 32bit only.
- long seek(long offset, Anchor anchor = Anchor.Begin);
- Set the file seek position to the specified offset
from the given anchor.
Unix-specific code. Note that some methods are 32bit only.
- @property long position();
- Return the current file position.
Unix-specific code. Note that some methods are 32bit only.
- @property long length();
- Return the total length of this file.
Unix-specific code. Note that some methods are 32bit only.
- 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.
Unix-specific code. Note that some methods are 32bit only.