Returns a stream that references the source named by
path
and allows the operations selected by
mode,
which should be one of:
"r" |
open for reading
| "w" |
create or truncate for writing
| "a" |
append; open for writing at the end of file, or create for writing
| "r+" |
open for update, which allows reading and writing
| "w+" |
truncate or create for update
|
open
returns
NULL
if the open failed.
path
and
mode
are often the only arguments and in that case
open
uses
path
to guess the stream type, with a
NULL
path
meaning a
StringStream.
The optional
stream
argument can be an
int,
File,
StringStream,
or
URL.
If
stream
is an
int
it must be
FILE,
URL,
or
STRINGSTREAM,
which are integer constants defined in
yoix.io,
and in that case
stream,
rather than
path,
determines the kind of stream that is opened.
Otherwise
stream
is the
File,
StringStream,
or
URL
that is used to open
path
and will be the return value if
open
succeeds.
However, on failure
open
always returns
NULL,
but in this case information about the failure may be recorded in
stream,
which is most useful when
stream
is a
URL
and you want access to the server's response.
The remaining optional arguments can be used to initialize fields
in the stream that
open
returns that are not explicitly set by
open.
They can be collected together in a
Dictionary
and supplied as the
init
argument, or they can be supplied as two or more arguments, organized in pairs,
with the first element being a
String
that names the field and the second element being the value that should be
assigned to that field.
Streams opened with
open
can be closed with
close
or
fclose.
Even though the interpreter tries to close streams that are open
but no longer accessible, it is not a foolproof implementation,
so an explicit close when you are done with an open stream is
the best policy.
| |
| Example: |
The program,
import yoix.*.*;
String line;
URL att;
if ((att = open("http://www.att.com", "r")) != NULL) {
while (line = att.nextline)
stdout.nextline = line;
close(att);
}
tries to copy the AT&T home page to standard output one line
at a time, but it lets
open
guess the stream type.
Exactly the same thing happens with the program,
import yoix.*.*;
String line;
URL att;
if ((att = open("http://www.att.com", "r", URL)) != NULL) {
while (line = att.nextline)
stdout.nextline = line;
close(att);
}
but in this case there is no guessing because we tell
open
that
path
should be treated as a
URL.
We probably also get the same result with the program,
import yoix.*.*;
String line;
URL att;
if ((att = open("http://www.att.com", "r", "usecaches", TRUE)) != NULL) {
while (line = att.nextline)
stdout.nextline = line;
close(att);
}
but in this case we asked
open
to set the field
usecaches
to
TRUE,
in the
URL
that was returned.
| | |
| Return: |
Stream
| | |
| See Also: |
close,
fclose,
fflush,
fopen,
freopen
|
|
