vector.h 4.23 KB
Newer Older
1 2 3 4 5 6 7 8 9 10
/*******************************************************************************
 * Copyright 2019 UChicago Argonne, LLC.
 * (c.f. AUTHORS, LICENSE)
 *
 * This file is part of the AML project.
 * For more info, see https://xgitlab.cels.anl.gov/argo/aml
 *
 * SPDX-License-Identifier: BSD-3-Clause
*******************************************************************************/

11 12 13 14 15 16 17 18 19
#ifndef AML_VECTOR_H
#define AML_VECTOR_H

/*******************************************************************************
 * Generic vector type:
 * Vector of nbelems, each of size sz, with a comparison key at offset off
 ******************************************************************************/

/* Pointer to the key within element "e" of a vector "v".  */
20
#define AML_VECTOR_ELTKEY_P(v, e) ((int *)(((intptr_t) e) + v->off))
21
/* Pointer to the key within element index "i" of a vector "v".  */
22
#define AML_VECTOR_KEY_P(v, i) ((int *)(((intptr_t) v->ptr) + i*v->sz + v->off))
23
/* Pointer to the element index "i" of a vector "v".  */
24
#define AML_VECTOR_ELT_P(v, i) ((void *)(((intptr_t) v->ptr) + i*v->sz))
25 26 27 28 29 30 31 32 33 34

struct aml_vector {
	int na;
	size_t nbelems;
	size_t sz;
	size_t off;
	void *ptr;
};

/* not needed, here for consistency */
35 36
#define AML_VECTOR_DECL(name) struct aml_vector name
#define AML_VECTOR_ALLOCSIZE (sizeof(struct aml_vector))
37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83

/*
 * Provides the total number of elements in the vector, including currently
 * unused ones.
 * "vector": an initialized vector structure.
 * Returns the number of elements in the vector.
 */
size_t aml_vector_size(const struct aml_vector *vector);
/*
 * Provides a pointer of element with index "index" within the vector.
 * "vector": an initialized vector structure.
 * "index": a valid index within "vector".  The index must not equal "na" and
 *          must be lower than the size of the vector.
 * Returns a pointer to the requested element.
 */
void *aml_vector_get(struct aml_vector *vector, int index);
/*
 * Find the first element with a particular key.
 * "vector": an initialized vector structure.
 * "key": the key to look for.
 * Returns the index of the found element or "na" if not found.
 */
int aml_vector_find(const struct aml_vector *vector, int key);
/*
 * Resizes the vector.  The keys of the newly allocated elements are set to the
 * "na" value.
 * "vector": an initialized vector structure.
 * "newsize": a new vector size.  Only sizes greater than the current one will
 *            be honored; smaller sizes will result in a no-op.
 * Returns 0 if successful; an error code otherwise.
 */
int aml_vector_resize(struct aml_vector *vector, size_t newsize);
/*
 * Provides the pointer to the first unused element.  If the vector is full,
 * it automatically gets enlarged.
 * "vector": an initialized vector structure.
 * Returns the pointer to the first unused element.
 */
void *aml_vector_add(struct aml_vector *vector);
/*
 * Removes an element from the vector.  The key of the element is set to the
 * "na" value.
 * "vector": an initialized vector structure.
 * "elem": an element within the vector.
 */
void aml_vector_remove(struct aml_vector *vector, void *elem);

84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99
/**
 * Allocate and Initialize a vector. Allocates elements and sets their keys to
 * the "na" value.
 *
 * @param vector the address of a pointer to a struct aml_vector used as a
 * return value.
 * @param num the number of elements to allocate.
 * @param size the size of each individual element.
 * @param key the offset within each element where the key (of type int)
 * is stored.
 * @param na a "null" key value used to indicate an unused element.
 * @return 0 if successful; an error code otherwise.
 **/
int aml_vector_create(struct aml_vector **vector, size_t num, size_t size,
		      size_t key, int na);

100
/*
101 102 103 104
 * Initializes a vector. Similar to create.
 *
 * @param vector a vector declared with AML_VECTOR_DECL
 **/
105 106
int aml_vector_init(struct aml_vector *vector, size_t num, size_t size,
		    size_t key, int na);
107 108 109 110 111 112 113 114

/**
 * Finalize a vector. Frees all inner resources.
 *
 * @param vector a vector initialized by aml_vector_init.
 **/
void aml_vector_fini(struct aml_vector *vector);

115
/*
116 117 118 119 120
 * Finalize and free a struct aml_vector.
 *
 * @param vector a vector created by aml_vector_create. NULL after return.
 **/
void aml_vector_destroy(struct aml_vector **vector);
121 122 123

#endif //AML_VECTOR_H