Although one may use the standard UNIX file interface (fprintf,
for example), the BIC Volume IO Library contains a set of routines for doing all
file operations, with the potential to be portable to other operating systems. There
are some other minor advantages, including the automatic expansion of ~
and environment variables. Also, automatic decompression of compressed
files is provided.
public STRING expand_filename(
STRING filename ) |
Searches the argument filename for certain patterns, and expands
them appropriately, returning the resulting expanded filename. Any sequence of
characters starting with a ~ up to but not including a slash,
/, will be changed to the specified user's home directory. Any
occurrence of a dollar sign, $, will result in the following
text, up to the next slash, being expanded to the environment variable specified by
the text. This expansion can be avoided by placing a backslash, \ before any
~ or $. In all the following functions
which take filenames, automatic expansion of filenames is performed.
public BOOLEAN file_exists(
STRING filename ) |
Returns TRUE if the file exists.
public BOOLEAN check_clobber_file(
STRING filename )
public BOOLEAN check_clobber_file_default_suffix(
STRING filename,
STRING default_suffix ) |
Checks to see if the file exists, and if so, prompts the user as to
whether it may be overwritten. Returns TRUE if either the file
does not exist, or if it does and the user answers `y' to the
prompt. The second form of the file appends a default suffix to the
filename, if it does not yet have a suffix.
public void remove_file(
STRING filename ) |
Removes the specified file, which results in the file being
removed only after all references to it are closed.
public BOOLEAN filename_extension_matches(
STRING filename,
STRING extension ) |
Returns TRUE if the file ends in the given extension, preceded
by a period. e.g., filename_extension_matches( "volume.mnc" , "mnc"
) returns TRUE. Correctly handles compressed files,
e.g., passing the arguments, "volume.mnc.Z" and
"mnc" returns TRUE.
public STRING remove_directories_from_filename(
STRING filename ) |
Strips the directories from the filename, returning the result.
public STRING extract_directory(
STRING filename ) |
Extracts the directory from the filename, returning the result.
public STRING get_absolute_filename(
STRING filename,
STRING directory ) |
Given a filename and a current directory, returns an absolute filename (one starting
with a slash, /.
public Status open_file(
STRING filename,
IO_types io_type,
File_formats file_format,
FILE **file )
public Status open_file_with_default_suffix(
STRING filename,
STRING default_suffix,
IO_types io_type,
File_formats file_format,
FILE **file ) |
The function open_file() opens the specified file, where
io_type must be one of WRITE_FILE or
READ_FILE, and file_format must be one of
ASCII_FORMAT or BINARY_FORMAT. If
successful, the file pointer is passed back in the last argument and a status of
OK is returned. Otherwise, a null pointer is passed back, and a
status of ERROR is returned. Filename expansion is
automatically performed. The second function performs the same task as
open_file with the addition that it automatically adds the
specified suffix extension, if needed. On input, if the specified file does not
exist and the file does not have an extension, then it looks for the specified file
with the default extension.
public Status close_file(
FILE *file ) |
Closes the file, returning OK if successful.
public Status set_file_position(
FILE *file,
long byte_position ) |
Seeks to the specified position in the file, where 0 corresponds to the beginning of
the file, returning OK if successful.
public Status flush_file(
FILE *file ) |
Flushes the file buffer of any pending output, returning OK if
successful.
public Status input_character(
FILE *file,
char *ch ) |
Inputs a character from the file and passes it back as the second argument. If the
character is the end of file character, returns a status of
ERROR, otherwise, OK.
public Status unget_character(
FILE *file,
char ch ) |
Places the character back on the input queue.
public Status input_nonwhite_character(
FILE *file,
char *ch ) |
Inputs the next non-white character, i.e. the next character that is neither a
blank, a tab, or a newline character.
public Status skip_input_until(
FILE *file,
char search_char ) |
Inputs characters from the file until the specified search character is found.
public Status input_string(
FILE *file,
STRING *str,
char termination_char ) |
Inputs a string from the file. The file is read into the string until either the
termination character or a newline character is found. If the string ends at a
newline character and the termination character is not a newline, the next character
available from the file will be the newline character. Otherwise, the next
character available is the one just after the termination character found.
public Status input_quoted_string(
FILE *file,
STRING *str ) |
Inputs a string from a file, delimited by quotation marks, returning
OK or ERROR. After successful reading of
a string, the next character available from the file is the one just after the
ending quotation mark.
public Status input_possibly_quoted_string(
FILE *file,
STRING *str ) |
Inputs a string from a file, delimited by quotation marks or white space, returning
OK or ERROR. After successful reading of
a string, the next character available from the file is the one just after the
ending quotation mark or last non-white space character.
public Status input_line(
FILE *file,
STRING line ) |
Inputs characters from the file into the argument line, up
until the next newline character. If a newline was found, the next available
character will be the one after the newline. The newline character is not stored in
the string.
public Status input_boolean(
FILE *file,
BOOLEAN *b ) |
Inputs the next non-white character. If it is a ``f'' or
``F'', then the value FALSE is passed
back. If it is a ``t'' or ``T'', then the
value TRUE is passed back. Otherwise
ERROR is returned.
public Status input_short(
FILE *file,
short *s )
public Status input_unsigned_short(
FILE *file,
unsigned short *s )
public Status input_int(
FILE *file,
int *i )
public Status input_real(
FILE *file,
Real *r )
public Status input_float(
FILE *file,
float *f )
public Status input_double(
FILE *file,
double *d ) |
Inputs a value of the specified type from an ascii file.
public Status input_newline(
FILE *file ) |
Inputs and discards characters from the file up to and including the next newline
character. Returns OK if a newline was found, or
ERROR if the end of file was reached first.
public Status input_binary_data(
FILE *file,
void *data,
size_t element_size,
int n ) |
Inputs an array of data from a file, in binary format. The array contains
n elements, each of size element_size.
Returns either OK or ERROR.
public Status output_character(
FILE *file,
char ch ) |
Outputs a character to the file, returning OK or
ERROR.
public Status output_string(
FILE *file,
STRING str ) |
Outputs the specified string to the file, returning OK or
ERROR.
public Status output_quoted_string(
FILE *file,
STRING str ) |
Outputs a quotation mark, the specified string, and a closing quotation mark.
public Status output_newline(
FILE *file ) |
Outputs a newline character, returning OK or
ERROR.
public Status output_boolean(
FILE *file,
BOOLEAN b ) |
If the argument is TRUE, then a space and the letter
``T'' is output, otherwise, a space and the letter
``F'' is output.
public Status output_short(
FILE *file,
short s )
public Status output_unsigned_short(
FILE *file,
unsigned short s )
public Status output_int(
FILE *file,
int i )
public Status output_real(
FILE *file,
Real r )
public Status output_float(
FILE *file,
float f )
public Status output_double(
FILE *file,
double d ) |
Outputs a space and then the specified value to an ascii file.
public Status output_binary_data(
FILE *file,
void *data,
size_t element_size,
int n ) |
Outputs an array of data to a file, in binary format. The array contains
n elements, each of size element_size.
Returns either OK or ERROR.
public Status io_binary_data(
FILE *file,
IO_types io_flag,
void *data,
size_t element_size,
int n ) |
Inputs or outputs the specified binary data, depending on whether the argument
io_flag is READ_FILE or
WRITE_FILE.
public Status io_newline(
FILE *file,
IO_types io_flag,
File_formats format ) |
Inputs or outputs an ascii newline character, depending on whether the argument
io_flag is READ_FILE or
WRITE_FILE. If the format argument is
BINARY_FORMAT, this function does nothing.
public Status io_quoted_string(
FILE *file,
IO_types io_flag,
File_formats format,
STRING str ) |
If the format argument is ASCII_FORMAT,
inputs or outputs a quotation mark delimited string, depending on whether the
argument io_flag is READ_FILE or
WRITE_FILE. IF the format argument is
BINARY_FORMAT, inputs or outputs a string preceded by an
integer indicating the length of the string.
public Status io_boolean(
FILE *file,
IO_types io_flag,
File_formats format,
BOOLEAN *b )
public Status io_short(
FILE *file,
IO_types io_flag,
File_formats format,
short *short_int )
public Status io_unsigned_short(
FILE *file,
IO_types io_flag,
File_formats format,
unsigned short *unsigned_short )
public Status io_unsigned_char(
FILE *file,
IO_types io_flag,
File_formats format,
unsigned char *c )
public Status io_int(
FILE *file,
IO_types io_flag,
File_formats format,
int *i )
public Status io_real(
FILE *file,
IO_types io_flag,
File_formats format,
Real *r )
public Status io_float(
FILE *file,
IO_types io_flag,
File_formats format,
float *f )
public Status io_double(
FILE *file,
IO_types io_flag,
File_formats format,
double *d ) |
Inputs or outputs a binary or ascii value of the specified type.
public Status io_ints(
FILE *file,
IO_types io_flag,
File_formats format,
int n,
int *ints[] ) |
Inputs or outputs an array of integers in binary or ascii
format.
public Status io_unsigned_chars(
FILE *file,
IO_types io_flag,
File_formats format,
int n,
unsigned char *unsigned_chars[] ) |
Inputs or outputs an array of unsigned characters in binary or ascii
format.