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

/**********************************************************************************************************************
 * DEFINE
 */
#define TJD_SYS_SLIST_INIT_VALUE               { .next = NULL }
#define TJD_SYS_SLIST_ITEM_INIT_VALUE          { .next = NULL }


#define TJD_SYS_SLIST_FOR_EACH(list, item)     for (item = (list)->next; item != NULL; item = item->next)


/** @brief The single-linked list.
 *  @note The list is not thread safe, take care of multi-threading in usage.
 */
typedef struct _tjd_sys_slist_item_t {
    struct _tjd_sys_slist_item_t  *next;
} tjd_sys_slist_item_t, tjd_sys_slist_t;

/** @brief Handler for freeing the memory of item.
 *  @param[in] item The pointer to #tjd_sys_slist_item_t.
 *  @param[in] cntx The context pointer for this handle.
 *  @return None.
 */
typedef void (*slist_free_handle_t)(tjd_sys_slist_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_slist_item_t.
 *  @param[in] item_b The pointer to another #tjd_sys_slist_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 (*slist_cmpr_handle_t)(const tjd_sys_slist_item_t *item_a, const tjd_sys_slist_item_t *item_b);

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


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

/** @fn tjd_sys_slist_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_slist_t.
 *  @return None.
 */
extern void  tjd_sys_slist_destroy(tjd_sys_slist_t *list, 
    slist_free_handle_t free_handle, void *cntx);

/** @fn tjd_sys_slist_item_init
 *  @brief Initialize an item.
 *  @param[in] list The pointer to #tjd_sys_slist_t.
 *  @return None.
 */
extern void  tjd_sys_slist_item_init(tjd_sys_slist_item_t *item);

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

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

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

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

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

/** @fn tjd_sys_slist_sort
 *  @brief Sort the list(Bubble Sort is utilized right now).
 *  @param[in] list The pointer to #tjd_sys_slist_t.
 *  @param[in] ascend 1 if sort in ascending order.
 *  @param[in] cmpr_handle The handler for comparing two items.
 *  @param[in] swap_handle The handler for swapping two items.
 */
extern void  tjd_sys_slist_sort(tjd_sys_slist_t *list, 
    uint32_t ascend, slist_cmpr_handle_t cmpr_handle, slist_swap_handle_t swap_handle);

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

/** @fn tjd_sys_slist_find_pre_item
 *  @brief Find the item in list and return pre item.
 *  @param[in] list The pointer to #tjd_sys_slist_t.
 *  @param[in] item The pointer to #tjd_sys_slist_item_t.
 *  @param[in] cmpr_handle The handler for comparing two items.
 *  @return pre item.
 */
extern void *tjd_sys_slist_find_pre_item(tjd_sys_slist_t *list, 
    tjd_sys_slist_item_t *item, slist_cmpr_handle_t cmpr_handle);

/** @fn tjd_sys_slist_remove_first
 *  @brief Remove the first item from list.
 *  @param[in] list The pointer to #tjd_sys_slist_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_slist_remove_first(tjd_sys_slist_t *list, 
    slist_free_handle_t free_handle, void *cntx);

/** @fn tjd_sys_slist_remove_last
 *  @brief Remove the last item from list.
 *  @param[in] list The pointer to #tjd_sys_slist_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_slist_remove_last(tjd_sys_slist_t *list, 
    slist_free_handle_t free_handle, void *cntx);

/** @fn tjd_sys_slist_remove_item
 *  @brief Remove the specific item from list.
 *  @param[in] list The pointer to #tjd_sys_slist_t.
 *  @param[in] free_handle The handler for destroying item;
 *  @param[in] cmpr_handle The handler for comparing two items, 
 *                         pointer will be compared if NULL.
 *  @param[in] cntx The context pointer for free_handle.
 *  @return true is find, false is find fail.
 */
bool tjd_sys_slist_remove_item_ret(tjd_sys_slist_t *list, tjd_sys_slist_item_t *item, 
    slist_cmpr_handle_t cmpr_handle, slist_free_handle_t free_handle, void *cntx);

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

#endif /* _SYS_SINGLE_LIST_H_ */
/**********************************************************************************************************************
 * EOF
 */
/** @} */