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

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.10    ! misho       6: * $Id: aarray.h,v 1.9.4.2 2019/01/23 17:40:37 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.8       misho      15: Copyright 2004 - 2019
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)
1.10    ! misho      58: #define array_Zero(_arr)               (assert((_arr)), (_arr)->arr_last = -1, \
        !            59:                                                memset((_arr)->arr_data, 0, array_Size((_arr)) * sizeof(intptr_t)))
1.1       misho      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))
1.7       misho      63: #define array_Get(_arr, _d)            (assert((_arr)), (_arr)->arr_data[_d])
                     64: #define array(_arr, _d, _type)         (assert((_arr)), ((_type) (_arr)->arr_data[_d]))
                     65: #define array_Set(_arr, _d, _ptr)      do { int __d = _d; assert((_arr) && (_arr)->arr_num > __d); \
                     66:                                                if ((_arr)->arr_last < __d) \
                     67:                                                        (_arr)->arr_last = __d; \
                     68:                                                (_arr)->arr_data[__d] = (void*) (_ptr); \
1.1       misho      69:                                        } while (0)
1.7       misho      70: #define array_Del(_arr, _d, _fri)      do { int __d = _d; assert((_arr) && (_arr)->arr_num > __d); \
                     71:                                                if (_fri && (_arr)->arr_data[__d]) \
                     72:                                                        e_free((_arr)->arr_data[__d]); \
                     73:                                                (_arr)->arr_data[__d] = NULL; \
1.1       misho      74:                                        } while (0)
                     75: 
                     76: /*
                     77:  * array_Init() - Create and initialize dynamic array
                     78:  *
                     79:  * @numItems = Number of Items
                     80:  * return: NULL error, != NULL allocated memory for array
                     81:  */
1.2       misho      82: array_t *array_Init(int numItems);
1.9       misho      83: /*
                     84:  * array_Init2() - Initialize dynamic array
                     85:  *
                     86:  * @arr = Allocated array variable
                     87:  * @numItems = Number of Items
                     88:  * return: NULL error, != NULL allocated memory for array
                     89:  */
                     90: array_t *array_Init2(array_t * __restrict arr, int numItems);
1.1       misho      91: /*
                     92:  * array_Destroy() - Free and destroy dynamic array
                     93:  *
                     94:  * @parr = Array
                     95:  * return: none
                     96:  */
1.2       misho      97: void array_Destroy(array_t ** __restrict parr);
1.1       misho      98: /*
1.10    ! misho      99:  * array_Destroy2() - Free data in dynamic array
        !           100:  *
        !           101:  * @parr = Array
        !           102:  * return: none
        !           103:  */
        !           104: void array_Destroy2(array_t * __restrict arr);
        !           105: /*
1.1       misho     106:  * array_Free() - Free all data in dynamic array items
                    107:  *     (WARNING! If assign static array dont use this!!!)
                    108:  *
                    109:  * @arr = Array
                    110:  * return: none
                    111:  */
1.2       misho     112: void array_Free(array_t * __restrict arr);
1.8       misho     113: /*
                    114:  * array_Reset() - Reset array to initial state
                    115:  *
                    116:  * @parr = Array
1.10    ! misho     117:  * @purge = Purge all data, if <>0 then will be free entire data memory
1.8       misho     118:  * return: none
                    119:  */
                    120: void array_Reset(array_t * __restrict arr, int purge);
1.1       misho     121: 
                    122: /*
                    123:  * array_From() - Create and fill array from array with pointers
                    124:  *
                    125:  * @pargv = Array with pointers
                    126:  * @argc = Number of Items, if 0 walk through argv and stop when reach NULL item
                    127:  * return: NULL error, != NULL allocated new array
                    128:  */
                    129: array_t *array_From(const char *** __restrict pargv, int argc);
                    130: /*
                    131:  * array_Args() Parse and make array from arguments ... (input string will be modified!!! 
1.4       misho     132:  *     and output array must be free with array_Destroy() after use!)
1.1       misho     133:  *
                    134:  * @psArgs = Input arguments line, after execute string is modified!!!
                    135:  * @nargs = Maximum requested count of arguments from input string psArgs, if 0 all psArgs
                    136:  * @csDelim = Delimiter(s) for separate
                    137:  * @parr = Output array of arguments ... (must be free with array_Destroy() after use!)
                    138:  * return: 0 error format; -1 error:: can`t read; >0 ok, number of readed items
                    139:  */
                    140: int array_Args(char * __restrict psArgs, int nargs, const char *csDelim, 
                    141:                array_t ** __restrict parr);
                    142: /*
                    143:  * array_To() - Create and fill array with pointers from dynamic array
                    144:  *
                    145:  * @arr = Array
                    146:  * return: NULL error, != NULL allocated memory for array, NULL terminated
                    147:  */
                    148: char **array_To(array_t * __restrict arr);
                    149: 
                    150: /*
                    151:  * array_Len() - Get last used element in dynamic array (array Length)
                    152:  *
                    153:  * @arr = Array
                    154:  * return: -1 empty or >-1 position of last used element
                    155:  */
1.2       misho     156: int array_Len(array_t * __restrict arr);
1.1       misho     157: 
                    158: /*
                    159:  * array_Grow() - Grow/Shrink dynamic array, Use with care when it shrink!!!
                    160:  *
                    161:  * @arr = Array
                    162:  * @newNumItems = Number of Items
                    163:  * @freeShrink = Free elements before shrink array
                    164:  * return: -1 error, 0 ok
                    165:  */
                    166: int array_Grow(array_t * __restrict arr, int newNumItems, int freeShrink);
                    167: /*
                    168:  * array_Vacuum() - Vacuum dynamic array, empty elements will be deleted
                    169:  *
                    170:  * @arr = Array
                    171:  * @fromWhere = 1 begin, 2 ALL empty elements
                    172:  * return: -1 error, 0 ok
                    173:  */
                    174: int array_Vacuum(array_t * __restrict arr, int fromWhere);
                    175: /*
                    176:  * array_Concat() Concat source array to destination array
                    177:  *
                    178:  * @dest = Destination array
                    179:  * @src = Source array
                    180:  * return: -1 error; >0 new count of destination array
                    181:  */
                    182: int array_Concat(array_t * __restrict dest, array_t * __restrict src);
                    183: /*
                    184:  * array_Copy() Copy source array to destination array
                    185:  *
1.4       misho     186:  * @dest = Destination array, after use free with array_Destroy()
1.1       misho     187:  * @src = Source array
                    188:  * return: -1 error; >0 count of destination array
                    189:  */
                    190: int array_Copy(array_t ** __restrict dest, array_t * __restrict src);
                    191: 
                    192: /*
                    193:  * array_Elem() - Always GET/PUT element into dynamic array, if not enough elements grow array
                    194:  *
                    195:  * @arr = Array
                    196:  * @n = Position
                    197:  * @data = Element, if set NULL GET element at position or !=NULL PUT element at position
                    198:  * return: -1 error or !=-1 return element at position
                    199:  */
1.2       misho     200: void *array_Elem(array_t * __restrict arr, int n, void *data);
1.1       misho     201: /*
                    202:  * array_Push() - Push element into dynamic array like stack manner, place at first empty position
                    203:  *
                    204:  * @arr = Array
                    205:  * @data = Element, if set NULL return only first empty position
                    206:  * @nogrow = Don't grow array if not enough space
                    207:  * return: -1 not found empty position, array is full!, >-1 return position of stored element into array
                    208:  */
1.2       misho     209: int array_Push(array_t * __restrict arr, void *data, int nogrow);
1.1       misho     210: /*
                    211:  * array_Pop() - Pop element from dynamic array like stack manner, last used position
                    212:  *
                    213:  * @arr = Array
                    214:  * @data = Element, if set NULL return only last used position
                    215:  * @nodel = Don't delete after Pop element
                    216:  * return: -1 not found used position, array is empty!, >-1 return element position
                    217:  */
1.2       misho     218: int array_Pop(array_t * __restrict arr, void ** __restrict data, int nodel);
1.1       misho     219: 
                    220: 
                    221: #endif

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