File

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.

class File : Device , Device.Seek, Device.Truncate {

alias read = Device.read;

alias write = Device.write;

enum Style ReadExisting;

enum Style ReadShared;

enum Style WriteExisting;

enum Style WriteCreate;

enum Style WriteAppending;

enum Style ReadWriteExisting;

enum Style ReadWriteCreate;

enum Style ReadWriteOpen;

this(const(char[]) path, Style style);

Style style [@property getter];

immutable(char)[] toString();

static void[] get(const(char)[] path, void[] dst);

static void set(const(char)[] path, const(void)[] content);

static void append(const(char)[] path, const(void)[] content);

bool open(const(char)[] path, Style style, DWORD addattr);

void open(const(char[]) path, Style style);

void truncate();

void truncate(long size);

long seek(long offset, Anchor anchor);

long position [@property getter];

long length [@property getter];

bool open(const(char[]) path, Style style, int addflags, int access);

void open(const(char[]) path, Style style);

void truncate();

void truncate(long size);

long seek(long offset, Anchor anchor);

long position [@property getter];

long length [@property getter];

}

Constructors

this this(): Create a File for use with open().
this this(const(char[]) path, Style style): Create a File with the provided path and style.

Members

Aliases

read alias read = Device.read: Undocumented in source.
write alias write = Device.write: Undocumented in source.

Enums

Access enum Access
Cache enum Cache
Open enum Open
Share enum Share

Functions

open bool open(const(char)[] path, Style style, DWORD addattr): Low level open for sub-classes that need to apply specific attributes.
open void open(const(char[]) path, Style style): Open a file with the provided style.
open bool open(const(char[]) path, Style style, int addflags, int access): Low level open for sub-classes that need to apply specific attributes.
open void open(const(char[]) path, Style style): Open a file with the provided style.
seek long seek(long offset, Anchor anchor): Set the file seek position to the specified offset from the given anchor.
seek long seek(long offset, Anchor anchor): Set the file seek position to the specified offset from the given anchor.
sync void sync(): Instructs the OS to flush it's internal buffers to the disk device.
sync void sync(): Instructs the OS to flush it's internal buffers to the disk device.
toString immutable(char)[] toString(): Return the path used by this file.
truncate void truncate(): Set the file size to be that of the current seek position. The file must be writable for this to succeed.
truncate void truncate(long size): Set the file size to be the specified length. The file must be writable for this to succeed.
truncate void truncate(): Set the file size to be that of the current seek position. The file must be writable for this to succeed.
truncate void truncate(long size): Set the file size to be the specified length. The file must be writable for this to succeed.

Properties

length long length [@property getter]: Return the total length of this file.
length long length [@property getter]: Return the total length of this file.
position long position [@property getter]: Return the current file position.
position long position [@property getter]: Return the current file position.
style Style style [@property getter]: Return the Style used for this file.

Static functions

append void append(const(char)[] path, const(void)[] content): Convenience function to append content to a file.
get void[] get(const(char)[] path, void[] dst): 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.
set void set(const(char)[] path, const(void)[] content): Convenience function to set file content and length to reflect the given array.

Structs

Style struct Style: Fits into 32 bits ...

Variables

ReadExisting enum Style ReadExisting;: Read an existing file.
ReadShared enum Style ReadShared;: Read an existing file.
ReadWriteCreate enum Style ReadWriteCreate;: Read & write on a clean file. Create if necessary.
ReadWriteExisting enum Style ReadWriteExisting;: Read and write an existing file.
ReadWriteOpen enum Style ReadWriteOpen;: Read and Write. Use existing file if present.
WriteAppending enum Style WriteAppending;: Write at the end of the file.
WriteCreate enum Style WriteCreate;: Write on a clean file. Create if necessary.
WriteExisting enum Style WriteExisting;: Write on an existing file. Do not create.

Inherited Members

From Device

error alias error = Conduit.error: expose superclass definition also
error void error(): Throw an IOException noting the last error.
toString immutable(char)[] toString(): Return the name of this device.
bufferSize size_t bufferSize(): Return a preferred size for buffering conduit I/O.
IO struct IO: Windows-specific code.
io IO io;: Windows-specific code.
reopen void reopen(Handle handle): Allow adjustment of standard IO handles.
fileHandle Handle fileHandle [@property getter]: Return the underlying OS handle of this Conduit.
dispose void dispose()
detach void detach(): Release the underlying file. Note that an exception is not thrown on error, as doing so can induce some spaggetti into error handling. Instead, we need to change this to return a bool instead, so the caller can decide what to do.
read size_t read(void[] dst): Read a chunk of bytes from the file into the provided array. Returns the number of bytes read, or Eof where there is no further data.
write size_t write(const(void)[] src): Write a chunk of bytes to the file from the provided array. Returns the number of bytes written, or Eof if the output is no longer available.
wait size_t wait(scheduler.Type type, uint bytes, uint timeout)
handle int handle;: Unix-specific code.
reopen void reopen(Handle handle): Allow adjustment of standard IO handles.
fileHandle Handle fileHandle [@property getter]: Return the underlying OS handle of this Conduit.
detach void detach(): Release the underlying file.
read size_t read(void[] dst): Read a chunk of bytes from the file into the provided array. Returns the number of bytes read, or Eof where there is no further data.
write size_t write(const(void)[] src): Write a chunk of bytes to the file from the provided array. Returns the number of bytes written, or Eof if the output is no longer available.

Meta

Source

See Implementation

tango io device File classes

File

functions

main