X-Git-Url: http://git.droids-corp.org/?a=blobdiff_plain;f=lib%2Fecoli_strvec.h;h=8e14973b40123ee646ac9b882dc97840e8286114;hb=dec2d7fa17ae1e8b3d1dec8e396d057757baf4f3;hp=af1db57f653df8d48e9d4cd88b7db3017f771c8a;hpb=c1eb3099a1a7f4c9b9f8c6238336ee5b69147fd6;p=protos%2Flibecoli.git diff --git a/lib/ecoli_strvec.h b/lib/ecoli_strvec.h index af1db57..8e14973 100644 --- a/lib/ecoli_strvec.h +++ b/lib/ecoli_strvec.h @@ -1,44 +1,174 @@ -/* - * Copyright (c) 2016, Olivier MATZ - * - * Redistribution and use in source and binary forms, with or without - * modification, are permitted provided that the following conditions are met: - * - * * Redistributions of source code must retain the above copyright - * notice, this list of conditions and the following disclaimer. - * * Redistributions in binary form must reproduce the above copyright - * notice, this list of conditions and the following disclaimer in the - * documentation and/or other materials provided with the distribution. - * * Neither the name of the University of California, Berkeley nor the - * names of its contributors may be used to endorse or promote products - * derived from this software without specific prior written permission. - * - * THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND ANY - * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED - * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - * DISCLAIMED. IN NO EVENT SHALL THE REGENTS AND CONTRIBUTORS BE LIABLE FOR ANY - * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES - * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; - * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND - * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT - * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS - * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +/* SPDX-License-Identifier: BSD-3-Clause + * Copyright 2016, Olivier MATZ + */ + +/** + * Vectors of strings. + * + * The ec_strvec API provide helpers to manipulate string vectors. + * When duplicating vectors, the strings are not duplicated in memory, + * a reference counter is used. */ #ifndef ECOLI_STRVEC_ #define ECOLI_STRVEC_ -#include #include +/** + * Allocate a new empty string vector. + * + * @return + * The new strvec object, or NULL on error (errno is set). + */ struct ec_strvec *ec_strvec(void); + +#ifndef EC_COUNT_OF +#define EC_COUNT_OF(x) ((sizeof(x)/sizeof(0[x])) / \ + ((size_t)(!(sizeof(x) % sizeof(0[x]))))) +#endif + +/** + * Allocate a new string vector + * + * The string vector is initialized with the list of const strings + * passed as arguments. + * + * @return + * The new strvec object, or NULL on error (errno is set). + */ +#define EC_STRVEC(args...) ({ \ + const char *_arr[] = {args}; \ + ec_strvec_from_array(_arr, EC_COUNT_OF(_arr)); \ + }) +/** + * Allocate a new string vector + * + * The string vector is initialized with the array of const strings + * passed as arguments. + * + * @param strarr + * The array of const strings. + * @param n + * The number of strings in the array. + * @return + * The new strvec object, or NULL on error (errno is set). + */ +struct ec_strvec *ec_strvec_from_array(const char * const *strarr, + size_t n); + +/** + * Add a string in a vector. + * + * @param strvec + * The pointer to the string vector. + * @param s + * The string to be added at the end of the vector. + * @return + * 0 on success or -1 on error (errno is set). + */ int ec_strvec_add(struct ec_strvec *strvec, const char *s); + +/** + * Delete the last entry in the string vector. + * + * @param strvec + * The pointer to the string vector. + * @param s + * The string to be added at the end of the vector. + * @return + * 0 on success or -1 on error (errno is set). + */ +int ec_strvec_del_last(struct ec_strvec *strvec); + +/** + * Duplicate a string vector. + * + * @param strvec + * The pointer to the string vector. + * @return + * The duplicated strvec object, or NULL on error (errno is set). + */ struct ec_strvec *ec_strvec_dup(const struct ec_strvec *strvec); + +/** + * Duplicate a part of a string vector. + * + * @param strvec + * The pointer to the string vector. + * @param off + * The index of the first string to duplicate. + * @param + * The number of strings to duplicate. + * @return + * The duplicated strvec object, or NULL on error (errno is set). + */ struct ec_strvec *ec_strvec_ndup(const struct ec_strvec *strvec, size_t off, size_t len); + +/** + * Free a string vector. + * + * @param strvec + * The pointer to the string vector. + */ void ec_strvec_free(struct ec_strvec *strvec); + +/** + * Get the length of a string vector. + * + * @param strvec + * The pointer to the string vector. + * @return + * The length of the vector. + */ size_t ec_strvec_len(const struct ec_strvec *strvec); -char *ec_strvec_val(const struct ec_strvec *strvec, size_t idx); + +/** + * Get a string element from a vector. + * + * @param strvec + * The pointer to the string vector. + * @param idx + * The index of the string to get. + * @return + * The string stored at given index, or NULL on error (strvec is NULL + * or invalid index). + */ +const char *ec_strvec_val(const struct ec_strvec *strvec, size_t idx); + +/** + * Compare two string vectors + * + * @param strvec + * The pointer to the first string vector. + * @param strvec + * The pointer to the second string vector. + * @return + * 0 if the string vectors are equal. + */ +int ec_strvec_cmp(const struct ec_strvec *strvec1, + const struct ec_strvec *strvec2); + +/** + * Sort the string vector. + * + * @param strvec + * The pointer to the first string vector. + * @param str_cmp + * The sort function to use. If NULL, use strcmp. + */ +void ec_strvec_sort(struct ec_strvec *strvec, + int (*str_cmp)(const char *s1, const char *s2)); + +/** + * Dump a string vector. + * + * @param out + * The stream where the dump is sent. + * @param strvec + * The pointer to the string vector. + */ void ec_strvec_dump(FILE *out, const struct ec_strvec *strvec); #endif