481 lines
13 KiB
C
481 lines
13 KiB
C
/*
|
|
Copyright (c) 2006-2020 Chung, Hyung-Hwan. All rights reserved.
|
|
|
|
Redistribution and use in source and binary forms, with or without
|
|
modification, are permitted provided that the following conditions
|
|
are met:
|
|
1. Redistributions of source code must retain the above copyright
|
|
notice, this list of conditions and the following disclaimer.
|
|
2. 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.
|
|
|
|
THIS SOFTWARE IS PROVIDED BY THE AUTHOR "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 AUTHOR 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.
|
|
*/
|
|
|
|
#ifndef _HAWK_ARR_H_
|
|
#define _HAWK_ARR_H_
|
|
|
|
#include <hawk-cmn.h>
|
|
|
|
/** \file
|
|
* This file provides a linear dynamic array. It grows dynamically as items
|
|
* are added.
|
|
*/
|
|
|
|
enum hawk_arr_walk_t
|
|
{
|
|
HAWK_ARR_WALK_STOP = 0,
|
|
HAWK_ARR_WALK_FORWARD = 1,
|
|
HAWK_ARR_WALK_BACKWARD = 2
|
|
};
|
|
|
|
typedef struct hawk_arr_t hawk_arr_t;
|
|
typedef struct hawk_arr_slot_t hawk_arr_slot_t;
|
|
typedef enum hawk_arr_walk_t hawk_arr_walk_t;
|
|
|
|
#define HAWK_ARR_COPIER_SIMPLE ((hawk_arr_copier_t)1)
|
|
#define HAWK_ARR_COPIER_INLINE ((hawk_arr_copier_t)2)
|
|
|
|
#define HAWK_ARR_COPIER_DEFAULT (HAWK_ARR_COPIER_SIMPLE)
|
|
#define HAWK_ARR_FREEER_DEFAULT (HAWK_NULL)
|
|
#define HAWK_ARR_COMPER_DEFAULT (hawk_arr_dflcomp)
|
|
#define HAWK_ARR_KEEPER_DEFAULT (HAWK_NULL)
|
|
#define HAWK_ARR_SIZER_DEFAULT (HAWK_NULL)
|
|
|
|
#define HAWK_ARR_NIL ((hawk_oow_t)-1)
|
|
|
|
#define HAWK_ARR_SIZE(arr) ((arr)->size)
|
|
#define HAWK_ARR_CAPA(arr) ((arr)->capa)
|
|
#define HAWK_ARR_TALLY(arr) ((arr)->tally)
|
|
|
|
#define HAWK_ARR_SLOT(arr,index) ((arr)->slot[index])
|
|
#define HAWK_ARR_DPTL(arr,index) ((const hawk_ptl_t*)&(arr)->slot[index]->val)
|
|
#define HAWK_ARR_DPTR(arr,index) ((arr)->slot[index]->val.ptr)
|
|
#define HAWK_ARR_DLEN(arr,index) ((arr)->slot[index]->val.len)
|
|
|
|
/**
|
|
* The hawk_arr_copier_t type defines a callback function for slot construction.
|
|
* A slot is contructed when a user adds data to an array. The user can
|
|
* define how the data to add can be maintained in the array. A dynamic
|
|
* array not specified with any copiers stores the data pointer and
|
|
* the data length into a slot. A special copier HAWK_ARR_COPIER_INLINE copies
|
|
* the contents of the data a user provided into the slot.
|
|
*
|
|
* A copier should return the pointer to the copied data. If it fails to copy
|
|
* data, it may return HAWK_NULL. You need to set a proper freeer to free up
|
|
* memory allocated for copy.
|
|
*/
|
|
typedef void* (*hawk_arr_copier_t) (
|
|
hawk_arr_t* arr /**< array */,
|
|
void* dptr /**< pointer to data to copy */,
|
|
hawk_oow_t dlen /**< length of data to copy */
|
|
);
|
|
|
|
/**
|
|
* The hawk_arr_freeer_t type defines a slot destruction callback.
|
|
*/
|
|
typedef void (*hawk_arr_freeer_t) (
|
|
hawk_arr_t* arr /**< array */,
|
|
void* dptr /**< pointer to data to free */,
|
|
hawk_oow_t dlen /**< length of data to free */
|
|
);
|
|
|
|
/**
|
|
* The hawk_arr_comper_t type defines a key comparator that is called when
|
|
* the arry needs to compare data. A linear dynamic array is created with a
|
|
* default comparator that performs bitwise comparison.
|
|
*
|
|
* The default comparator compares data in a memcmp-like fashion.
|
|
* It is not suitable when you want to implement a heap of numbers
|
|
* greater than a byte size. You must implement a comparator that
|
|
* takes the whole element and performs comparison in such a case.
|
|
*
|
|
* The comparator should return 0 if the data are the same, a negative
|
|
* integer if the first data is less than the second data, a positive
|
|
* integer otherwise.
|
|
*
|
|
*/
|
|
typedef int (*hawk_arr_comper_t) (
|
|
hawk_arr_t* arr /* array */,
|
|
const void* dptr1 /* data pointer */,
|
|
hawk_oow_t dlen1 /* data length */,
|
|
const void* dptr2 /* data pointer */,
|
|
hawk_oow_t dlen2 /* data length */
|
|
);
|
|
|
|
/**
|
|
* The hawk_arr_keeper_t type defines a value keeper that is called when
|
|
* a value is retained in the context that it should be destroyed because
|
|
* it is identical to a new value. Two values are identical if their beginning
|
|
* pointers and their lengths are equal.
|
|
*/
|
|
typedef void (*hawk_arr_keeper_t) (
|
|
hawk_arr_t* arr /**< array */,
|
|
void* vptr /**< pointer to a value */,
|
|
hawk_oow_t vlen /**< length of a value */
|
|
);
|
|
|
|
/**
|
|
* The hawk_arr_sizer_t type defines an array size claculator that is called
|
|
* when the array needs to be resized.
|
|
*/
|
|
typedef hawk_oow_t (*hawk_arr_sizer_t) (
|
|
hawk_arr_t* arr, /**< array */
|
|
hawk_oow_t hint /**< sizing hint */
|
|
);
|
|
|
|
|
|
typedef struct hawk_arr_style_t hawk_arr_style_t;
|
|
|
|
struct hawk_arr_style_t
|
|
{
|
|
hawk_arr_copier_t copier; /* data copier */
|
|
hawk_arr_freeer_t freeer; /* data freeer */
|
|
hawk_arr_comper_t comper; /* data comparator */
|
|
hawk_arr_keeper_t keeper; /* data keeper */
|
|
hawk_arr_sizer_t sizer; /* size calculator */
|
|
};
|
|
|
|
/**
|
|
* The hawk_arr_style_kind_t type defines the type of predefined
|
|
* callback set for pair manipulation.
|
|
*/
|
|
enum hawk_arr_style_kind_t
|
|
{
|
|
/** store element pointers */
|
|
HAWK_ARR_STYLE_DEFAULT,
|
|
/** copy elements */
|
|
HAWK_ARR_STYLE_INLINE_COPIER
|
|
};
|
|
|
|
typedef enum hawk_arr_style_kind_t hawk_arr_style_kind_t;
|
|
|
|
|
|
typedef hawk_arr_walk_t (*hawk_arr_walker_t) (
|
|
hawk_arr_t* arr /* array */,
|
|
hawk_oow_t index /* index to the visited slot */,
|
|
void* ctx /* user-defined context */
|
|
);
|
|
|
|
/**
|
|
* The hawk_arr_t type defines a linear dynamic array.
|
|
*/
|
|
struct hawk_arr_t
|
|
{
|
|
hawk_gem_t* gem;
|
|
const hawk_arr_style_t* style;
|
|
hawk_uint8_t scale; /* scale factor */
|
|
hawk_oow_t heap_pos_offset; /* offset in the data element where position
|
|
* is stored when heap operation is performed. */
|
|
hawk_oow_t size; /* number of items */
|
|
hawk_oow_t tally; /* number of items set */
|
|
hawk_oow_t capa; /* capacity */
|
|
hawk_arr_slot_t** slot;
|
|
};
|
|
|
|
/**
|
|
* The hawk_arr_slot_t type defines a linear dynamic array slot
|
|
*/
|
|
struct hawk_arr_slot_t
|
|
{
|
|
hawk_ptl_t val;
|
|
};
|
|
|
|
#if defined(__cplusplus)
|
|
extern "C" {
|
|
#endif
|
|
|
|
/**
|
|
* The hawk_get_arr_style() functions returns a predefined callback set for
|
|
* pair manipulation.
|
|
*/
|
|
HAWK_EXPORT const hawk_arr_style_t* hawk_get_arr_style (
|
|
hawk_arr_style_kind_t kind
|
|
);
|
|
|
|
/**
|
|
* The hawk_arr_open() function creates a linear dynamic array.
|
|
*/
|
|
HAWK_EXPORT hawk_arr_t* hawk_arr_open (
|
|
hawk_gem_t* gem,
|
|
hawk_oow_t ext, /**< extension size in bytes */
|
|
hawk_oow_t capa /**< initial array capacity */
|
|
);
|
|
|
|
/**
|
|
* The hawk_arr_close() function destroys a linear dynamic array.
|
|
*/
|
|
HAWK_EXPORT void hawk_arr_close (
|
|
hawk_arr_t* arr /**< array */
|
|
);
|
|
|
|
/**
|
|
* The hawk_arr_init() function initializes a linear dynamic array.
|
|
*/
|
|
HAWK_EXPORT int hawk_arr_init (
|
|
hawk_arr_t* arr,
|
|
hawk_gem_t* gem,
|
|
hawk_oow_t capa
|
|
);
|
|
|
|
/**
|
|
* The hawk_arr_fini() function finalizes a linear dynamic array.
|
|
*/
|
|
HAWK_EXPORT void hawk_arr_fini (
|
|
hawk_arr_t* arr /**< array */
|
|
);
|
|
|
|
#if defined(HAWK_HAVE_INLINE)
|
|
static HAWK_INLINE void* hawk_arr_getxtn (hawk_arr_t* arr) { return (void*)(arr + 1); }
|
|
#else
|
|
#define hawk_arr_getxtn(arr) ((void*)((hawk_arr_t*)(arr) + 1))
|
|
#endif
|
|
|
|
/**
|
|
* The hawk_arr_getscale() function returns the scale factor
|
|
*/
|
|
HAWK_EXPORT int hawk_arr_getscale (
|
|
hawk_arr_t* arr /**< array */
|
|
);
|
|
|
|
/**
|
|
* The hawk_arr_setscale() function sets the scale factor of the length
|
|
* of a key and a value. A scale factor determines the actual length of
|
|
* a key and a value in bytes. A arr is created with a scale factor of 1.
|
|
* The scale factor should be larger than 0 and less than 256.
|
|
* It is a bad idea to change the scale factor when \a arr is not empty.
|
|
*/
|
|
HAWK_EXPORT void hawk_arr_setscale (
|
|
hawk_arr_t* arr /**< array */,
|
|
int scale /**< scale factor - 1 to 255 */
|
|
);
|
|
|
|
HAWK_EXPORT hawk_arr_copier_t hawk_arr_getcopier (
|
|
hawk_arr_t* arr /* array */
|
|
);
|
|
|
|
|
|
HAWK_EXPORT void hawk_arr_setstyle (
|
|
hawk_arr_t* arr,
|
|
const hawk_arr_style_t* style
|
|
);
|
|
|
|
HAWK_EXPORT const hawk_arr_style_t* hawk_arr_getstyle (
|
|
hawk_arr_t* arr
|
|
);
|
|
|
|
HAWK_EXPORT hawk_oow_t hawk_arr_getsize (
|
|
hawk_arr_t* arr
|
|
);
|
|
|
|
HAWK_EXPORT hawk_oow_t hawk_arr_getcapa (
|
|
hawk_arr_t* arr
|
|
);
|
|
|
|
HAWK_EXPORT hawk_arr_t* hawk_arr_setcapa (
|
|
hawk_arr_t* arr,
|
|
hawk_oow_t capa
|
|
);
|
|
|
|
HAWK_EXPORT hawk_oow_t hawk_arr_search (
|
|
hawk_arr_t* arr,
|
|
hawk_oow_t pos,
|
|
const void* dptr,
|
|
hawk_oow_t dlen
|
|
);
|
|
|
|
HAWK_EXPORT hawk_oow_t hawk_arr_rsearch (
|
|
hawk_arr_t* arr,
|
|
hawk_oow_t pos,
|
|
const void* dptr,
|
|
hawk_oow_t dlen
|
|
);
|
|
|
|
HAWK_EXPORT hawk_oow_t hawk_arr_upsert (
|
|
hawk_arr_t* arr,
|
|
hawk_oow_t index,
|
|
void* dptr,
|
|
hawk_oow_t dlen
|
|
);
|
|
|
|
HAWK_EXPORT hawk_oow_t hawk_arr_insert (
|
|
hawk_arr_t* arr,
|
|
hawk_oow_t index,
|
|
void* dptr,
|
|
hawk_oow_t dlen
|
|
);
|
|
|
|
HAWK_EXPORT hawk_oow_t hawk_arr_update (
|
|
hawk_arr_t* arr,
|
|
hawk_oow_t pos,
|
|
void* dptr,
|
|
hawk_oow_t dlen
|
|
);
|
|
|
|
/**
|
|
* The hawk_arr_delete() function deletes the as many data as the count
|
|
* from the index. It returns the number of data deleted.
|
|
*/
|
|
HAWK_EXPORT hawk_oow_t hawk_arr_delete (
|
|
hawk_arr_t* arr,
|
|
hawk_oow_t index,
|
|
hawk_oow_t count
|
|
);
|
|
|
|
/**
|
|
* The hawk_arr_uplete() function deletes data slot without compaction.
|
|
* It returns the number of data affected.
|
|
*/
|
|
HAWK_EXPORT hawk_oow_t hawk_arr_uplete (
|
|
hawk_arr_t* arr,
|
|
hawk_oow_t index,
|
|
hawk_oow_t count
|
|
);
|
|
|
|
HAWK_EXPORT void hawk_arr_clear (
|
|
hawk_arr_t* arr
|
|
);
|
|
|
|
/**
|
|
* The hawk_arr_walk() function calls the \a walker function for each
|
|
* element in the array beginning from the first. The \a walker function
|
|
* should return one of #HAWK_ARR_WALK_FORWARD, #HAWK_ARR_WALK_BACKWARD,
|
|
* #HAWK_ARR_WALK_STOP.
|
|
* \return number of calls to the \a walker fucntion made
|
|
*/
|
|
HAWK_EXPORT hawk_oow_t hawk_arr_walk (
|
|
hawk_arr_t* arr,
|
|
hawk_arr_walker_t walker,
|
|
void* ctx
|
|
);
|
|
|
|
/**
|
|
* The hawk_arr_rwalk() function calls the \a walker function for each
|
|
* element in the array beginning from the last. The \a walker function
|
|
* should return one of #HAWK_ARR_WALK_FORWARD, #HAWK_ARR_WALK_BACKWARD,
|
|
* #HAWK_ARR_WALK_STOP.
|
|
* \return number of calls to the \a walker fucntion made
|
|
*/
|
|
HAWK_EXPORT hawk_oow_t hawk_arr_rwalk (
|
|
hawk_arr_t* arr,
|
|
hawk_arr_walker_t walker,
|
|
void* ctx
|
|
);
|
|
|
|
/**
|
|
* The hawk_arr_pushstack() function appends data to the array. It is a utility
|
|
* function to allow stack-like operations over an array. To do so, you should
|
|
* not play with other non-stack related functions.
|
|
*/
|
|
HAWK_EXPORT hawk_oow_t hawk_arr_pushstack (
|
|
hawk_arr_t* arr,
|
|
void* dptr,
|
|
hawk_oow_t dlen
|
|
);
|
|
|
|
/**
|
|
* The hawk_arr_popstack() function deletes the last array data. It is a utility
|
|
* function to allow stack-like operations over an array. To do so, you should
|
|
* not play with other non-stack related functions.
|
|
* \note You must not call this function if \a arr is empty.
|
|
*/
|
|
HAWK_EXPORT void hawk_arr_popstack (
|
|
hawk_arr_t* arr
|
|
);
|
|
|
|
/**
|
|
* The hawk_arr_pushheap() function inserts data to an array while keeping the
|
|
* largest data at position 0. It is a utiltiy funtion to implement a binary
|
|
* max-heap over an array. Inverse the comparator to implement a min-heap.
|
|
* \return number of array elements
|
|
* \note You must not mess up the array with other non-heap related functions
|
|
* to keep the heap property.
|
|
*/
|
|
HAWK_EXPORT hawk_oow_t hawk_arr_pushheap (
|
|
hawk_arr_t* arr,
|
|
void* dptr,
|
|
hawk_oow_t dlen
|
|
);
|
|
|
|
/**
|
|
* The hawk_arr_popheap() function deletes data at position 0 while keeping
|
|
* the largest data at positon 0. It is a utiltiy funtion to implement a binary
|
|
* max-heap over an array.
|
|
* \note You must not mess up the array with other non-heap related functions
|
|
* to keep the heap property.
|
|
*/
|
|
HAWK_EXPORT void hawk_arr_popheap (
|
|
hawk_arr_t* arr
|
|
);
|
|
|
|
HAWK_EXPORT void hawk_arr_deleteheap (
|
|
hawk_arr_t* arr,
|
|
hawk_oow_t index
|
|
);
|
|
|
|
HAWK_EXPORT hawk_oow_t hawk_arr_updateheap (
|
|
hawk_arr_t* arr,
|
|
hawk_oow_t index,
|
|
void* dptr,
|
|
hawk_oow_t dlen
|
|
);
|
|
|
|
HAWK_EXPORT hawk_oow_t hawk_arr_getheapposoffset (
|
|
hawk_arr_t* arr
|
|
);
|
|
|
|
/**
|
|
* The hawk_arr_setheapposoffset() function sets the offset to a position holding
|
|
* field within a data element. It assumes that the field is of the hawk_oow_t type.
|
|
*
|
|
* \code
|
|
* struct data_t
|
|
* {
|
|
* int v;
|
|
* hawk_oow_t pos;
|
|
* };
|
|
* struct data_t d;
|
|
* hawk_arr_setheapposoffset (arr, HAWK_OFFSETOF(struct data_t, pos));
|
|
* d.v = 20;
|
|
* hawk_arr_pushheap (arr, &d, 1);
|
|
* \endcode
|
|
*
|
|
* In the code above, the 'pos' field of the first element in the array must be 0.
|
|
*
|
|
* If it's set to HAWK_ARR_NIL, position is not updated when heapification is
|
|
* performed.
|
|
*/
|
|
HAWK_EXPORT void hawk_arr_setheapposoffset (
|
|
hawk_arr_t* arr,
|
|
hawk_oow_t offset
|
|
);
|
|
|
|
|
|
|
|
/**
|
|
* The hawk_arr_dflcomp() function is the default comparator
|
|
*/
|
|
HAWK_EXPORT int hawk_arr_dflcomp (
|
|
hawk_arr_t* arr,
|
|
const void* dptr1,
|
|
hawk_oow_t dlen1,
|
|
const void* dptr2,
|
|
hawk_oow_t dlen2
|
|
);
|
|
|
|
#if defined(__cplusplus)
|
|
}
|
|
#endif
|
|
|
|
#endif
|