mirrors/phobos
1
0
Fork 0
mirror of https://github.com/dlang/phobos.git synced 2025-04-29 06:30:28 +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
(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;