IO Streams

Github Page

IO Streams
License
Boost License 1.0.
Authors
Jason White

enum  Mode: int;

Specifies in what mode a file should be opened. These flags can be combined.

 none

Default mode. Not very useful.

 open

Opens an existing file. Unless combined with create, fails if the file does not exist.

 create

Creates a new file. Fails if the file is opened without write access. Fails if the file already exists and not combined with truncate or open.

 openOrCreate

Opens the file if it already exists or creates it if it does not.

 append

Allows only appending to the end of the file. Seek operations only affect subsequent reads. Upon writing, the file pointer gets set to the end of the file. Requires write access to the file.

 truncate

Truncates the file. This has no effect if the file has been created anew. Requires write access to the file.

enum  Share: int;

Specifies what other processes are allowed to do to the file. These flags can be combined.

Windows specific:
Currently only used by Windows.

 none

Forbids sharing of the file.

 read

Allows others to  read from the file.

 write

Allows others to  write to the file.

 readWrite

Allows others to either read or write to the file.

 remove

Allows the file to deleted.

struct  FileFlags;

File flags that determine how a file stream is created and used.

Since all methods in this struct are pure, the high-level configuration flags given here are converted to the platform-specific file flags at compile time.

See Also
io.file.stream
Example:
// Creates the file "foobar", truncates it, and opens it in write-only mode
auto f = File("foobar", FileFlags.writeEmpty);

static immutable FileFlags  readExisting;

An existing file is opened with read access. This is likely the most commonly used set of flags.

static immutable FileFlags  writeExisting;

An existing file is opened with write access.

static immutable FileFlags  writeNew;

A new file is created with write access. Fails if the file already exists.

static immutable FileFlags  writeAlways;

A new file is either opened or created with write access.

static immutable FileFlags  writeEmpty;

A new file is either opened or created, truncated if necessary, with write access. This ensures that an empty file is opened.

static immutable FileFlags  readWriteExisting;

An existing file is opened with read/write access.

static immutable FileFlags  readWriteNew;

A new file is created with read/write access. Fails if the file already exists.

static immutable FileFlags  readWriteAlways;

A new file is either opened or created with read/write access.

static immutable FileFlags  readWriteEmpty;

A new file is either opened or created, truncated if necessary, with read/write access. This ensures that an empty file is opened.

pure nothrow this(Mode mode, Access access, Share share = Share.init);

Constructs the FileFlag with the given mode, access, and share attributes. These high-level flags are converted to the equivalent platform-specific flags that are needed when opening the file.

Parameters
Mode mode Mode the file should be opened in. That is, to open, create, append, or truncate the file.
Access access The permissions on the file stream. That is, read access, write access, or both.
Share share The sharing permissions other processes are allowed on the file stream when trying to open the same file. By default, other processes are prevented from opening the file if they request read, write, or delete access. If you wish to allow other processes to read the file while it is open in this process, set this to Share.read. Currently only used by Windows.
Windows specific:
The share parameter is currently only used by Windows.
Example:
immutable flags = FileFlags(Mode.open, Access.read);

pure this(string mode);
pure void  opAssign(string mode);

Constructs the file flags from a mode string.

This simply calls FileFlags.parse.

See Also
FileFlags.parse
Examples
FileFlags ff = "wb+";
assert(ff == FileFlags.readWriteEmpty);
assert(ff == FileFlags("wb+"));

static pure FileFlags  parse(string mode);

Parses an fopen-style mode string such as "r+". All possible mode strings include:

Mode String Meaning
"wb" Write truncated
"wb+" Read/write truncated
"w+b" Read/write truncated
"wbx" Write new
"wb+x" Read/write new
"w+bx" Read/write new
"rb" Read existing"
"rb+" Read/write existing"
"r+b" Read/write existing"
"ab" Append new"
"ab+" Append/read new"
"a+b" Append/read new"


The mode strings accepted here differ from those accepted by fopen. Here, file streams are never opened in text mode -- only binary mode. Text handling functionality is built on top of low-level file streams. It does not make sense to distinguish between text and binary modes here. fopen opens all files in text mode by default and the flag 'b' must be specified in order to open in binary mode. Thus, an exception is thrown here if 'b' is omitted in the specified mode string.

Note:
It is not advisable to use fopen-style mode strings. It is better to use one of the predefined file flag configurations such as FileFlags.readExisting for greater readability and intent of meaning.
Examples
static assert(FileFlags("wb")   == FileFlags.writeEmpty);
static assert(FileFlags("wb+")  == FileFlags.readWriteEmpty);
static assert(FileFlags("w+b")  == FileFlags.readWriteEmpty);
static assert(FileFlags("wbx")  == FileFlags.writeNew);
static assert(FileFlags("wb+x") == FileFlags.readWriteNew);
static assert(FileFlags("w+bx") == FileFlags.readWriteNew);
static assert(FileFlags("rb")   == FileFlags.readExisting);
static assert(FileFlags("rb+")  == FileFlags.readWriteExisting);
static assert(FileFlags("r+b")  == FileFlags.readWriteExisting);
static assert(FileFlags("ab")   == FileFlags(Mode.openOrCreate | Mode.append, Access.write));
static assert(FileFlags("ab+")  == FileFlags(Mode.openOrCreate | Mode.append, Access.readWrite));
static assert(FileFlags("a+b")  == FileFlags(Mode.openOrCreate | Mode.append, Access.readWrite));