tango.io.device.File

License:
BSD style:

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: tango.io.device.Device.Device, tango.io.model.IConduit.IConduit.Seek, tango.io.model.IConduit.IConduit.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:
        // 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 = Style(cast(Access)cast(ubyte)1u,cast(Open)cast(ubyte)0u,cast(Share)cast(ubyte)0u,cast(Cache)cast(ubyte)0u));
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.


Page generated by Ddoc. Copyright (c) 2004 Kris Bell. All rights reserved