/* See COPYING.txt for the full license governing this code. */
/**
 * \file rwhelper.c
 *
 * Header file with some helper functions for working with SDL_RWops.
 */

#include <SDL_rwops.h>

#ifndef SDL_visualtest_rwhelper_h_
#define SDL_visualtest_rwhelper_h_

/** Length of the buffer in SDLVisualTest_RWHelperBuffer */
#define RWOPS_BUFFER_LEN 256

/* Set up for C function definitions, even when using C++ */
#ifdef __cplusplus
extern "C" {
#endif

/**
 * Struct that is used as a buffer by the RW helper functions. Should be initialized by calling
 * SDLVisualTest_RWHelperResetBuffer() before being used.
 */
typedef struct SDLVisualTest_RWHelperBuffer
{
    /*! Character buffer that data is read into */
    char buffer[RWOPS_BUFFER_LEN];
    /*! buffer[buffer_pos] is the next character to be read from the buffer */
    int buffer_pos;
    /*! Number of character read into the buffer */
    int buffer_width;
} SDLVisualTest_RWHelperBuffer;

/**
 * Resets the buffer pointed to by \c buffer used by some of the helper functions.
 * This function should be called when you're using one of the helper functions 
 * with a new SDL_RWops object.
 */
void SDLVisualTest_RWHelperResetBuffer(SDLVisualTest_RWHelperBuffer* buffer);

/**
 * Reads a single character using the SDL_RWops object pointed to by \c rw.
 * This function reads data in blocks and stores them in the buffer pointed to by
 * \c buffer, so other SDL_RWops functions should not be used in conjunction 
 * with this function.
 *
 * \return The character that was read.
 */
char SDLVisualTest_RWHelperReadChar(SDL_RWops* rw,
                                    SDLVisualTest_RWHelperBuffer* buffer);

/**
 * Reads characters using the SDL_RWops object pointed to by \c rw into the
 * character array pointed to by \c str (of size \c size) until either the 
 * array is full or a new line is encountered. If \c comment_char is encountered,
 * all characters from that position till the end of the line are ignored. The new line
 * is not included as part of the buffer. Lines with only whitespace and comments
 * are ignored. This function reads data in blocks and stores them in the buffer
 * pointed to by \c buffer, so other SDL_RWops functions should not be used in
 * conjunction with this function.
 * 
 * \return pointer to the string on success, NULL on failure or EOF.
 */
char* SDLVisualTest_RWHelperReadLine(SDL_RWops* rw, char* str, int size,
                                     SDLVisualTest_RWHelperBuffer* buffer,
                                     char comment_char);

/**
 * Counts the number of lines that are not all whitespace and comments using the
 * SDL_RWops object pointed to by \c rw. \c comment_char indicates the character
 * used for comments. Uses the buffer pointed to by \c buffer to read data in blocks.
 *
 * \return Number of lines on success, -1 on failure.
 */
int SDLVisualTest_RWHelperCountNonEmptyLines(SDL_RWops* rw,
                                             SDLVisualTest_RWHelperBuffer* buffer,
                                             char comment_char);

/* Ends C function definitions when using C++ */
#ifdef __cplusplus
}
#endif

#endif /* SDL_visualtest_rwhelper_h_ */

/* vi: set ts=4 sw=4 expandtab: */