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

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.9     ! misho       6: * $Id: aarray.h,v 1.8.4.1 2019/01/22 16:16:45 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)
                     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))
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: /*
                     99:  * array_Free() - Free all data in dynamic array items
                    100:  *     (WARNING! If assign static array dont use this!!!)
                    101:  *
                    102:  * @arr = Array
                    103:  * return: none
                    104:  */
1.2       misho     105: void array_Free(array_t * __restrict arr);
1.8       misho     106: /*
                    107:  * array_Reset() - Reset array to initial state
                    108:  *
                    109:  * @parr = Array
                    110:  * @purge = Purge data, if <>0 then will be free entire data memory
                    111:  * return: none
                    112:  */
                    113: void array_Reset(array_t * __restrict arr, int purge);
1.1       misho     114: 
                    115: /*
                    116:  * array_From() - Create and fill array from array with pointers
                    117:  *
                    118:  * @pargv = Array with pointers
                    119:  * @argc = Number of Items, if 0 walk through argv and stop when reach NULL item
                    120:  * return: NULL error, != NULL allocated new array
                    121:  */
                    122: array_t *array_From(const char *** __restrict pargv, int argc);
                    123: /*
                    124:  * array_Args() Parse and make array from arguments ... (input string will be modified!!! 
1.4       misho     125:  *     and output array must be free with array_Destroy() after use!)
1.1       misho     126:  *
                    127:  * @psArgs = Input arguments line, after execute string is modified!!!
                    128:  * @nargs = Maximum requested count of arguments from input string psArgs, if 0 all psArgs
                    129:  * @csDelim = Delimiter(s) for separate
                    130:  * @parr = Output array of arguments ... (must be free with array_Destroy() after use!)
                    131:  * return: 0 error format; -1 error:: can`t read; >0 ok, number of readed items
                    132:  */
                    133: int array_Args(char * __restrict psArgs, int nargs, const char *csDelim, 
                    134:                array_t ** __restrict parr);
                    135: /*
                    136:  * array_To() - Create and fill array with pointers from dynamic array
                    137:  *
                    138:  * @arr = Array
                    139:  * return: NULL error, != NULL allocated memory for array, NULL terminated
                    140:  */
                    141: char **array_To(array_t * __restrict arr);
                    142: 
                    143: /*
                    144:  * array_Len() - Get last used element in dynamic array (array Length)
                    145:  *
                    146:  * @arr = Array
                    147:  * return: -1 empty or >-1 position of last used element
                    148:  */
1.2       misho     149: int array_Len(array_t * __restrict arr);
1.1       misho     150: 
                    151: /*
                    152:  * array_Grow() - Grow/Shrink dynamic array, Use with care when it shrink!!!
                    153:  *
                    154:  * @arr = Array
                    155:  * @newNumItems = Number of Items
                    156:  * @freeShrink = Free elements before shrink array
                    157:  * return: -1 error, 0 ok
                    158:  */
                    159: int array_Grow(array_t * __restrict arr, int newNumItems, int freeShrink);
                    160: /*
                    161:  * array_Vacuum() - Vacuum dynamic array, empty elements will be deleted
                    162:  *
                    163:  * @arr = Array
                    164:  * @fromWhere = 1 begin, 2 ALL empty elements
                    165:  * return: -1 error, 0 ok
                    166:  */
                    167: int array_Vacuum(array_t * __restrict arr, int fromWhere);
                    168: /*
                    169:  * array_Concat() Concat source array to destination array
                    170:  *
                    171:  * @dest = Destination array
                    172:  * @src = Source array
                    173:  * return: -1 error; >0 new count of destination array
                    174:  */
                    175: int array_Concat(array_t * __restrict dest, array_t * __restrict src);
                    176: /*
                    177:  * array_Copy() Copy source array to destination array
                    178:  *
1.4       misho     179:  * @dest = Destination array, after use free with array_Destroy()
1.1       misho     180:  * @src = Source array
                    181:  * return: -1 error; >0 count of destination array
                    182:  */
                    183: int array_Copy(array_t ** __restrict dest, array_t * __restrict src);
                    184: 
                    185: /*
                    186:  * array_Elem() - Always GET/PUT element into dynamic array, if not enough elements grow array
                    187:  *
                    188:  * @arr = Array
                    189:  * @n = Position
                    190:  * @data = Element, if set NULL GET element at position or !=NULL PUT element at position
                    191:  * return: -1 error or !=-1 return element at position
                    192:  */
1.2       misho     193: void *array_Elem(array_t * __restrict arr, int n, void *data);
1.1       misho     194: /*
                    195:  * array_Push() - Push element into dynamic array like stack manner, place at first empty position
                    196:  *
                    197:  * @arr = Array
                    198:  * @data = Element, if set NULL return only first empty position
                    199:  * @nogrow = Don't grow array if not enough space
                    200:  * return: -1 not found empty position, array is full!, >-1 return position of stored element into array
                    201:  */
1.2       misho     202: int array_Push(array_t * __restrict arr, void *data, int nogrow);
1.1       misho     203: /*
                    204:  * array_Pop() - Pop element from dynamic array like stack manner, last used position
                    205:  *
                    206:  * @arr = Array
                    207:  * @data = Element, if set NULL return only last used position
                    208:  * @nodel = Don't delete after Pop element
                    209:  * return: -1 not found used position, array is empty!, >-1 return element position
                    210:  */
1.2       misho     211: int array_Pop(array_t * __restrict arr, void ** __restrict data, int nodel);
1.1       misho     212: 
                    213: 
                    214: #endif

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