Input Struct Reference

Inheritance diagram for Input

Inheritance graph


Public Methods

long Input_seekg (struct Input *ptr_input, long pos, seek_t mode)
long Input_tellg (struct Input *ptr_input)
long Input_read (struct Input *ptr_input, void *buffer, long length)
int Input_read_byte (struct Input *ptr_input)
int Input_get_flags (struct Input *ptr_input)
bool Input_is_eof (struct Input *ptr_input)
bool Input_is_bad (struct Input *ptr_input)
bool Input_is_good (struct Input *ptr_input)
long Input_get_size (struct Input *ptr_input)
void Input_dtor (struct Input *ptr_input, int)
short Input_read_word (struct Input *ptr_input)
long Input_read_dword (struct Input *ptr_input)

Detailed Description

The CyOS stream modes have 2 basic streams that are abstractions for the sequential data access objects: Input and Output. Those streams can pump data to and from virtually any source, including disk files, network connections, console terminals and more. Those basic streams are used, in turn, with filter streams that apply specific features to some abstract streams' filters.

Typical stream implementations include the file streams FileInput and FileOutput, console streams, and various filters. Filter streams process the data from other streams.

They take the other streams' objects while constructing, and are just like regular streams themselves. Typical filters are UNICODE/ASCII conversion, text formatting streams Reader and Writer, and compression streams Compressor and Decompressor.

Filters are intended to combine the desired stream implementation with the selected filter object, to combine the features that best suit your needs. This object is just an interface for an input stream.

See also:
File I/O

Member Function Documentation

void Input_dtor ( struct Input * ptr_input,
int memory_flag )
 

Destructor.

Parameters:
ptr_input   A pointer to the initialized Input 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 <cywin.h>
       ...
       char tenth_byte;
       struct Input* ptr_input;
       ...
       ptr_input = open_resource_Ex( "data.txt" );
       ...
       Input_seekg( ptr_input, 10, SEEK_SET );
       tenth_byte = Input_read_byte( ptr_input );
       ...
       Input_dtor( ptr_input, FREE_MEMORY );
       ...
See also:
FREE_MEMORY, LEAVE_MEMORY.

int Input_get_flags ( struct Input * ptr_input )
 

Returns the current flags.

Parameters:
ptr_input   A pointer to the initialized Input object
Returns:
The current flags 
       #include <cywin.h>
       ...
       long sum = 0;
       struct Input* ptr_input;
       ...
       ptr_input = open_resource_Ex( "values.txt" );
       ...
       while( ! ( Input_get_flags(ptr_input) & FLAG_EOF ) )
       {
         sum += (long)Input_read_byte( ptr_input );
       }
       ...
       Input_dtor( ptr_input, FREE_MEMORY );
       ...

long Input_get_size ( struct Input * ptr_input )
 

Returns the stream size (if applicable).

Parameters:
ptr_input   A pointer to the initialized Input object
Returns:
Stream size, or -1 if the operation can't be done on this stream 
       #include <cywin.h>
       ...
       long size;
       long index;
       long sum = 0;
       struct Input* ptr_input;
       ...
       ptr_input = open_resource_Ex( "values.txt" );
       ...
       size = Input_get_size( ptr_input );
       for( index = 0; index < size; index++ )
       {
         sum += (long)Input_read_byte( ptr_input );
       }
       ...
       Input_dtor( ptr_input, FREE_MEMORY );
       ...

bool Input_is_bad ( struct Input * ptr_input )
 

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

Parameters:
ptr_input   A pointer to the initialized Input object
Returns:
TRUE if the BAD flag is set (stream is bad) 
       #include <cywin.h>
          ...
          long sum = 0;
          struct Input* ptr_input;
          ...
          ptr_input = open_resource_Ex( "values.txt" );
          if (!Input_is_bad(ptr_input))
          {
             //success
          }
           ...
          Input_dtor( ptr_input, FREE_MEMORY );
See also:
Input_is_good, Input_is_eof.

bool Input_is_eof ( struct Input * ptr_input )
 

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

Parameters:
ptr_input   A pointer to the initialized Input object
Returns:
TRUE if the EOF flag is set (stream reached end-of-file) 
       #include <cywin.h>
          ...
          long sum = 0;
          struct Input* ptr_input;
          ...
          ptr_input = open_resource_Ex( "values.txt" );
          ...
          while( ! ( Input_is_eof(ptr_input) )
          {
            sum += (long)Input_read_byte( ptr_input );
          }
          ...
          Input_dtor( ptr_input, FREE_MEMORY );
Stream size, or -1 if the operation can't be done on this stream.
See also:
Input_is_bad, Input_is_good.

bool Input_is_good ( struct Input * ptr_input )
 

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

Parameters:
ptr_input   A pointer to the initialized Input object
Returns:
TRUE if the BAD flag is not set (stream is good) 
       #include <cywin.h>
          ...
          long sum = 0;
          struct Input* ptr_input;
          ...
          ptr_input = open_resource_Ex( "values.txt" );
          if (Input_is_good (ptr_input))
          {
             //success
          }
           ...
          Input_dtor( ptr_input, FREE_MEMORY );
See also:
Input_is_bad, Input_is_eof.

long Input_read ( struct Input * ptr_input,
void * buffer,
long length )
 

Reads the 'length' bytes from the stream.

Parameters:
ptr_input   A pointer to the initialized Input object
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 <cywin.h>
       #include "score.h"
       ...
       struct Input* ptr_input;
       struct score_t high_scores[10];
       ...
       ptr_input = open_resource_Ex( "score.inf" );
       ...
       Input_read( ptr_input, high_scores, sizeof(high_scores) );
       ...
       Input_dtor( ptr_input, FREE_MEMORY );
       ...
See also:
Input_read_byte.

int Input_read_byte ( struct Input * ptr_input )
 

Reads the next byte from the stream.

Parameters:
ptr_input   A pointer to the initialized Input object
Returns:
The next byte from the stream 
       #include <cywin.h>
       ...
       char tenth_byte;
       struct Input* ptr_input;
       ...
       ptr_input = open_resource_Ex( "data.txt" );
       ...
       Input_seekg( ptr_input, 10, SEEK_SET );
       tenth_byte = Input_read_byte( ptr_input );
       ...
       Input_dtor( ptr_input, FREE_MEMORY );
       ...
See also:
Input_read.

long Input_read_dword ( struct Input * ptr_input )
 

Reads a 32-bit word, independent of hardware.

Parameters:
ptr_input   A pointer to the initialized Input object
Returns:
The next 4 bytes from the stream 
       #include <cywin.h>
       ...
       long size;
       long index;
       long sum = 0;
       struct Input* ptr_input;
       ...
       ptr_input = open_resource_Ex( "values.txt" );
       ...
       size = Input_get_size( ptr_input )/(sizeof (long));
       for( index = 0; index < size; index++ )
       {
         sum += (long)Input_read_dword( ptr_input );
       }
       ...
       Input_dtor( ptr_input, FREE_MEMORY );
       ...
See also:
Input_read_word.

short Input_read_word ( struct Input * ptr_input )
 

Reads a 16-bit word, independent of hardware.

Parameters:
ptr_input   A pointer to the initialized Input object
Returns:
The next 2 bytes from the stream 
       #include <cywin.h>
       ...
       long size;
       long index;
       long sum = 0;
       struct Input* ptr_input;
       ...
       ptr_input = open_resource_Ex( "values.txt" );
       ...
       size = Input_get_size( ptr_input )/(sizeof (int));
       for( index = 0; index < size; index++ )
       {
         sum += (long)Input_read_word( ptr_input );
       }
       ...
       Input_dtor( ptr_input, FREE_MEMORY );
       ...
See also:
Input_read_dword.

long Input_seekg ( struct Input * ptr_input,
long pos,
seek_t mode )
 

Seeks an input stream.
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 (after the stream's last byte).

Parameters:
ptr_input   A pointer to the initialized Input object
pos   The seek offset
mode   The seek mode
Returns:
The new position or -1 if an error occurred 
       #include <cywin.h>
       ...
       char tenth_byte;
       struct Input* ptr_input;
       ...
       ptr_input = open_resource_Ex( "data.txt" );
       ...
       Input_seekg( ptr_input, 10, SEEK_SET );
       tenth_byte = Input_read_byte( ptr_input );
       ...
       Input_dtor( ptr_input, FREE_MEMORY );
       ...

long Input_tellg ( struct Input * ptr_input )
 

Returns the stream's position.

Parameters:
ptr_input   A pointer to the initialized Input object
Returns:
The stream's position, or -1 of that operation is not supported for this stream 
       #include <cywin.h>
       ...
       char tenth_byte;
       long current_pos;
       struct Input* ptr_input;
       ...
       ptr_input = open_resource_Ex( "data.txt" );
       ...
       Input_seekg( ptr_input, 10, SEEK_SET );
       tenth_byte = Input_read_byte( ptr_input );
       // The current_pos value will be equal to 11.
       current_pos = Input_tellg( ptr_input );
       ...
       Input_dtor( ptr_input, FREE_MEMORY );
       ...