cr-input

## cr-input cr-input |

## Synopsis

    struct              CRInput;
    struct              CRInputPos;
                        CRInputPriv;
    enum CRStatus       cr_input_consume_char               (CRInput *a_this,
                                                             guint32 a_char);
    enum CRStatus       cr_input_consume_chars              (CRInput *a_this,
                                                             guint32 a_char,
                                                             gulong *a_nb_char);
    enum CRStatus       cr_input_consume_white_spaces       (CRInput *a_this,
                                                             gulong *a_nb_chars);
    void                cr_input_destroy                    (CRInput *a_this);
    enum CRStatus       cr_input_end_of_input               (CRInput const *a_this,
                                                             gboolean *a_end_of_input);
    guchar *            cr_input_get_byte_addr              (CRInput *a_this,
                                                             gulong a_offset);
    enum CRStatus       cr_input_get_column_num             (CRInput const *a_this,
                                                             glong *a_col);
    enum CRStatus       cr_input_get_cur_byte_addr          (CRInput *a_this,
                                                             guchar **a_offset);
    enum CRStatus       cr_input_get_cur_index              (CRInput const *a_this,
                                                             glong *a_index);
    enum CRStatus       cr_input_get_cur_pos                (CRInput const *a_this,
                                                             CRInputPos *a_pos);
    enum CRStatus       cr_input_get_end_of_file            (CRInput const *a_this,
                                                             gboolean *a_eof);
    enum CRStatus       cr_input_get_end_of_line            (CRInput const *a_this,
                                                             gboolean *a_eol);
    enum CRStatus       cr_input_get_line_num               (CRInput const *a_this,
                                                             glong *a_line_num);
    glong               cr_input_get_nb_bytes_left          (CRInput const *a_this);
    enum CRStatus       cr_input_get_parsing_location       (CRInput const *a_this,
                                                             CRParsingLocation *a_loc);
    enum CRStatus       cr_input_increment_col_num          (CRInput *a_this,
                                                             glong a_increment);
    enum CRStatus       cr_input_increment_line_num         (CRInput *a_this,
                                                             glong a_increment);
    CRInput *           cr_input_new_from_buf               (guchar *a_buf,
                                                             gulong a_len,
                                                             enum CREncoding a_enc,
                                                             gboolean a_free_buf);
    CRInput *           cr_input_new_from_uri               (const gchar *a_file_uri,
                                                             enum CREncoding a_enc);
    enum CRStatus       cr_input_peek_byte                  (CRInput const *a_this,
                                                             enum CRSeekPos a_origin,
                                                             gulong a_offset,
                                                             guchar *a_byte);
    guchar              cr_input_peek_byte2                 (CRInput const *a_this,
                                                             gulong a_offset,
                                                             gboolean *a_eof);
    enum CRStatus       cr_input_peek_char                  (CRInput const *a_this,
                                                             guint32 *a_char);
    enum CRStatus       cr_input_read_byte                  (CRInput *a_this,
                                                             guchar *a_byte);
    enum CRStatus       cr_input_read_char                  (CRInput *a_this,
                                                             guint32 *a_char);
    void                cr_input_ref                        (CRInput *a_this);
    enum CRStatus       cr_input_seek_index                 (CRInput *a_this,
                                                             enum CRSeekPos a_origin,
                                                             gint a_pos);
    enum CRStatus       cr_input_set_column_num             (CRInput *a_this,
                                                             glong a_col);
    enum CRStatus       cr_input_set_cur_index              (CRInput *a_this,
                                                             glong a_index);
    enum CRStatus       cr_input_set_cur_pos                (CRInput *a_this,
                                                             CRInputPos const *a_pos);
    enum CRStatus       cr_input_set_end_of_file            (CRInput *a_this,
                                                             gboolean a_eof);
    enum CRStatus       cr_input_set_end_of_line            (CRInput *a_this,
                                                             gboolean a_eol);
    enum CRStatus       cr_input_set_line_num               (CRInput *a_this,
                                                             glong a_line_num);
    gboolean            cr_input_unref                      (CRInput *a_this);

## Description

## Details

### struct CRInput

    struct CRInput {
            CRInputPriv *priv ;
    };

### struct CRInputPos

    struct CRInputPos {
            glong line ;
            glong col ;
            gboolean end_of_file ;
            gboolean end_of_line ;
            glong next_byte_index ;
    };

### CRInputPriv

    typedef struct _CRInputPriv CRInputPriv;

### cr_input_consume_char ()

    enum CRStatus       cr_input_consume_char               (CRInput *a_this,
                                                             guint32 a_char);

Consumes the next character of the input stream if and only if that character equals a_char.

`a_this` : | the this pointer.
`a_char` : | the character to consume. If set to zero, consumes any character.
Returns : | CR_OK upon successful completion, CR_PARSING_ERROR if next char is different from a_char, an other error code otherwise

### cr_input_consume_chars ()

    enum CRStatus       cr_input_consume_chars              (CRInput *a_this,
                                                             guint32 a_char,
                                                             gulong *a_nb_char);

Consumes up to a_nb_char occurences of the next contiguous characters which equal a_char. Note that the next character of the input stream *MUST* equal a_char to trigger the consumption, or else, the error code CR_PARSING_ERROR is returned. If the number of contiguous characters that equals a_char is less than a_nb_char, then this function consumes all the characters it can consume.

`a_this` : | the this pointer of the current instance of CRInput.
`a_char` : | the character to consume.
`a_nb_char` : | in/out parameter. The number of characters to consume. If set to a negative value, the function will consume all the occurences of a_char found. After return, if the return value equals CR_OK, this variable contains the number of characters actually consumed.
Returns : | CR_OK if at least one character has been consumed, an error code otherwise.

### cr_input_consume_white_spaces ()

    enum CRStatus       cr_input_consume_white_spaces       (CRInput *a_this,
                                                             gulong *a_nb_chars);

Same as `cr_input_consume_chars()` but this one consumes white spaces.

`a_this` : | the "this pointer" of the current instance of CRInput.
`a_nb_chars` : | in/out parameter. The number of white spaces to consume. After return, holds the number of white spaces actually consumed.
Returns : | CR_OK upon successful completion, an error code otherwise.

### cr_input_destroy ()

    void                cr_input_destroy                    (CRInput *a_this);

The destructor of the CRInput class.

`a_this` : | the current instance of CRInput.

### cr_input_end_of_input ()

    enum CRStatus       cr_input_end_of_input               (CRInput const *a_this,
                                                             gboolean *a_end_of_input);

Tests wether the current instance of CRInput has reached its input buffer.

`a_this` : | the current instance of CRInput.
`a_end_of_input` : | out parameter. Is set to TRUE if the current instance has reached the end of its input buffer, FALSE otherwise.
Returns : | CR_OK upon successful completion, an error code otherwise. Note that all the out parameters of this method are valid if and only if this method returns CR_OK.

### cr_input_get_byte_addr ()

    guchar *            cr_input_get_byte_addr              (CRInput *a_this,
                                                             gulong a_offset);

Gets the memory address of the byte located at a given offset in the input stream.

`a_this` : | the current instance of CRInput.
`a_offset` : | the offset of the byte in the input stream starting from the beginning of the stream.
Returns : | the address, otherwise NULL if an error occured.

### cr_input_get_column_num ()

    enum CRStatus       cr_input_get_column_num             (CRInput const *a_this,
                                                             glong *a_col);

Getter of the current column number.

`a_this` : | the "this pointer" of the current instance of CRInput.
`a_col` : | out parameter
Returns : | CR_OK upon successful completion, an error code otherwise.

### cr_input_get_cur_byte_addr ()

    enum CRStatus       cr_input_get_cur_byte_addr          (CRInput *a_this,
                                                             guchar **a_offset);

Gets the address of the current character pointer.

`a_this` : | the current input stream
`a_offset` : | out parameter. The returned address.
Returns : | CR_OK upon successful completion, an error code otherwise.

### cr_input_get_cur_index ()

    enum CRStatus       cr_input_get_cur_index              (CRInput const *a_this,
                                                             glong *a_index);

Getter of the next byte index. It actually returns the index of the next byte to be read.

`a_this` : | the "this pointer" of the current instance of CRInput
`a_index` : | out parameter. The returned index.
Returns : | CR_OK upon successful completion, an error code otherwise.

### cr_input_get_cur_pos ()

    enum CRStatus       cr_input_get_cur_pos                (CRInput const *a_this,
                                                             CRInputPos *a_pos);

Gets the position of the "current byte index" which is basically the position of the last returned byte in the input stream.

`a_this` : | the current instance of CRInput.
`a_pos` : | out parameter. The returned position.
Returns : | CR_OK upon successful completion. Otherwise, CR_BAD_PARAMETER_ERROR if at least one of the arguments is invalid. CR_START_OF_INPUT if no call to either `cr_input_read_byte()` or `cr_input_seek_index()` have been issued before calling `cr_input_get_cur_pos()` Note that the out parameters of this function are valid if and only if this function returns CR_OK.

### cr_input_get_end_of_file ()

    enum CRStatus       cr_input_get_end_of_file            (CRInput const *a_this,
                                                             gboolean *a_eof);

Gets the end of file flag.

`a_this` : | the current instance of CRInput.
`a_eof` : | out parameter the place to put the end of file flag.
Returns : | CR_OK upon successful completion, an error code otherwise.

### cr_input_get_end_of_line ()

    enum CRStatus       cr_input_get_end_of_line            (CRInput const *a_this,
                                                             gboolean *a_eol);

Gets the end of line flag of the current input.

`a_this` : | the current instance of CRInput
`a_eol` : | out parameter. The place to put the returned flag
Returns : | CR_OK upon successful completion, an error code otherwise.

### cr_input_get_line_num ()

    enum CRStatus       cr_input_get_line_num               (CRInput const *a_this,
                                                             glong *a_line_num);

Getter of the current line number.

`a_this` : | the "this pointer" of the current instance of CRInput.
`a_line_num` : | the returned line number.
Returns : | CR_OK upon successful completion, an error code otherwise.

### cr_input_get_nb_bytes_left ()

    glong               cr_input_get_nb_bytes_left          (CRInput const *a_this);

`a_this` : | the current instance of CRInput.
Returns : | the number of bytes left in the input stream before the end, -1 in case of error.

### cr_input_get_parsing_location ()

    enum CRStatus       cr_input_get_parsing_location       (CRInput const *a_this,
                                                             CRParsingLocation *a_loc);

Gets the current parsing location. The Parsing location is a public datastructure that represents the current line/column/byte offset/ in the input stream.

`a_this` : | the current instance of CRInput
`a_loc` : | the set parsing location.
Returns : | CR_OK upon successful completion, an error code otherwise.

### cr_input_increment_col_num ()

    enum CRStatus       cr_input_increment_col_num          (CRInput *a_this,
                                                             glong a_increment);

Increments the current column number.

`a_this` : | the "this pointer" of the current instance of CRInput.
`a_increment` : | the increment to add to the column number.
Returns : | CR_OK upon successful completion, an error code otherwise.

### cr_input_increment_line_num ()

    enum CRStatus       cr_input_increment_line_num         (CRInput *a_this,
                                                             glong a_increment);

Increments the current line number.

`a_this` : | the "this pointer" of the current instance of CRInput.
`a_increment` : | the increment to add to the line number.
Returns : | CR_OK upon successful completion, an error code otherwise.

### cr_input_new_from_buf ()

    CRInput *           cr_input_new_from_buf               (guchar *a_buf,
                                                             gulong a_len,
                                                             enum CREncoding a_enc,
                                                             gboolean a_free_buf);

Creates a new input stream from a memory buffer.

`a_buf` : | the memory buffer to create the input stream from. The CRInput keeps this pointer so user should not free it !.
`a_len` : | the size of the input buffer.
`a_enc` : | the buffer's encoding.
`a_free_buf` : | if set to TRUE, this a_buf will be freed at the destruction of this instance. If set to false, it is up to the caller to free it.
Returns : | the newly built instance of CRInput.

### cr_input_new_from_uri ()

    CRInput *           cr_input_new_from_uri               (const gchar *a_file_uri,
                                                             enum CREncoding a_enc);

Creates a new input stream from a file.

`a_file_uri` : | the file to create *the input stream from.
`a_enc` : | the encoding of the file *to create the input from.
Returns : | the newly created input stream if this method could read the file and create it, NULL otherwise.

### cr_input_peek_byte ()

    enum CRStatus       cr_input_peek_byte                  (CRInput const *a_this,
                                                             enum CRSeekPos a_origin,
                                                             gulong a_offset,
                                                             guchar *a_byte);

Gets a byte from the input stream, starting from the current position in the input stream. Unlike `cr_input_peek_next_byte()` this method does not update the state of the current input stream. Subsequent calls to cr_input_peek_byte with the same arguments will return the same byte.

`a_this` : | the current instance of CRInput.
`a_origin` : | the origin to consider in the calculation of the position of the byte to peek.
`a_offset` : | the offset of the byte to peek, starting from the origin specified by a_origin.
`a_byte` : | out parameter the peeked byte.
Returns : | CR_OK upon successful completion or, CR_BAD_PARAM_ERROR if at least one of the parameters is invalid; CR_OUT_OF_BOUNDS_ERROR if the indexed byte is out of bounds.

### cr_input_peek_byte2 ()

    guchar              cr_input_peek_byte2                 (CRInput const *a_this,
                                                             gulong a_offset,
                                                             gboolean *a_eof);

Same as `cr_input_peek_byte()` but with a simplified interface.

`a_this` : | the current byte input stream.
`a_offset` : | the offset of the byte to peek, starting from the current input position pointer.
`a_eof` : | out parameter. Is set to true is we reach end of stream. If set to NULL by the caller, this parameter is not taken in account.
Returns : | the read byte or 0 if something bad happened.

### cr_input_peek_char ()

    enum CRStatus       cr_input_peek_char                  (CRInput const *a_this,
                                                             guint32 *a_char);

Same as `cr_input_read_char()` but does not update the internal state of the input stream. The next call to `cr_input_peek_char()` or `cr_input_read_char()` will thus return the same character as the current one.

`a_this` : | the current instance of CRInput.
`a_char` : | out parameter. The returned character.
Returns : | CR_OK upon successful completion, an error code otherwise.

### cr_input_read_byte ()

    enum CRStatus       cr_input_read_byte                  (CRInput *a_this,
                                                             guchar *a_byte);

Gets the next byte of the input. Updates the state of the input so that the next invocation of this method returns the next coming byte.

`a_this` : | the current instance of CRInput.
`a_byte` : | out parameter the returned byte.
Returns : | CR_OK upon successful completion, an error code otherwise. All the out parameters of this method are valid if and only if this method returns CR_OK.

### cr_input_read_char ()

    enum CRStatus       cr_input_read_char                  (CRInput *a_this,
                                                             guint32 *a_char);

Reads an unicode character from the current instance of CRInput.

`a_this` : | the current instance of CRInput.
`a_char` : | out parameter. The read character.
Returns : | CR_OK upon successful completion, an error code otherwise.

### cr_input_ref ()

    void                cr_input_ref                        (CRInput *a_this);

Increments the reference count of the current instance of CRInput.

`a_this` : | the current instance of CRInput.

### cr_input_seek_index ()

    enum CRStatus       cr_input_seek_index                 (CRInput *a_this,
                                                             enum CRSeekPos a_origin,
                                                             gint a_pos);

Sets the "current byte index" of the current instance of CRInput. Next call to `cr_input_get_byte()` will return the byte next after the new "current byte index".

`a_this` : | the current instance of CRInput.
`a_origin` : | the origin to consider during the calculation of the absolute position of the new "current byte index".
`a_pos` : | the relative offset of the new "current byte index." This offset is relative to the origin a_origin.
Returns : | CR_OK upon successful completion otherwise returns CR_BAD_PARAM_ERROR if at least one of the parameters is not valid or CR_OUT_BOUNDS_ERROR in case of error.

### cr_input_set_column_num ()

    enum CRStatus       cr_input_set_column_num             (CRInput *a_this,
                                                             glong a_col);

Setter of the current column number.

`a_this` : | the "this pointer" of the current instance of CRInput.
`a_col` : | the new column number.
Returns : | CR_OK upon successful completion, an error code otherwise.

### cr_input_set_cur_index ()

    enum CRStatus       cr_input_set_cur_index              (CRInput *a_this,
                                                             glong a_index);

Setter of the next byte index. It sets the index of the next byte to be read.

`a_this` : | the "this pointer" of the current instance of CRInput .
`a_index` : | the new index to set.
Returns : | CR_OK upon successful completion, an error code otherwise.

### cr_input_set_cur_pos ()

    enum CRStatus       cr_input_set_cur_pos                (CRInput *a_this,
                                                             CRInputPos const *a_pos);

Sets the current position in the input stream.

`a_this` : | the "this pointer" of the current instance of CRInput.
`a_pos` : | the new position.
Returns : | CR_OK upon successful completion, an error code otherwise.

### cr_input_set_end_of_file ()

    enum CRStatus       cr_input_set_end_of_file            (CRInput *a_this,
                                                             gboolean a_eof);

Sets the end of file flag.

`a_this` : | the current instance of CRInput.
`a_eof` : | the new end of file flag.
Returns : | CR_OK upon successful completion, an error code otherwise.

### cr_input_set_end_of_line ()

    enum CRStatus       cr_input_set_end_of_line            (CRInput *a_this,
                                                             gboolean a_eol);

Sets the end of line flag.

`a_this` : | the current instance of CRInput.
`a_eol` : | the new end of line flag.
Returns : | CR_OK upon successful completion, an error code otherwise.

### cr_input_set_line_num ()

    enum CRStatus       cr_input_set_line_num               (CRInput *a_this,
                                                             glong a_line_num);

Setter of the current line number.

Return CR_OK upon successful completion, an error code otherwise.

`a_this` : | the "this pointer" of the current instance of CRInput.
`a_line_num` : | the new line number.

### cr_input_unref ()

    gboolean            cr_input_unref                      (CRInput *a_this);

Decrements the reference count of this instance of CRInput. If the reference count goes down to zero, this instance is destroyed.

`a_this` : | the current instance of CRInput.
Returns : | TRUE if the instance of CRInput got destroyed, false otherwise.