3
* @brief generic bag container interface
7
* Copyright 2011 Canonical Ltd.
9
* This program is free software: you can redistribute it and/or modify it
10
* under the terms of the GNU General Public License version 3, as published
11
* by the Free Software Foundation.
13
* This program is distributed in the hope that it will be useful, but
14
* WITHOUT ANY WARRANTY; without even the implied warranties of
15
* MERCHANTABILITY, SATISFACTORY QUALITY, or FITNESS FOR A PARTICULAR
16
* PURPOSE. See the GNU General Public License for more details.
18
* You should have received a copy of the GNU General Public License along
19
* with this program. If not, see <http://www.gnu.org/licenses/>.
21
#ifndef GEIS_UTIL_BAG_H
22
#define GEIS_UTIL_BAG_H
24
#include "geis/geis.h"
29
* @brief A handle for a generic value-storage bag.
32
* A bag is a container that holds zero or more copies of a data structure of
33
* homogeneous type. It is implemented as a contiguous store of data that grows
34
* when needed using a predetermined growth factor to give amortized constant
35
* insertion and removal rates.
37
* Uses of this structure should be wrapped by more type-specific functions.
40
* @brief opaque pointer to a GeisBag object.
42
typedef struct GeisBag *GeisBag;
46
GeisSize store_size; /**< The size of data_store in datum_size
48
GeisFloat store_growth_factor; /**< The storage growth factor. */
49
GeisSize datum_size; /**< The number of bytes in each datum. */
50
GeisSize data_count; /**< The number of data in data_store. */
51
void *data_store; /**< The the data store. */
55
static const GeisSize geis_bag_default_init_alloc = 2;
56
static const GeisFloat geis_bag_default_growth_factor = 1.5f;
60
* Creates a new, empty bag.
63
* @param[in] data_size The size (in bytes) of the stored datum.
64
* @param[in] init_alloc The initial number of data to allocate space for.
65
* @param[in] growth_factor The growth factor for extending the bag.
67
* Constructs a generic homogenous container that is designed to hold data with
68
* a size of @p data_size (in bytes). Space for @p init_alloc data is initially
69
* allocated, and subsequent expansions will be done by a factor of
70
* @p growth_factor (taking the ceiling of the current allocation times the @p
73
* @returns a new, empty GeisBag on success or a NULL on failure.
76
geis_bag_new(GeisSize data_size, GeisSize init_alloc, GeisFloat growth_factor);
82
* @param[in] bag The bag to destroy.
84
* Frees all resources used by the bag itself: does not destroy any store data.
87
geis_bag_delete(GeisBag bag);
90
* Gets the number of data contained in the bag.
93
* @param[in] bag The bag.
95
* @returns the count of the data contained in the bag.
98
geis_bag_count(GeisBag bag);
101
* Appends a new datam to the store.
104
* @param[in] bag The bag to append to.
105
* @param[in] datum The datum to append.
107
* @returns GEIS_STATUS_UNKNOWN_ERROR if @p datum failed to be appended (for
108
* example, memory allocation failure during bag expansion), GEIS_STATUS_SUCCESS
112
geis_bag_append(GeisBag bag, void *datum);
115
* Gets a pointer to a datum by index.
118
* @param[in] bag The bag.
119
* @param[in] index Indicates the datum to retrieve.
121
* @returns NULL if @p index is out of range, a pointer to the indictaed datum
125
geis_bag_at(GeisBag bag, GeisSize index);
128
* Removes an indicated datum from the bag.
131
* @param[in] bag The bag.
132
* @param[in] index Indicates the datum to remove.
134
* This function removes the datum and if necessary fills in the 'hole' in the
135
* store by moving other data around. It will invalidate any pointers into the
136
* bag: avoid using 'em. Does not call any deleter functions, so plan
139
* @returns GEIS_STATUS_BAD_ARGUMENT if @p index is out of range,
140
* GEIS_STATUS_SUCCESS otherwise.
143
geis_bag_remove(GeisBag bag, GeisSize index);
145
#endif /* GEIS_UTIL_BAG_H */
added
removed
libs/geis-util/geis_bag.h
