1 /*

     2  * Hedgewars, a free turn based strategy game

     3  * Copyright (C) 2012 Simeon Maxein <smaxein@googlemail.com>

     4  *

     5  * This program is free software; you can redistribute it and/or

     6  * modify it under the terms of the GNU General Public License

     7  * as published by the Free Software Foundation; either version 2

     8  * of the License, or (at your option) any later version.

     9  *

    10  * This program is distributed in the hope that it will be useful,

    11  * but WITHOUT ANY WARRANTY; without even the implied warranty of

    12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

    13  * GNU General Public License for more details.

    14  *

    15  * You should have received a copy of the GNU General Public License

    16  * along with this program; if not, write to the Free Software

    17  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.

    18  */

    19 

    20 #ifndef BUFFER_H_

    21 #define BUFFER_H_

    22 

    23 #include <stdint.h>

    24 #include <stddef.h>

    25 

    26 /**

    27  * A simple struct to hold both the pointer to an array and its size,

    28  * for e.g. conveniently returning it from a function.

    29  *

    30  * Convention: Size is zero iff data is a NULL pointer.

    31  */

    32 typedef struct {

    33 	void *data;

    34 	size_t size;

    35 } flib_buffer;

    36 

    37 /**

    38  * Just like flib_buffer, but the contents are not supposed to be modified.

    39  */

    40 typedef struct {

    41 	const void *data;

    42 	size_t size;

    43 } flib_constbuffer;

    44 

    45 /**

    46  * Simple variable-capacity data structure that can be efficiently appended to.

    47  */

    48 typedef struct _flib_vector flib_vector;

    49 

    50 /**

    51  * Create a new vector. Needs to be destroyed again later with flib_vector_destroy.

    52  * May return NULL if memory runs out.

    53  */

    54 flib_vector *flib_vector_create();

    55 

    56 /**

    57  * Free the memory of this vector

    58  */

    59 void flib_vector_destroy(flib_vector *vec);

    60 

    61 /**

    62  * Resize the vector. This changes the size, and ensures the capacity is large enough to

    63  * for the new size. Can also free memory if the new size is smaller. There is no guarantee

    64  * about the contents of extra memory.

    65  */

    66 int flib_vector_resize(flib_vector *vec, size_t newSize);

    67 

    68 /**

    69  * Append the provided data to the end of the vector, enlarging it as required.

    70  * The vector remains unchanged if appending fails.

    71  * Returns 0 on success.

    72  */

    73 int flib_vector_append(flib_vector *vec, const void *data, size_t len);

    74 

    75 /**

    76  * Append data from a format string to the buffer (without trailing 0)

    77  * Returns 0 on success.

    78  */

    79 int flib_vector_appendf(flib_vector *vec, const char *template, ...);

    80 

    81 /**

    82  * Return a pointer to the current data buffer of the vector. This pointer can

    83  * become invalid if the vector size or capacity is changed.

    84  */

    85 void *flib_vector_data(flib_vector *vec);

    86 

    87 /**

    88  * Return the current size of the vector.

    89  */

    90 size_t flib_vector_size(flib_vector *vec);

    91 

    92 /**

    93  * Return a buffer pointing to the current contents of the vector.

    94  * These will become invalid if the vector size or capacity is changed.

    95  */

    96 flib_buffer flib_vector_as_buffer(flib_vector *vec);

    97 

    98 /**

    99  * Return a constbuffer pointing to the current contents of the vector.

   100  * These will become invalid if the vector size or capacity is changed.

   101  */

   102 flib_constbuffer flib_vector_as_constbuffer(flib_vector *vec);

   103 

   104 #endif