visualtest/include/SDL_visualtest_rwhelper.h
changeset 7924 fcb86d323770
child 11382 2c50e79b19e0
equal deleted inserted replaced
7923:d9ecdf71effb 7924:fcb86d323770
       
     1 /* See COPYING.txt for the full license governing this code. */
       
     2 /**
       
     3  * \file rwhelper.c
       
     4  *
       
     5  * Header file with some helper functions for working with SDL_RWops.
       
     6  */
       
     7 
       
     8 #include <SDL_rwops.h>
       
     9 
       
    10 #ifndef _SDL_visualtest_rwhelper_h
       
    11 #define _SDL_visualtest_rwhelper_h
       
    12 
       
    13 /** Length of the buffer in SDLVisualTest_RWHelperBuffer */
       
    14 #define RWOPS_BUFFER_LEN 256
       
    15 
       
    16 /* Set up for C function definitions, even when using C++ */
       
    17 #ifdef __cplusplus
       
    18 extern "C" {
       
    19 #endif
       
    20 
       
    21 /**
       
    22  * Struct that is used as a buffer by the RW helper functions. Should be initialized by calling
       
    23  * SDLVisualTest_RWHelperResetBuffer() before being used.
       
    24  */
       
    25 typedef struct SDLVisualTest_RWHelperBuffer
       
    26 {
       
    27     /*! Character buffer that data is read into */
       
    28     char buffer[RWOPS_BUFFER_LEN];
       
    29     /*! buffer[buffer_pos] is the next character to be read from the buffer */
       
    30     int buffer_pos;
       
    31     /*! Number of character read into the buffer */
       
    32     int buffer_width;
       
    33 } SDLVisualTest_RWHelperBuffer;
       
    34 
       
    35 /**
       
    36  * Resets the buffer pointed to by \c buffer used by some of the helper functions.
       
    37  * This function should be called when you're using one of the helper functions 
       
    38  * with a new SDL_RWops object.
       
    39  */
       
    40 void SDLVisualTest_RWHelperResetBuffer(SDLVisualTest_RWHelperBuffer* buffer);
       
    41 
       
    42 /**
       
    43  * Reads a single character using the SDL_RWops object pointed to by \c rw.
       
    44  * This function reads data in blocks and stores them in the buffer pointed to by
       
    45  * \c buffer, so other SDL_RWops functions should not be used in conjunction 
       
    46  * with this function.
       
    47  *
       
    48  * \return The character that was read.
       
    49  */
       
    50 char SDLVisualTest_RWHelperReadChar(SDL_RWops* rw,
       
    51                                     SDLVisualTest_RWHelperBuffer* buffer);
       
    52 
       
    53 /**
       
    54  * Reads characters using the SDL_RWops object pointed to by \c rw into the
       
    55  * character array pointed to by \c str (of size \c size) until either the 
       
    56  * array is full or a new line is encountered. If \c comment_char is encountered,
       
    57  * all characters from that position till the end of the line are ignored. The new line
       
    58  * is not included as part of the buffer. Lines with only whitespace and comments
       
    59  * are ignored. This function reads data in blocks and stores them in the buffer
       
    60  * pointed to by \c buffer, so other SDL_RWops functions should not be used in
       
    61  * conjunction with this function.
       
    62  * 
       
    63  * \return pointer to the string on success, NULL on failure or EOF.
       
    64  */
       
    65 char* SDLVisualTest_RWHelperReadLine(SDL_RWops* rw, char* str, int size,
       
    66                                      SDLVisualTest_RWHelperBuffer* buffer,
       
    67                                      char comment_char);
       
    68 
       
    69 /**
       
    70  * Counts the number of lines that are not all whitespace and comments using the
       
    71  * SDL_RWops object pointed to by \c rw. \c comment_char indicates the character
       
    72  * used for comments. Uses the buffer pointed to by \c buffer to read data in blocks.
       
    73  *
       
    74  * \return Number of lines on success, -1 on failure.
       
    75  */
       
    76 int SDLVisualTest_RWHelperCountNonEmptyLines(SDL_RWops* rw,
       
    77                                              SDLVisualTest_RWHelperBuffer* buffer,
       
    78                                              char comment_char);
       
    79 
       
    80 /* Ends C function definitions when using C++ */
       
    81 #ifdef __cplusplus
       
    82 }
       
    83 #endif
       
    84 
       
    85 #endif /* _SDL_visualtest_rwhelper_h */