FileInput Struct Reference

Inheritance diagram for FileInput

Inheritance graph

Collaboration diagram for FileInput:

Collaboration graph


Public Methods

struct FileInput* FileInput_ctor (struct FileInput *ptr_file_input)
struct FileInput* FileInput_ctor_Ex (struct FileInput *ptr_file_input, char *sz_file_name)
bool FileInput_open (struct FileInput *ptr_file_input, char *sz_file_name)
long FileInput_seek (struct FileInput *ptr_file_input, long pos, seek_t mode)
long FileInput_tell (struct FileInput *ptr_file_input)
void FileInput_dtor (struct FileInput *ptr_file_input, int memory_flag)
long FileInput_read (struct FileInput *ptr_file_input, void *ptr_buffer, long length)
int FileInput_read_byte (struct FileInput *ptr_file_input)
long FileInput_seekg (struct FileInput *ptr_file_input, long pos, seek_t mode)
long FileInput_tellg (struct FileInput *ptr_file_input)
long FileInput_get_size (struct FileInput *ptr_file_input)
int FileInput_get_flags (struct FileInput *ptr_file_input)
bool FileInput_is_eof (struct FileInput *ptr_file_input)
bool FileInput_is_bad (struct FileInput *ptr_file_input)
bool FileInput_is_good (struct FileInput *ptr_file_input)

Detailed Description

Implements basic file input operations. Attempting to open or construct FileInput for a non-existing file will corrupt the file (FileInput_is_bad returns TRUE)

See also:
File I/O

Member Function Documentation

struct FileInput * FileInput_ctor ( struct FileInput * ptr_file_input )
 

Creates an empty input file stream object.

Parameters:
ptr_file_input   A pointer to the FileInput structure
Returns:
A pointer to the initialized FileInput object. 
       #include <cybiko.h>
       ...
       {
         char tenth_byte;
         struct FileInput file_input;
         ...
         FileInput_ctor( &file_input );
         ...
         if( FileInput_open( &file_input, "game.save" ) )
         {
           FileInput_seek( &file_input, 10, SEEK_SET );
           tenth_byte = FileInput_read_byte( &file_input );
         }
         ...
         FileInput_dtor( &file_input, LEAVE_MEMORY );
         ...
       }
See also:
FileInput_ctor_Ex.

struct FileInput * FileInput_ctor_Ex ( struct FileInput * ptr_file_input,
char * sz_file_name )
 

Creates an input file stream object for a file with the specified name.

Parameters:
ptr_file_input   A pointer to the FileInput structure
sz_file_name   Name of the file to open
Returns:
A pointer to the initialized FileInput object 
       #include <cybiko.h>
       ...
       char tenth_byte;
       struct FileInput file_input;
       ...
       FileInput_ctor_Ex( &file_input, "game.save");
       ...
       FileInput_seek( &file_input, 10, SEEK_SET );
       tenth_byte = FileInput_read_byte( &file_input );
       ...
       FileInput_dtor( &file_input, LEAVE_MEMORY );
       ...
See also:
FileInput_ctor.

void FileInput_dtor ( struct FileInput * ptr_file_input,
int memory_flag )
 

Destructor.

Parameters:
ptr_file_input   A pointer to the initialized FileInput object
memory_flag   Can be FREE_MEMORY or LEAVE_MEMORY. If the memory was allocated for the object by malloc(), use FREE_MEMORY to free it. Use LEAVE_MEMORY If the object was static or allocated in a stack
Returns:
None 
       #include <cybiko.h>
       ...
       {
         char tenth_byte;
         struct FileInput file_input;
         ...
         FileInput_ctor( &file_input );
         ...
         if( FileInput_open( &file_input, "game.save" ) )
         {
           FileInput_seek( &file_input, 10, SEEK_SET );
           tenth_byte = FileInput_read_byte( &file_input );
         }
         ...
         FileInput_dtor( &file_input, LEAVE_MEMORY );
       }
       ...
See also:
FREE_MEMORY, LEAVE_MEMORY

int FileInput_get_flags ( struct FileInput * ptr_file_input )
 

Returns the stream's current state.

Parameters:
ptr_file_input   A pointer to the initialized FileInput object
Returns:
The stream's current state 
       #include <cybiko.h>
       ...
       {
         char tenth_byte;
         long size;
         long sum = 0;
         long index = 0;
         struct FileInput file_input;
         ...
         FileInput_ctor( &file_input );
         ...
         if( FileInput_open( &file_input, "values.txt" ) )
         {
           while( ! ( FileInput_get_flags( &file_input ) & FLAG_EOF ) )
           {
             sum += (long)FileInput_read_byte( &file_input );
             index ++;
           }
         }
         ...
         FileInput_dtor( &file_input, LEAVE_MEMORY );
       }
       ...
See also:
Flags

long FileInput_get_size ( struct FileInput * ptr_file_input )
 

Returns the stream size (if applicable).

Parameters:
ptr_file_input   A pointer to the initialized FileInput object
Returns:
Stream size, or -1 if this operation can't be done on this stream 
       #include <cybiko.h>
       ...
       {
         char tenth_byte;
         long size;
         long index;
         long sum = 0;
         struct FileInput file_input;
         ...
         FileInput_ctor( &file_input );
         ...
         if( FileInput_open( &file_input, "values.txt" ) )
         {
           size = FileInput_get_size( &file_input);
           for( index = 0; index < size; index++ )
           {
             sum += (long)FileInput_read_byte( &file_input );
           }
         }
         ...
         FileInput_dtor( &file_input, LEAVE_MEMORY );
       }
       ...

bool FileInput_is_bad ( struct FileInput * ptr_file_input )
 

Returns TRUE if the BAD flag is set (stream is bad).

Parameters:
ptr_file_input   A pointer to the initialized FileInput object
Returns:
TRUE if the BAD flag is set (stream is bad) 
       #include <cybiko.h>
       ...
       struct FileInput file_input;
       ...
       FileInput_ctor_Ex( &file_input , "values.txt");
       if ( ! FileInput_is_bad( &file_input ) )
       {
         //  Success.
         ...
       }
       ...
See also:
Flags

bool FileInput_is_eof ( struct FileInput * ptr_file_input )
 

Returns TRUE if the EOF flag is set (stream reached end-of-file).

Parameters:
ptr_file_input   A pointer to the initialized FileInput object
Returns:
TRUE if the EOF flag is set (stream reached end-of-file) 
       #include <cybiko.h>
       ...
       {
         char tenth_byte;
         long size;
         long sum = 0;
         long index = 0;
         struct FileInput file_input;
         ...
         FileInput_ctor( &file_input );
         ...
         if( FileInput_open( &file_input, "values.txt" ) )
         {
           while( ! FileInput_is_eof( &file_input ) )
           {
             sum += (long)FileInput_read_byte( &file_input );
             index ++;
           }
         }
         ...
         FileInput_dtor( &file_input, LEAVE_MEMORY );
       }
       ...

bool FileInput_is_good ( struct FileInput * ptr_file_input )
 

Returns TRUE if the BAD flag is not set (stream is good).

Parameters:
ptr_file_input   A pointer to the initialized FileInput object
Returns:
TRUE if the BAD flag is not set (stream is good). 
       #include <cybiko.h>
       ...
       struct FileInput file_input;
       ...
       FileInput_ctor_Ex( &file_input , "values.txt");
       if( FileInput_is_good( &file_input ) )
       {
         //  Success.
         ...
       }
       ...
See also:
Flags

bool FileInput_open ( struct FileInput * ptr_file_input,
char * sz_file_name )
 

Opens an input stream for the file with the specified name.

Parameters:
ptr_file_input   A pointer to the initialized FileInput object
sz_file_name   Name of the file to open
Returns:
TRUE if the stream was opened successfully 
       #include <cybiko.h>
       ...
       {
         char tenth_byte;
         struct FileInput file_input;
         ...
         FileInput_ctor( &file_input );
         ...
         if( FileInput_open( &file_input, "game.save" ) )
         {
           FileInput_seek( &file_input, 10, SEEK_SET );
           tenth_byte = FileInput_read_byte( &file_input );
         }
         ...
         FileInput_dtor( &file_input, LEAVE_MEMORY );
       }
       ...

long FileInput_read ( struct FileInput * ptr_file_input,
void * ptr_buffer,
long length )
 

Reads a specified number of bytes from the stream.

Parameters:
ptr_file_input   A pointer to the initialized FileInput object
ptr_buffer   A pointer to the allocated buffer
length   The number of bytes to read
Returns:
The exact number of bytes read, or 0 if no bytes were read 
       #include <cybiko.h>
       ...
       struct FileInput file_input;
       struct score_t high_scores[10];
       ...
       FileInput_ctor( &file_input );
       if( FileInput_open( &file_input, "game.save" ) )
       ...
       Input_read( &file_input, high_scores, sizeof(high_scores) );
       ...
       Input_dtor( &file_input, LEAVE_MEMORY );
       ...
See also:
FileInput_read_byte.

int FileInput_read_byte ( struct FileInput * ptr_file_input )
 

Reads the next byte from the stream.

Parameters:
ptr_file_input   A pointer to the initialized FileInput object
Returns:
The next byte from the stream 
       #include <cybiko.h>
       ...
       {
         char tenth_byte;
         struct FileInput file_input;
         ...
         FileInput_ctor( &file_input );
         ...
         if( FileInput_open( &file_input, "game.save" ) )
         {
           FileInput_seek( &file_input, 10, SEEK_SET );
           tenth_byte = FileInput_read_byte( &file_input );
         }
         ...
         FileInput_dtor( &file_input, LEAVE_MEMORY );
       }
       ...
See also:
FileInput_read.

long FileInput_seek ( struct FileInput * ptr_file_input,
long pos,
seek_t mode )
 

Seeks to the specified position, then returns the sought position.
If the stream supports a seek operation, it seeks to the specified position in the specified mode. If the requested seek operation can not be done (not supported or wrong parameters), -1 will be returned. Seeking prior to the beginning of the stream sets the pointer to the stream's first byte. Seeking after the end of the stream sets the pointer to the end of stream just after the stream's last byte.

Parameters:
ptr_file_input   A pointer to the initialized FileInput object
pos   The seek offset
mode   The seek mode
Returns:
The new position, or -1 if an error occurred 
       #include <cybiko.h>
       ...
       {
         char tenth_byte;
         struct FileInput file_input;
         ...
         FileInput_ctor( &file_input );
         ...
         if( FileInput_open( &file_input, "game.save" ) )
         {
           FileInput_seek( &file_input, 10, SEEK_SET );
           tenth_byte = FileInput_read_byte( &file_input );
         }
         ...
         FileInput_dtor( &file_input, LEAVE_MEMORY );
       }
       ...
See also:
SEEK_SET, SEEK_CUR, SEEK_END.

long FileInput_seekg ( struct FileInput * ptr_file_input,
long pos,
seek_t mode )
 

Seeks an input stream.

Parameters:
ptr_file_input   A pointer to the initialized FileInput object
pos   The seek offset
mode   The seek mode
Returns:
The new position, or -1 if an error occurred 
       #include <cybiko.h>
       ...
       {
         char tenth_byte;
         struct FileInput file_input;
         ...
         FileInput_ctor( &file_input );
         ...
         if( FileInput_open( &file_input, "game.save" ) )
         {
           FileInput_seekg( &file_input, 10, SEEK_SET );
           tenth_byte = FileInput_read_byte( &file_input );
         }
         ...
         FileInput_dtor( &file_input, LEAVE_MEMORY );
       }
       ...
See also:
SEEK_SET, SEEK_CUR, SEEK_END.

long FileInput_tell ( struct FileInput * ptr_file_input )
 

Returns the stream's current position.

Parameters:
ptr_file_input   A pointer to the initialized FileInput object
Returns:
The stream's position, or -1 if that operation is not supported for this stream 
       #include <cybiko.h>
       ...
       char tenth_byte;
       struct FileInput file_input;
       long cur_pos;
       ...
       FileInput_ctor_Ex( &file_input, "game.save");
       ...
       FileInput_seek( &file_input, 10, SEEK_SET );
       tenth_byte = FileInput_read_byte( &file_input );
       // cur_pos will be equal to 11.
       cur_pos = FileInput_tell( &file_input );
       ...
       FileInput_dtor( &file_input, LEAVE_MEMORY );
       ...

long FileInput_tellg ( struct FileInput * ptr_file_input )
 

Returns the stream's position.

Parameters:
ptr_file_input   A pointer to the initialized FileInput object
Returns:
The stream's position 
       #include <cybiko.h>
       ...
       {
         char tenth_byte;
         long current_pos;
         struct FileInput file_input;
         ...
         FileInput_ctor( &file_input );
         ...
         if( FileInput_open( &file_input, "game.save" ) )
         {
           FileInput_seekg( &file_input, 10, SEEK_SET );
           tenth_byte = FileInput_read_byte( &file_input );
         }
         //  The current_pos value will be equal to 11.
         current_pos = FileInput_tellg( &file_input );
         ...
         FileInput_dtor( &file_input, LEAVE_MEMORY );
       }
       ...