mirrors/phobos
1
0
Fork 0
mirror of https://github.com/dlang/phobos.git synced 2025-04-29 22:50:38 +03:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

DDoc -std.stdio: exceptions thrown by C-like API.

Browse source 
Updated documentation for all the C-like member functions \
(and the File ctor) to specify exactly what gets thrown when. 

(note: Exceptions in std.stdio are a mess and should be made 
 more consistent. Also, it seems some member functions that 
 should check if the file is opened do not, but I don't know
 if that might be intentional (as the C functions should fail 
 anyway, resulting in a throw))
This commit is contained in:
Ferdinand Majerech 2013-04-10 23:36:27 +03:00
parent 0927fd2d37
commit 402af9d0c4
1 changed files with 74 additions and 37 deletions
Download patch file Download diff file Expand all files Collapse all files

111
std/stdio.d
View file

@ -302,13 +302,15 @@ struct File
Constructor taking the name of the file to open and the open mode Constructor taking the name of the file to open and the open mode
(with the same semantics as in the C standard library $(WEB (with the same semantics as in the C standard library $(WEB
cplusplus.com/reference/clibrary/cstdio/fopen.html, fopen) cplusplus.com/reference/clibrary/cstdio/fopen.html, fopen)
function). Throws an exception if the file could not be opened. function).
Copying one $(D File) object to another results in the two $(D File) Copying one $(D File) object to another results in the two $(D File)
objects referring to the same underlying file. objects referring to the same underlying file.
The destructor automatically closes the file as soon as no $(D File) The destructor automatically closes the file as soon as no $(D File)
object refers to it anymore. object refers to it anymore.
Throws: $(D ErrnoException) if the file could not be opened.
*/ */
this(string name, in char[] stdioOpenmode = "rb") this(string name, in char[] stdioOpenmode = "rb")
{ {
@ -345,7 +347,8 @@ First calls $(D detach) (throwing on failure), and then attempts to
_open file $(D name) with mode $(D stdioOpenmode). The mode has the _open file $(D name) with mode $(D stdioOpenmode). The mode has the
same semantics as in the C standard library $(WEB same semantics as in the C standard library $(WEB
cplusplus.com/reference/clibrary/cstdio/fopen.html, fopen) function. cplusplus.com/reference/clibrary/cstdio/fopen.html, fopen) function.
Throws exception in case of error.
Throws: $(D ErrnoException) in case of error.
*/ */
void open(string name, in char[] stdioOpenmode = "rb") void open(string name, in char[] stdioOpenmode = "rb")
{ {
@ -357,6 +360,8 @@ Throws exception in case of error.
First calls $(D detach) (throwing on failure), and then runs a command First calls $(D detach) (throwing on failure), and then runs a command
by calling the C standard library function $(WEB by calling the C standard library function $(WEB
opengroup.org/onlinepubs/007908799/xsh/_popen.html, _popen). opengroup.org/onlinepubs/007908799/xsh/_popen.html, _popen).
Throws: $(D ErrnoException) in case of error.
*/ */
version(Posix) void popen(string command, in char[] stdioOpenmode = "r") version(Posix) void popen(string command, in char[] stdioOpenmode = "r")
{ {
@ -374,8 +379,9 @@ opengroup.org/onlinepubs/007908799/xsh/_popen.html, _popen).
/** /**
Returns $(D true) if the file is at end (see $(WEB Returns $(D true) if the file is at end (see $(WEB
cplusplus.com/reference/clibrary/cstdio/feof.html, feof)). The file cplusplus.com/reference/clibrary/cstdio/feof.html, feof)).
must be opened, otherwise an exception is thrown.
Throws: $(D Exception) if the file is not opened.
*/ */
@property bool eof() const pure @property bool eof() const pure
{ {
@ -402,8 +408,9 @@ the file handle.
} }
/** /**
Detaches from the underlying file. If the sole owner, calls $(D close) Detaches from the underlying file. If the sole owner, calls $(D close).
and throws if that fails.
Throws: $(D ErrnoException) on failure if closing the file.
*/ */
void detach() void detach()
{ {
@ -439,6 +446,8 @@ throwing on error. Even if an exception is thrown, afterwards the $(D
File) object is empty. This is different from $(D detach) in that it File) object is empty. This is different from $(D detach) in that it
always closes the file; consequently, all other $(D File) objects always closes the file; consequently, all other $(D File) objects
referring to the same handle will see a closed file henceforth. referring to the same handle will see a closed file henceforth.
Throws: $(D ErrnoException) on error.
*/ */
void close() void close()
{ {
@ -481,9 +490,10 @@ _clearerr) for the file handle.
} }
/** /**
If the file is not opened, throws an exception. Otherwise, calls $(WEB Calls $(WEB cplusplus.com/reference/clibrary/cstdio/_fflush.html, _fflush)
cplusplus.com/reference/clibrary/cstdio/_fflush.html, _fflush) for the for the file handle.
file handle and throws on error.
Throws: $(D Exception) if the file is not opened or if the call to $D(fflush) fails.
*/ */
void flush() void flush()
{ {
@ -493,15 +503,17 @@ file handle and throws on error.
} }
/** /**
If the file is not opened, throws an exception. Otherwise, calls $(WEB Calls $(WEB cplusplus.com/reference/clibrary/cstdio/fread.html, fread) for the
cplusplus.com/reference/clibrary/cstdio/fread.html, fread) for the file handle. The number of items to read and the size of
file handle and throws on error. The number of items to read and the size of
each item is inferred from the size and type of the input array, respectively. each item is inferred from the size and type of the input array, respectively.
Returns: The slice of $(D buffer) containing the data that was actually read. Returns: The slice of $(D buffer) containing the data that was actually read.
This will be shorter than $(D buffer) if EOF was reached before the buffer This will be shorter than $(D buffer) if EOF was reached before the buffer
could be filled. could be filled.
Throws: $(D Exception) if $(D buffer) is empty.
$(D ErrnoException) if the file is not opened or the call to $D(fread) fails.
$(D rawRead) always reads in binary mode on Windows. $(D rawRead) always reads in binary mode on Windows.
*/ */
T[] rawRead(T)(T[] buffer) T[] rawRead(T)(T[] buffer)
@ -542,13 +554,14 @@ $(D rawRead) always reads in binary mode on Windows.
} }
/** /**
If the file is not opened, throws an exception. Otherwise, calls $(WEB Calls $(WEB cplusplus.com/reference/clibrary/cstdio/fwrite.html, fwrite) for the file
cplusplus.com/reference/clibrary/cstdio/fwrite.html, fwrite) for the file handle. The number of items to write and the size of each
handle and throws on error. The number of items to write and the size of each
item is inferred from the size and type of the input array, respectively. An item is inferred from the size and type of the input array, respectively. An
error is thrown if the buffer could not be written in its entirety. error is thrown if the buffer could not be written in its entirety.
$(D rawWrite) always writes in binary mode on Windows. $(D rawWrite) always writes in binary mode on Windows.
Throws: $(D ErrnoException) if the file is not opened or if the call to $D(fread) fails.
*/ */
void rawWrite(T)(in T[] buffer) void rawWrite(T)(in T[] buffer)
{ {
@ -588,9 +601,11 @@ $(D rawWrite) always writes in binary mode on Windows.
} }
/** /**
If the file is not opened, throws an exception. Otherwise, calls $(WEB Calls $(WEB cplusplus.com/reference/clibrary/cstdio/fseek.html, fseek)
cplusplus.com/reference/clibrary/cstdio/fseek.html, fseek) for the for the file handle.
file handle. Throws on error.
Throws: $(D Exception) if the file is not opened.
$(D ErrnoException) if the call to $D(fseek) fails.
*/ */
void seek(long offset, int origin = SEEK_SET) void seek(long offset, int origin = SEEK_SET)
{ {
@ -635,9 +650,11 @@ file handle. Throws on error.
} }
/** /**
If the file is not opened, throws an exception. Otherwise, calls $(WEB Calls $(WEB cplusplus.com/reference/clibrary/cstdio/ftell.html, ftell) for the
cplusplus.com/reference/clibrary/cstdio/ftell.html, ftell) for the managed file handle.
managed file handle. Throws on error.
Throws: $(D Exception) if the file is not opened.
$(D ErrnoException) if the call to $D(ftell) fails.
*/ */
@property ulong tell() const @property ulong tell() const
{ {
@ -667,9 +684,10 @@ managed file handle. Throws on error.
} }
/** /**
If the file is not opened, throws an exception. Otherwise, calls $(WEB Calls $(WEB cplusplus.com/reference/clibrary/cstdio/_rewind.html, _rewind)
cplusplus.com/reference/clibrary/cstdio/_rewind.html, _rewind) for the for the file handle.
file handle. Throws on error.
Throws: $(D Exception) if the file is not opened.
*/ */
void rewind() void rewind()
{ {
@ -678,9 +696,11 @@ file handle. Throws on error.
} }
/** /**
If the file is not opened, throws an exception. Otherwise, calls $(WEB Calls $(WEB cplusplus.com/reference/clibrary/cstdio/_setvbuf.html, _setvbuf) for
cplusplus.com/reference/clibrary/cstdio/_setvbuf.html, _setvbuf) for
the file handle. the file handle.
Throws: $(D Exception) if the file is not opened.
$(D ErrnoException) if the call to $D(setvbuf) fails.
*/ */
void setvbuf(size_t size, int mode = _IOFBF) void setvbuf(size_t size, int mode = _IOFBF)
{ {
@ -690,9 +710,12 @@ the file handle.
} }
/** /**
If the file is not opened, throws an exception. Otherwise, calls Calls $(WEB cplusplus.com/reference/clibrary/cstdio/_setvbuf.html,
$(WEB cplusplus.com/reference/clibrary/cstdio/_setvbuf.html, _setvbuf) for the file handle.
_setvbuf) for the file handle. */
Throws: $(D Exception) if the file is not opened.
$(D ErrnoException) if the call to $D(setvbuf) fails.
*/
void setvbuf(void[] buf, int mode = _IOFBF) void setvbuf(void[] buf, int mode = _IOFBF)
{ {
enforce(isOpen, "Attempting to call setvbuf() on an unopened file"); enforce(isOpen, "Attempting to call setvbuf() on an unopened file");
@ -702,8 +725,11 @@ _setvbuf) for the file handle. */
} }
/** /**
If the file is not opened, throws an exception. Otherwise, writes its Writes its arguments in text format to the file.
arguments in text format to the file. */
Throws: $(D Exception) if the file is not opened.
$(D ErrnoException) on an error writing to the file.
*/
void write(S...)(S args) void write(S...)(S args)
{ {
auto w = lockingTextWriter; auto w = lockingTextWriter;
@ -739,24 +765,35 @@ arguments in text format to the file. */
} }
/** /**
If the file is not opened, throws an exception. Otherwise, writes its Writes its arguments in text format to the file, followed by a newline.
arguments in text format to the file, followed by a newline. */
Throws: $(D Exception) if the file is not opened.
$(D ErrnoException) on an error writing to the file.
*/
void writeln(S...)(S args) void writeln(S...)(S args)
{ {
write(args, '\n'); write(args, '\n');
} }
/** /**
If the file is not opened, throws an exception. Otherwise, writes its Writes its arguments in text format to the file, according to the
arguments in text format to the file, according to the format in the format in the first argument.
first argument. */
Throws: $(D Exception) if the file is not opened.
$(D ErrnoException) on an error writing to the file.
*/
void writef(Char, A...)(in Char[] fmt, A args) void writef(Char, A...)(in Char[] fmt, A args)
{ {
std.format.formattedWrite(lockingTextWriter, fmt, args); std.format.formattedWrite(lockingTextWriter, fmt, args);
} }
/** /**
Same as writef, plus adds a newline. */ Writes its arguments in text format to the file, according to the
format in the first argument, followed by a newline.
Throws: $(D Exception) if the file is not opened.
$(D ErrnoException) on an error writing to the file.
*/
void writefln(Char, A...)(in Char[] fmt, A args) void writefln(Char, A...)(in Char[] fmt, A args)
{ {
auto w = lockingTextWriter; auto w = lockingTextWriter;