/*----------------------------------------------------------------------------
 * Copyright (c) TJD Technologies Co., Ltd. 2020. All rights reserved.
 *
 * Description: sys_dlist.h 
 *
 * Author: saimen
 *
 * Create: 2024-4-24
 *--------------------------------------------------------------------------*/
#ifndef _SYS_DOUBLE_LIST_H_
#define _SYS_DOUBLE_LIST_H_
//lib
#include <stdint.h>

/**********************************************************************************************************************
 * DEFINE
 */
#define TJD_SYS_DLIST_INIT_VALUE                   { .next = NULL, .prev = NULL }
#define TJD_SYS_DLIST_ITEM_INIT_VALUE              { .next = NULL, .prev = NULL }
#define TJD_SYS_DLIST_ITEM_INIT(p_item)            do { (p_item)->next = NULL; (p_item)->prev = NULL; } while (0)
#define TJD_SYS_DLIST_INIT(list)                   do { (list)->prev = (list); (list)->next = (list); } while (0)

#define TJD_SYS_DLIST_FOR_EACH(curr_item, next_item, head) \
    for (curr_item = (head)->next, next_item = curr_item->next; \
         curr_item != (head); \
         curr_item = next_item, next_item = curr_item->next)

/** @brief Structure of an list and item of list. */
typedef struct _tjd_sys_dlist_item_t {
    struct _tjd_sys_dlist_item_t *prev;                            /**< Previous item */
    struct _tjd_sys_dlist_item_t *next;                            /**< Next item */
} tjd_sys_dlist_t, tjd_sys_dlist_item_t;

/** @brief Handler for freeing the memory of item.
 *  @param[in] item The pointer to #tjd_sys_dlist_item_t.
 *  @param[in] cntx The context pointer for this handle.
 *  @return None.
 */
typedef void (*dlist_free_handle_t)(tjd_sys_dlist_item_t *item, void *cntx);

/** @brief Handler for comparing the value of item_a to item_b.
 *  @param[in] item_a The pointer to #tjd_sys_dlist_item_t.
 *  @param[in] item_b The pointer to another #tjd_sys_dlist_item_t.
 *  @return  0 if item_a is equal to item_b,
 *          <0 if item_a is smaller than item_b,
 *          >0 if item is larger than item_b.
 */
typedef int (*dlist_cmpr_handle_t)(const tjd_sys_dlist_item_t *item_a, const tjd_sys_dlist_item_t *item_b);

/** @brief Handler for swapping the content of item.
 *  @param[in] item_a The pointer to #tjd_sys_dlist_item_t.
 *  @param[in] item_b The pointer to another #tjd_sys_dlist_item_t.
 *  @return None.
 */
typedef void (*dlist_swap_handle_t)(tjd_sys_dlist_item_t *item_a, tjd_sys_dlist_item_t *item_b);

/** @brief Handler for traverse the item.
 *  @param[in] item The pointer to #tjd_sys_dlist_item_t.
 *  @param[in] cntx The context pointer for this handle.
 *
 *  @note Don't touch the list structure.
 *
 *  @return None.
 */
typedef void (*dlist_trvs_handle_t)(tjd_sys_dlist_item_t *item, void *cntx);

/**********************************************************************************************************************
 * PUBLIC FUNCTION PROTOTYPES
 */
/** @fn tjd_sys_dlist_create
 *  @brief Create a list.
 *  @param[in] list The pointer to #tjd_sys_dlist_t.
 *  @return None.
 */
extern void  tjd_sys_dlist_create(tjd_sys_dlist_t *list);

/** @fn tjd_sys_dlist_destroy
 *  @brief Destroy a list.
 *  @param[in] free_handle The handler for free item;
 *  @param[in] cntx The context pointer for free_handle.
 *  @param[in] list The pointer to #tjd_sys_dlist_t.
 *  @return None.
 */
extern void  tjd_sys_dlist_destroy(tjd_sys_dlist_t *list, 
    dlist_free_handle_t free_handle, void *cntx);

/** @fn tjd_sys_dlist_append
 *  @brief Append an item to list.
 *  @param[in] list The pointer to #tjd_sys_dlist_t.
 *  @param[in] item The pointer to #tjd_sys_dlist_item_t.
 *  @return None.
 */
extern void  tjd_sys_dlist_append(tjd_sys_dlist_t *list, tjd_sys_dlist_item_t *item);

/** @fn tjd_sys_dlist_prepend
 *  @brief Prepend an item to list.
 *  @param[in] list The pointer to #tjd_sys_dlist_t.
 *  @param[in] item The pointer to #tjd_sys_dlist_item_t.
 *  @return None.
 */
extern void  tjd_sys_dlist_prepend(tjd_sys_dlist_t *list, tjd_sys_dlist_item_t *item);

/** @fn tjd_sys_dlist_remove
 *  @brief remove an item from list.
 *  @param[in] item The pointer to #tjd_sys_dlist_item_t.
 *  @return None.
 */
extern void  tjd_sys_dlist_remove(tjd_sys_dlist_item_t *item);

/** @fn tjd_sys_dlist_first
 *  @brief Get the first item from list.
 *  @param[in] list The pointer to #tjd_sys_dlist_t.
 *  @return The pointer to #tjd_sys_dlist_item_t.
 */
extern void *tjd_sys_dlist_first(tjd_sys_dlist_t *list);

/** @fn tjd_sys_dlist_last
 *  @brief Get the first item from list.
 *  @param[in] list The pointer to #tjd_sys_dlist_t.
 *  @return The pointer to #tjd_sys_dlist_item_t.
 */
extern void *tjd_sys_dlist_last(tjd_sys_dlist_t *list);

/** @fn tjd_sys_dlist_size
 *  @brief Get the size of list.
 *  @param[in] list The pointer to #tjd_sys_dlist_t.
 *  @return The item count of list.
 */
extern uint32_t tjd_sys_dlist_size(tjd_sys_dlist_t *list);

/** @fn tjd_sys_dlist_insert
 *  @brief Insert item to list(Bubble Sort is utilized right now).
 *  @param[in] list The pointer to #tjd_sys_dlist_t.
 *  @param[in] item The pointer to #tjd_sys_dlist_item_t.
 *  @param[in] ascend 1 if sort in ascending order.
 *  @param[in] cmpr_handle The handler for comparing two items.
 */
extern void  tjd_sys_dlist_insert(tjd_sys_dlist_t *list, 
    tjd_sys_dlist_item_t *item, uint32_t ascend, dlist_cmpr_handle_t cmpr_handle);

/** @fn tjd_sys_dlist_find
 *  @brief Find the item in list.
 *  @param[in] list The pointer to #tjd_sys_dlist_t.
 *  @param[in] item The pointer to #tjd_sys_dlist_item_t.
 *  @param[in] cmpr_handle The handler for comparing two items.
 *  @return NONE.
 */
extern void *tjd_sys_dlist_find(tjd_sys_dlist_t *list, 
    tjd_sys_dlist_item_t *item, dlist_cmpr_handle_t cmpr_handle);

/** @fn tjd_sys_dlist_remove_first
 *  @brief Remove the first item from list.
 *  @param[in] list The pointer to #tjd_sys_dlist_t.
 *  @param[in] free_handle The handler for destroying item;
 *  @param[in] cntx The context pointer for free_handle.
 *  @return NONE.
 */
extern void  tjd_sys_dlist_remove_first(tjd_sys_dlist_t *list, 
    dlist_free_handle_t free_handle, void *cntx);

/** @fn tjd_sys_dlist_remove_last
 *  @brief Remove the last item from list.
 *  @param[in] list The pointer to #tjd_sys_dlist_t.
 *  @param[in] free_handle The handler for destroying item;
 *  @param[in] cntx The context pointer for free_handle.
 *  @return NONE.
 */
extern void  tjd_sys_dlist_remove_last(tjd_sys_dlist_t *list, 
    dlist_free_handle_t free_handle, void *cntx);

/** @fn tjd_sys_dlist_remove_items
 *  @brief Remove the specific items from list.
 *  @param[in] list The pointer to #tjd_sys_dlist_t.
 *  @param[in] cmpr_handle The handler for comparing two items, 
 *                         pointer will be compared if NULL.
 *  @param[in] free_handle The handler for destroying item;
 *  @param[in] cntx The context pointer for free_handle.
 *  @return NONE.
 */
extern void  tjd_sys_dlist_remove_items(tjd_sys_dlist_t *list, tjd_sys_dlist_item_t *item, 
    dlist_cmpr_handle_t cmpr_handle, dlist_free_handle_t free_handle, void *cntx);

/** @fn tjd_sys_dlist_traverse
 *  @brief Traverse list.
 *  @param[in] list The pointer to #tjd_sys_dlist_t.
 *  @param[in] trvs_handle The handler for handling item.
 *  @param[in] cntx The context pointer for trvs_handle.
 *  @return NONE.
 */
extern void tjd_sys_dlist_traverse(tjd_sys_dlist_t *list, dlist_trvs_handle_t trvs_handle, void *cntx);

#endif /* _tjd_sys_DOUBLE_LIST_H_ */
/**********************************************************************************************************************
 * EOF
 */
/** @} */