BSD style: see
license.txt
Mar 2004: Initial release
Dec 2006: Outback release
Nov 2008: relocated and simplified
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.
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.
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.