Annotation of libelwix/inc/elwix/aarray.h, revision 1.5

1.1       misho       1: /*************************************************************************
                      2: * (C) 2013 AITNET ltd - Sofia/Bulgaria - <misho@aitnet.org>
                      3: *  by Michael Pounov <misho@elwix.org>
                      4: *
                      5: * $Author: misho $
1.5     ! misho       6: * $Id: aarray.h,v 1.4.6.1 2014/01/29 14:15:58 misho Exp $
1.1       misho       7: *
                      8: **************************************************************************
                      9: The ELWIX and AITNET software is distributed under the following
                     10: terms:
                     11: 
                     12: All of the documentation and software included in the ELWIX and AITNET
                     13: Releases is copyrighted by ELWIX - Sofia/Bulgaria <info@elwix.org>
                     14: 
1.5     ! misho      15: Copyright 2004 - 2014
1.1       misho      16:        by Michael Pounov <misho@elwix.org>.  All rights reserved.
                     17: 
                     18: Redistribution and use in source and binary forms, with or without
                     19: modification, are permitted provided that the following conditions
                     20: are met:
                     21: 1. Redistributions of source code must retain the above copyright
                     22:    notice, this list of conditions and the following disclaimer.
                     23: 2. Redistributions in binary form must reproduce the above copyright
                     24:    notice, this list of conditions and the following disclaimer in the
                     25:    documentation and/or other materials provided with the distribution.
                     26: 3. All advertising materials mentioning features or use of this software
                     27:    must display the following acknowledgement:
                     28: This product includes software developed by Michael Pounov <misho@elwix.org>
                     29: ELWIX - Embedded LightWeight unIX and its contributors.
                     30: 4. Neither the name of AITNET nor the names of its contributors
                     31:    may be used to endorse or promote products derived from this software
                     32:    without specific prior written permission.
                     33: 
                     34: THIS SOFTWARE IS PROVIDED BY AITNET AND CONTRIBUTORS ``AS IS'' AND
                     35: ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
                     36: IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
                     37: ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
                     38: FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
                     39: DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
                     40: OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
                     41: HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
                     42: LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
                     43: OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
                     44: SUCH DAMAGE.
                     45: */
                     46: #ifndef __AARRAY_H
                     47: #define __AARRAY_H
                     48: 
                     49: 
                     50: typedef struct _tagArray {
                     51:        int     arr_last;
                     52:        int     arr_num;
                     53:        void    **arr_data;
                     54: } array_t;
                     55: 
                     56: #define array_Size(_arr)               ((_arr) ? (_arr)->arr_num : 0)
                     57: #define array_Last(_arr)               (array_Size((_arr)) ? (_arr)->arr_last : -1)
                     58: #define array_Zero(_arr)               (assert((_arr)), memset((_arr)->arr_data, 0, \
                     59:                                                array_Size((_arr)) * sizeof(intptr_t)))
                     60: 
1.3       misho      61: #define array_Ptr(_arr, _d)            ((_arr) ? (_arr)->arr_data[_d] : NULL)
1.1       misho      62: #define array_Get2(_arr, _d)           (assert((_arr) && (_arr)->arr_num > _d), ((_arr)->arr_data + _d))
                     63: #define array_Get(_arr, _d)            (assert((_arr) && (_arr)->arr_num > _d), (_arr)->arr_data[_d])
                     64: #define array(_arr, _d, _type)         (assert((_arr) && (_arr)->arr_num > _d), \
                     65:                                                ((_type) (_arr)->arr_data[_d]))
                     66: #define array_Set(_arr, _d, _ptr)      do { assert((_arr) && (_arr)->arr_num > _d); \
                     67:                                                if ((_arr)->arr_last < _d) \
                     68:                                                        (_arr)->arr_last = _d; \
                     69:                                                (_arr)->arr_data[_d] = (void*) (_ptr); \
                     70:                                        } while (0)
                     71: #define array_Del(_arr, _d, _fri)      do { assert((_arr) && (_arr)->arr_num > _d); \
                     72:                                                if (_fri && (_arr)->arr_data[_d]) \
                     73:                                                        e_free((_arr)->arr_data[_d]); \
                     74:                                                (_arr)->arr_data[_d] = NULL; \
                     75:                                        } while (0)
                     76: 
                     77: /*
                     78:  * array_Init() - Create and initialize dynamic array
                     79:  *
                     80:  * @numItems = Number of Items
                     81:  * return: NULL error, != NULL allocated memory for array
                     82:  */
1.2       misho      83: array_t *array_Init(int numItems);
1.1       misho      84: /*
                     85:  * array_Destroy() - Free and destroy dynamic array
                     86:  *
                     87:  * @parr = Array
                     88:  * return: none
                     89:  */
1.2       misho      90: void array_Destroy(array_t ** __restrict parr);
1.1       misho      91: /*
                     92:  * array_Free() - Free all data in dynamic array items
                     93:  *     (WARNING! If assign static array dont use this!!!)
                     94:  *
                     95:  * @arr = Array
                     96:  * return: none
                     97:  */
1.2       misho      98: void array_Free(array_t * __restrict arr);
1.1       misho      99: 
                    100: /*
                    101:  * array_From() - Create and fill array from array with pointers
                    102:  *
                    103:  * @pargv = Array with pointers
                    104:  * @argc = Number of Items, if 0 walk through argv and stop when reach NULL item
                    105:  * return: NULL error, != NULL allocated new array
                    106:  */
                    107: array_t *array_From(const char *** __restrict pargv, int argc);
                    108: /*
                    109:  * array_Args() Parse and make array from arguments ... (input string will be modified!!! 
1.4       misho     110:  *     and output array must be free with array_Destroy() after use!)
1.1       misho     111:  *
                    112:  * @psArgs = Input arguments line, after execute string is modified!!!
                    113:  * @nargs = Maximum requested count of arguments from input string psArgs, if 0 all psArgs
                    114:  * @csDelim = Delimiter(s) for separate
                    115:  * @parr = Output array of arguments ... (must be free with array_Destroy() after use!)
                    116:  * return: 0 error format; -1 error:: can`t read; >0 ok, number of readed items
                    117:  */
                    118: int array_Args(char * __restrict psArgs, int nargs, const char *csDelim, 
                    119:                array_t ** __restrict parr);
                    120: /*
                    121:  * array_To() - Create and fill array with pointers from dynamic array
                    122:  *
                    123:  * @arr = Array
                    124:  * return: NULL error, != NULL allocated memory for array, NULL terminated
                    125:  */
                    126: char **array_To(array_t * __restrict arr);
                    127: 
                    128: /*
                    129:  * array_Len() - Get last used element in dynamic array (array Length)
                    130:  *
                    131:  * @arr = Array
                    132:  * return: -1 empty or >-1 position of last used element
                    133:  */
1.2       misho     134: int array_Len(array_t * __restrict arr);
1.1       misho     135: 
                    136: /*
                    137:  * array_Grow() - Grow/Shrink dynamic array, Use with care when it shrink!!!
                    138:  *
                    139:  * @arr = Array
                    140:  * @newNumItems = Number of Items
                    141:  * @freeShrink = Free elements before shrink array
                    142:  * return: -1 error, 0 ok
                    143:  */
                    144: int array_Grow(array_t * __restrict arr, int newNumItems, int freeShrink);
                    145: /*
                    146:  * array_Vacuum() - Vacuum dynamic array, empty elements will be deleted
                    147:  *
                    148:  * @arr = Array
                    149:  * @fromWhere = 1 begin, 2 ALL empty elements
                    150:  * return: -1 error, 0 ok
                    151:  */
                    152: int array_Vacuum(array_t * __restrict arr, int fromWhere);
                    153: /*
                    154:  * array_Concat() Concat source array to destination array
                    155:  *
                    156:  * @dest = Destination array
                    157:  * @src = Source array
                    158:  * return: -1 error; >0 new count of destination array
                    159:  */
                    160: int array_Concat(array_t * __restrict dest, array_t * __restrict src);
                    161: /*
                    162:  * array_Copy() Copy source array to destination array
                    163:  *
1.4       misho     164:  * @dest = Destination array, after use free with array_Destroy()
1.1       misho     165:  * @src = Source array
                    166:  * return: -1 error; >0 count of destination array
                    167:  */
                    168: int array_Copy(array_t ** __restrict dest, array_t * __restrict src);
                    169: 
                    170: /*
                    171:  * array_Elem() - Always GET/PUT element into dynamic array, if not enough elements grow array
                    172:  *
                    173:  * @arr = Array
                    174:  * @n = Position
                    175:  * @data = Element, if set NULL GET element at position or !=NULL PUT element at position
                    176:  * return: -1 error or !=-1 return element at position
                    177:  */
1.2       misho     178: void *array_Elem(array_t * __restrict arr, int n, void *data);
1.1       misho     179: /*
                    180:  * array_Push() - Push element into dynamic array like stack manner, place at first empty position
                    181:  *
                    182:  * @arr = Array
                    183:  * @data = Element, if set NULL return only first empty position
                    184:  * @nogrow = Don't grow array if not enough space
                    185:  * return: -1 not found empty position, array is full!, >-1 return position of stored element into array
                    186:  */
1.2       misho     187: int array_Push(array_t * __restrict arr, void *data, int nogrow);
1.1       misho     188: /*
                    189:  * array_Pop() - Pop element from dynamic array like stack manner, last used position
                    190:  *
                    191:  * @arr = Array
                    192:  * @data = Element, if set NULL return only last used position
                    193:  * @nodel = Don't delete after Pop element
                    194:  * return: -1 not found used position, array is empty!, >-1 return element position
                    195:  */
1.2       misho     196: int array_Pop(array_t * __restrict arr, void ** __restrict data, int nodel);
1.1       misho     197: 
                    198: 
                    199: #endif

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>