src/vsvector.h

   1 /*
   2  * vsvector.h -- a dynamic array
   3  * (C) 2011 - Georg Martius
   4  *   georg dot martius at web dot de
   5  *
   6  *  This file is part of vid.stab video stabilization library
   7  *
   8  *  vid.stab is free software; you can redistribute it and/or modify
   9  *  it under the terms of the GNU General Public License,
  10  *  as published by the Free Software Foundation; either version 2, or
  11  *  (at your option) any later version.
  12  *
  13  *  vid.stab is distributed in the hope that it will be useful,
  14  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16  *  GNU General Public License for more details.
  17  *
  18  *  You should have received a copy of the GNU General Public License
  19  *  along with GNU Make; see the file COPYING.  If not, write to
  20  *  the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
  21  */
  22 #ifndef VSVECTOR_H
  23 #define VSVECTOR_H
  24
  25 #include <stddef.h>
  26 #include <stdio.h>
  27
  28 /**
  29    A vector for arbitrary elements that resizes
  30 */
  31 typedef struct vsvector_ VSVector;
  32 struct vsvector_ {
  33   void**  data;
  34   int    buffersize;
  35   int    nelems;
  36 };
  37
  38 /**
  39  * vs_vector_init:
  40  *     intializes a vector data structure.
  41  *     A vector will grow but not shrink if elements are added.
  42  *
  43  * Parameters:
  44  *              V: pointer to list to be initialized.
  45  *     buffersize: size of buffer (if known, then # of resizes are reduced)
  46  * Return Value:
  47  *     VS_OK on success,
  48  *     VS_ERROR on error.
  49  */
  50 int vs_vector_init(VSVector *V, int buffersize);
  51
  52 /**
  53  * vs_vector_fini:
  54  *     finalizes a vector data structure. Frees all resources aquired,
  55  *     but *NOT* the data pointed by vector elements.
  56  *
  57  * Parameters:
  58  *     V: pointer to list to be finalized
  59  * Return Value:
  60  *     VS_OK on success,
  61  *     VS_ERROR on error.
  62  */
  63 int vs_vector_fini(VSVector *V);
  64
  65 /**
  66  * vs_vector_del:
  67  *     like vs_vector_fini, but also deletes the data pointed by vector elements.
  68  *
  69  * Parameters:
  70  *     V: pointer to list to be finalized
  71  * Return Value:
  72  *     VS_OK on success,
  73  *     VS_ERROR on error.
  74  */
  75 int vs_vector_del(VSVector *V);
  76
  77 /**
  78  * vs_vector_zero:
  79  *    deletes all data pointed to by the vector elements.
  80  *    sets the number of elements to 0 but does not delete buffer
  81 */
  82 int vs_vector_zero(VSVector *V);
  83
  84 /**
  85  * vs_vector_size:
  86  *     gives the number of elements present in the vector
  87  *     (not the internal buffer size).
  88  *
  89  * Parameters:
  90  *     V: vector to be used.
  91  * Return Value:
  92  *    -1 on error,
  93  *    the number of elements otherwise
  94  */
  95 int vs_vector_size(const VSVector *V);
  96
  97
  98 /**
  99  * vs_vector_append:
 100  *     append an element to the vector.
 101  *     The element is added to the end of the vector.
 102  *
 103  * Parameters:
 104  *        V: pointer to vector to be used
 105  *     data: pointer to data to be appended or prepend.
 106  *           *PLEASE NOTE* that JUST THE POINTER is copied on the newly-added
 107  *           element. NO deep copy is performed.
 108  *           The caller has to allocate memory by itself if it want to
 109  *           add a copy of the data.
 110  * Return Value:
 111  *     VS_OK on success,
 112  *     VS_ERROR on error.
 113  */
 114 int vs_vector_append(VSVector *V, void *data);
 115
 116 /**
 117  * vs_vector_append_dup:
 118  *  like vs_vector_append but copies data
 119  */
 120 int vs_vector_append_dup(VSVector *V, void *data, int data_size);
 121
 122
 123 /* vs_vector_set:
 124  *      the newly inserted element BECOMES the position `pos' in the vector.
 125  *      and the old item is returned
 126  */
 127 void* vs_vector_set(VSVector *V, int pos, void *data);
 128
 129 /* vs_vector_set_dup:
 130  *      the newly inserted element is copied and BECOMES the position `pos' in the vector
 131  *      and the old item is returned
 132  */
 133 void* vs_vector_set_dup(VSVector *V, int pos, void *data, int data_size);
 134
 135 /*
 136  * vs_vector_get:
 137  *     gives access to the data pointed by the element in the given position.
 138  *
 139  * Parameters:
 140  *       V: vector to be accessed.
 141  *     pos: position of the element on which the data will be returned.
 142  * Return Value:
 143  *     NULL on error (requested element doesn't exist)
 144  *     a pointer to the data belonging to the requested vector item.
 145  */
 146 void *vs_vector_get(const VSVector *V, int pos);
 147
 148 /*
 149  * vs_vector_filter:
 150  *      returns a new vector with elements that fulfill predicate
 151  *      pred(param, elem)
 152  */
 153 VSVector vs_vector_filter(const VSVector *V, short (*pred)(void*, void*), void* param);
 154
 155 /*
 156  * vs_vector_concat:
 157  *      returns a new vector with elements of vector V1 and V2 after another
 158  */
 159 VSVector vs_vector_concat(const VSVector *V1, const VSVector *V2);
 160
 161
 162 /**
 163    A simple fixed-size double vector
 164 */
 165 typedef struct vsarray_ VSArray;
 166 struct vsarray_ {
 167   double* dat;
 168   int len;
 169 };
 170
 171 /** creates an VSArray from a double array */
 172 VSArray vs_array(double vals[], int len);
 173
 174 /** allocates a new (zero initialized) double array */
 175 VSArray vs_array_new(int len);
 176
 177 /** adds two vectors ands stores results into c (if zero length then allocated) */
 178 VSArray* vs_array_plus(VSArray* c, VSArray a, VSArray b);
 179
 180 /** scales a vector by a factor and stores results into c (if zero length then allocated) */
 181 VSArray* vs_array_scale(VSArray* c, VSArray a, double f);
 182
 183 /** create a new deep copy of the vector */
 184 VSArray vs_array_copy(VSArray a);
 185
 186 /** sets all elements of the vector to 0.0 */
 187 void vs_array_zero(VSArray* a);
 188
 189 /** swaps the content of the two arrays */
 190 void vs_array_swap(VSArray* a, VSArray* b);
 191
 192 /** free data */
 193 void vs_array_free(VSArray a);
 194
 195 /** print array to file */
 196 void vs_array_print(VSArray a, FILE* f);
 197
 198 #endif /* VSVECTOR_H */
 199
 200 /*
 201  * Local variables:
 202  *   c-file-style: "stroustrup"
 203  *   c-file-offsets: ((case-label . *) (statement-case-intro . *))
 204  *   indent-tabs-mode: nil
 205  * End:
 206  *
 207  * vim: expandtab shiftwidth=4:
 208  */