FileOutput Struct Reference

Inheritance diagram for FileOutput

Inheritance graph

Collaboration diagram for FileOutput:

Collaboration graph


Public Methods

struct FileOutput* FileOutput_ctor (struct FileOutput *ptr_file_output)
struct FileOutput* FileOutput_ctor_Ex (struct FileOutput *ptr_file_output, char *sz_file_name, bool create)
bool FileOutput_open (struct FileOutput *ptr_file_output, char *sz_file_name, bool create)
long FileOutput_seek (struct FileOutput *ptr_file_output, long pos, seek_t mode)
long FileOutput_tell (struct FileOutput *ptr_file_output)
bool FileOutput_truncate (struct FileOutput *ptr_file_output, long position)
void FileOutput_dtor (struct FileOutput *ptr_file_output, int memory_flag)
long FileOutput_write (struct FileOutput *ptr_file_output, void *ptr_buffer, long length)
int FileOutput_write_byte (struct FileOutput *ptr_file_output, int fbyte)
long FileOutput_seekp (struct FileOutput *ptr_file_output, long pos, seek_t mode)
long FileOutput_tellp (struct FileOutput *ptr_file_output)
long FileOutput_get_size (struct FileOutput *ptr_file_output)
int FileOutput_get_flags (struct FileOutput *ptr_file_output)
bool FileOutput_is_eof (struct FileOutput *ptr_file_output)
bool FileOutput_is_bad (struct FileOutput *ptr_file_output)
bool FileOutput_is_good (struct FileOutput *ptr_file_output)

Detailed Description

Implements basic file output operations.

See also:
File I/O

Member Function Documentation

struct FileOutput * FileOutput_ctor ( struct FileOutput * ptr_file_output )
 

Creates an empty output file stream object.

Parameters:
ptr_file_output   A pointer to the FileInput structure
Returns:
A pointer to the initialized FileOutput object 
       #include <cybiko.h>
       ...
       {
         char tenth_byte = 100;
         struct FileOutput file_output;
         ...
         FileOutput_ctor( &file_output );
         ...
         if( FileOutput_open( &file_output, "game.save", TRUE ) )
         {
           FileOutput_seek( &file_output, 10, SEEK_SET );
           FileOutput_write_byte( &file_output, tenth_byte);
         }
         ...
         FileOutput_dtor( &file_output, LEAVE_MEMORY );
       }
       ...

struct FileOutput * FileOutput_ctor_Ex ( struct FileOutput * ptr_file_output,
char * sz_file_name,
bool create )
 

Creates an output file stream object for the file with the specified name.

Parameters:
ptr_file_output   A pointer to the FileInput structure
sz_file_name   The file's name
create   Specifies whether or not to create a new file if the specified file does not exist
Returns:
A pointer to the initialized FileOutput object 
       #include <cybiko.h>
       ...
       char tenth_byte = 100;
       struct FileOutput file_output;
       ...
       FileOutput_ctor_Ex( &file_output, "game.save" , TRUE);
       ...
       FileOutput_seek( &file_output, 10, SEEK_SET );
       FileOutput_write_byte( &file_output, tenth_byte);
       ...
       FileOutput_dtor( &file_output, LEAVE_MEMORY );
       ...

void FileOutput_dtor ( struct FileOutput * ptr_file_output,
int memory_flag )
 

Destructor.

Parameters:
ptr_file_output   A pointer to the initialized FileOutput 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 = 100;
       struct FileOutput file_output;
       ...
       FileOutput_ctor_Ex( &file_output, "game.save" , TRUE);
       ...
       FileOutput_seek( &file_output, 10, SEEK_SET );
       FileOutput_write_byte( &file_output, tenth_byte);
       ...
       FileOutput_dtor( &file_output, LEAVE_MEMORY );
       ...
See also:
FREE_MEMORY, LEAVE_MEMORY.

int FileOutput_get_flags ( struct FileOutput * ptr_file_output )
 

Returns the stream's current state.

Parameters:
ptr_file_output   A pointer to the initialized FileOutput object
Returns:
The stream's current state 
       #include <cybiko.h>
       ...
       char obtain_new_value();
       ...
       {
         struct FileOutput file_output;
         char current_value;
         long size;
         ...
         FileOutput_ctor_Ex( &file_output, "game.save" );
         ...
         while( !( FileOutput_get_flags( &file_output ) & FLAG_EOF ) )
         {
           current_value = obtain_new_value();
           FileOutput_write_byte(& file_output, current_value );
         }
         ...
         FileOutput_dtor( &file_output, LEAVE_MEMORY );
       }
       ...
See also:
Flags

long FileOutput_get_size ( struct FileOutput * ptr_file_output )
 

Returns the stream size (if applicable).

Parameters:
ptr_file_output   A pointer to the initialized FileOutput object
Returns:
The stream size (if applicable) 
       #include <cybiko.h>
       ...
       char obtain_new_value();
       ...
       {
         struct FileOutput file_output;
         char current_value;
         long size;
         ...
         FileOutput_ctor_Ex( &file_output, "game.save" );
         ...
         size = Output_get_size( &file_output );
         for( index = 0; index < size; index++ )
         {    
           current_value = obtain_new_value();
           FileOutput_write_byte( &file_output, current_value );
         }
         cur_pos = FileOutput_tellp(&file_output);
         ...
         FileOutput_dtor( &file_output, LEAVE_MEMORY );
       }
       ...

bool FileOutput_is_bad ( struct FileOutput * ptr_file_output )
 

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

Parameters:
ptr_file_output   A pointer to the initialized FileOutput object
Returns:
TRUE if the BAD flag is set (stream is bad) 
       #include <cybiko.h>
       ...
       struct FileOutput file_output;
       ...
       FileOutput_ctor_Ex( &file_output, "game.save" );
       if( ! FileOutput_is_bad( &file_output ) )
       {
          //  Success.
       }
       ...
       FileOutput_dtor( &file_output, LEAVE_MEMORY );
       ...
See also:
Flags

bool FileOutput_is_eof ( struct FileOutput * ptr_file_output )
 

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

Parameters:
ptr_file_output   A pointer to the initialized FileOutput object
Returns:
TRUE if the EOF flag is set (stream reached end-of-file) 
       #include <cybiko.h>
       ...
       char obtain_new_value();
       ...
       {
         struct FileOutput file_output;
         char current_value;
         long size;
         ...
         FileOutput_ctor_Ex( &file_output, "game.save" );
         ...
         while( !( FileOutput_is_eof( &file_output ) ) )
         {
           current_value = obtain_new_value();
           FileOutput_write_byte( &file_output, current_value );
         }
         ...
         FileOutput_dtor( &file_output, LEAVE_MEMORY );
       }
       ...
See also:
Flags

bool FileOutput_is_good ( struct FileOutput * ptr_file_output )
 

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

Parameters:
ptr_file_output   A pointer to the initialized FileOutput object
Returns:
TRUE if the BAD flag is not set (stream is good) 
       #include <cybiko.h>
       ...
       struct FileOutput file_output;
       ...
       FileOutput_ctor_Ex( &file_output, "game.save" );
       if( FileOutput_is_good( &file_output ) )
       {
         //  Success.
       }
       ...
       FileOutput_dtor( &file_output, LEAVE_MEMORY );
       ...
See also:
Flags

bool FileOutput_open ( struct FileOutput * ptr_file_output,
char * sz_file_name,
bool create )
 

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

Parameters:
ptr_file_output   A pointer to the initialized FileOutput object
sz_file_name   The name of the file
create   Specifies whether or not to create a new file if the specified file does not exist
Returns:
TRUE if the function succeeded 
       #include <cybiko.h>
       ...
       {
         char tenth_byte = 100;
         struct FileOutput file_output;
         ...
         FileOutput_ctor( &file_output );
         ...
         if( FileOutput_open( &file_output, "game.save", TRUE ) )
         {
           FileOutput_seek( &file_output, 10, SEEK_SET );
           FileOutput_write_byte( &file_output, tenth_byte);
         }
         ...
         FileOutput_dtor( &file_output, LEAVE_MEMORY );
       }
       ...

long FileOutput_seek ( struct FileOutput * ptr_file_output,
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 cannot 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 the stream; then the stream will be extended with garbage bytes to the specified size.

Parameters:
ptr_file_output   A pointer to the initialized FileOutput 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 = 100;
         struct FileOutput file_output;
         ...
         FileOutput_ctor( &file_output );
         ...
         if( FileOutput_open( &file_output, "game.save", TRUE ) )
         {
           FileOutput_seek( &file_output, 10, SEEK_SET );
           FileOutput_write_byte( &file_output, tenth_byte);
         }
         ...
         FileOutput_dtor( &file_output, LEAVE_MEMORY );
       }
       ...
See also:
SEEK_SET, SEEK_CUR, SEEK_END.

long FileOutput_seekp ( struct FileOutput * ptr_file_output,
long pos,
seek_t mode )
 

Seeks an output stream.

Parameters:
ptr_file_output   A pointer to the initialized FileOutput 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 = 100;
       struct FileOutput file_output;
       ...
       FileOutput_ctor_Ex( &file_output, "game.save" );
       ...
       FileOutput_seekp( &file_output, 10, SEEK_SET );
       FileOutput_write_byte( &file_output, tenth_byte);
       ...
       FileOutput_dtor( &file_output, LEAVE_MEMORY );
       ...
See also:
SEEK_SET, SEEK_CUR, SEEK_END.

long FileOutput_tell ( struct FileOutput * ptr_file_output )
 

Returns the stream's position.

Parameters:
ptr_file_output   A pointer to the initialized FileOutput object.
Returns:
The stream's position, or -1 if the operation is not supported for this stream. 
       #include <cybiko.h>
       ...
       char tenth_byte = 100;
       struct FileOutput file_output;
       long cur_pos;
       ...
       FileOutput_ctor_Ex( &file_output, "game.save", TRUE );
       ...
       FileOutput_seek( &file_output, 10, SEEK_SET );
       FileOutput_write_byte( &file_output, tenth_byte);
       // cur_pos will be equal to 11.
       cur_pos = FileOutput_tell( &file_output );
       ...
       FileOutput_dtor( &file_output, LEAVE_MEMORY );
       ...
See also:
SEEK_SET, SEEK_CUR, SEEK_END.

long FileOutput_tellp ( struct FileOutput * ptr_file_output )
 

Returns the stream's position.

Parameters:
ptr_file_output   A pointer to the initialized FileOutput object
Returns:
The stream position, or -1 if the operation is not supported for this stream 
       #include <cybiko.h>
       ...
       char tenth_byte = 100;
       long cur_pos;
       struct FileOutput file_output;
       ...
       FileOutput_ctor_Ex( &file_output, "game.save" );
       ...
       FileOutput_seekp( &file_output, 10, SEEK_SET );
       FileOutput_write_byte( &file_output, tenth_byte);
       //  cur_pos will be equal to 11.
       cur_pos = FileOutput_tellp( &file_output );
       ...
       FileOutput_dtor( &file_output, LEAVE_MEMORY );
       ...
See also:
SEEK_SET, SEEK_CUR, SEEK_END.

bool FileOutput_truncate ( struct FileOutput * ptr_file_output,
long position )
 

Truncates a file associated with the stream.
Thread right access sensitive!

Parameters:
ptr_file_output   A pointer to the initialized FileOutput object
position   The truncation position
Returns:
TRUE if the function succeeded 
       #include <cybiko.h>
       ...
       struct FileOutput file_output;
       ...
       FileOutput_ctor_Ex( &file_output, "game.save", TRUE );
       ...
       FileOutput_seek( &file_output, 10, SEEK_SET );
       // The file size is 11 bytes now.
       FileOutput_truncate( &file_output , 10 );
       ...
       FileOutput_dtor( &file_output, LEAVE_MEMORY );
       ...

long FileOutput_write ( struct FileOutput * ptr_file_output,
void * ptr_buffer,
long length )
 

Writes the specified number of bytes to the stream.

Parameters:
ptr_file_output   A pointer to the initialized FileOutput object
ptr_buffer   The buffer with the data to write
length   The number of bytes to write
Returns:
The exact number of bytes written, or 0 if no bytes were written 
       #include <cybiko.h>
       ...
       struct score_t high_scores[10];
       struct FileOutput file_output;
       ...
       FileOutput_ctor_Ex( &file_output, "game.save", TRUE );
       ...
       FileOutput_write(&file_output, high_scores, sizeof( high_scores ));
       ....
       FileOutput_dtor( &file_output, LEAVE_MEMORY );
       ...

int FileOutput_write_byte ( struct FileOutput * ptr_file_output,
int fbyte )
 

Writes a byte to the stream.

Parameters:
ptr_file_output   A pointer to the initialized FileOutput object
fbyte   The byte to write
Returns:
-1 in the case of failure, otherwise the value of the byte written 
       #include <cybiko.h>
       ...
       char tenth_byte = 100;
       struct FileOutput file_output;
       ...
       FileOutput_ctor( &file_output );
       ...
       if( FileOutput_open( &file_output, "game.save", TRUE ) )
       {
         FileOutput_seek( &file_output, 10, SEEK_SET );
         FileOutput_write_byte( &file_output, tenth_byte);
       }
       ...
       FileOutput_dtor( &file_output, LEAVE_MEMORY );
       ...