diff --git a/std/stdio.d b/std/stdio.d index 19bb1842e..dbf789331 100644 --- a/std/stdio.d +++ b/std/stdio.d @@ -302,13 +302,15 @@ struct File Constructor taking the name of the file to open and the open mode (with the same semantics as in the C standard library $(WEB 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) objects referring to the same underlying file. The destructor automatically closes the file as soon as no $(D File) object refers to it anymore. + +Throws: $(D ErrnoException) if the file could not be opened. */ 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 same semantics as in the C standard library $(WEB 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") { @@ -357,6 +360,8 @@ Throws exception in case of error. First calls $(D detach) (throwing on failure), and then runs a command by calling the C standard library function $(WEB 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") { @@ -374,8 +379,9 @@ opengroup.org/onlinepubs/007908799/xsh/_popen.html, _popen). /** Returns $(D true) if the file is at end (see $(WEB -cplusplus.com/reference/clibrary/cstdio/feof.html, feof)). The file -must be opened, otherwise an exception is thrown. +cplusplus.com/reference/clibrary/cstdio/feof.html, feof)). + +Throws: $(D Exception) if the file is not opened. */ @property bool eof() const pure { @@ -402,8 +408,9 @@ the file handle. } /** -Detaches from the underlying file. If the sole owner, calls $(D close) -and throws if that fails. +Detaches from the underlying file. If the sole owner, calls $(D close). + +Throws: $(D ErrnoException) on failure if closing the file. */ 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 always closes the file; consequently, all other $(D File) objects referring to the same handle will see a closed file henceforth. + +Throws: $(D ErrnoException) on error. */ void close() { @@ -481,9 +490,10 @@ _clearerr) for the file handle. } /** -If the file is not opened, throws an exception. Otherwise, calls $(WEB -cplusplus.com/reference/clibrary/cstdio/_fflush.html, _fflush) for the -file handle and throws on error. +Calls $(WEB cplusplus.com/reference/clibrary/cstdio/_fflush.html, _fflush) +for the file handle. + +Throws: $(D Exception) if the file is not opened or if the call to $D(fflush) fails. */ void flush() { @@ -493,15 +503,17 @@ file handle and throws on error. } /** -If the file is not opened, throws an exception. Otherwise, calls $(WEB -cplusplus.com/reference/clibrary/cstdio/fread.html, fread) for the -file handle and throws on error. The number of items to read and the size of +Calls $(WEB cplusplus.com/reference/clibrary/cstdio/fread.html, fread) for the +file handle. The number of items to read and the size of 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. This will be shorter than $(D buffer) if EOF was reached before the buffer 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. */ 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 -cplusplus.com/reference/clibrary/cstdio/fwrite.html, fwrite) for the file -handle and throws on error. The number of items to write and the size of each +Calls $(WEB cplusplus.com/reference/clibrary/cstdio/fwrite.html, fwrite) for the file +handle. 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 error is thrown if the buffer could not be written in its entirety. $(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) { @@ -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 -cplusplus.com/reference/clibrary/cstdio/fseek.html, fseek) for the -file handle. Throws on error. +Calls $(WEB cplusplus.com/reference/clibrary/cstdio/fseek.html, fseek) +for the file handle. + +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) { @@ -635,9 +650,11 @@ file handle. Throws on error. } /** -If the file is not opened, throws an exception. Otherwise, calls $(WEB -cplusplus.com/reference/clibrary/cstdio/ftell.html, ftell) for the -managed file handle. Throws on error. +Calls $(WEB cplusplus.com/reference/clibrary/cstdio/ftell.html, ftell) for the +managed file handle. + +Throws: $(D Exception) if the file is not opened. + $(D ErrnoException) if the call to $D(ftell) fails. */ @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 -cplusplus.com/reference/clibrary/cstdio/_rewind.html, _rewind) for the -file handle. Throws on error. +Calls $(WEB cplusplus.com/reference/clibrary/cstdio/_rewind.html, _rewind) +for the file handle. + +Throws: $(D Exception) if the file is not opened. */ void rewind() { @@ -678,9 +696,11 @@ file handle. Throws on error. } /** -If the file is not opened, throws an exception. Otherwise, calls $(WEB -cplusplus.com/reference/clibrary/cstdio/_setvbuf.html, _setvbuf) for +Calls $(WEB cplusplus.com/reference/clibrary/cstdio/_setvbuf.html, _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(size_t size, int mode = _IOFBF) { @@ -690,9 +710,12 @@ the file handle. } /** -If the file is not opened, throws an exception. Otherwise, calls -$(WEB cplusplus.com/reference/clibrary/cstdio/_setvbuf.html, -_setvbuf) for the file handle. */ +Calls $(WEB cplusplus.com/reference/clibrary/cstdio/_setvbuf.html, +_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) { 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 -arguments in text format to the file. */ +Writes its 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) { 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 -arguments in text format to the file, followed by a newline. */ +Writes its 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) { write(args, '\n'); } /** -If the file is not opened, throws an exception. Otherwise, writes its -arguments in text format to the file, according to the format in the -first argument. */ +Writes its arguments in text format to the file, according to the +format in the 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) { 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) { auto w = lockingTextWriter;