/* SPDX-License-Identifier: LGPL-2.1-only OR BSD-3-Clause */
/******************************************************************************
 *
 * This file is provided under a dual license.  When you use or
 * distribute this software, you may choose to be licensed under
 * version 2.1 of the GNU Lesser General Public License
 * ("LGPLv2.1 License") or BSD License.
 *
 * LGPLv2.1 License
 *
 * Copyright(C) 2019 MediaTek Inc.
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of version 2.1 of the GNU Lesser General Public
 * License as published by the Free Software Foundation.
 *
 * This program is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 * See https://www.gnu.org/licenses/old-licenses/lgpl-2.1.html for more
 * details.
 *
 * BSD LICENSE
 *
 * Copyright(C) 2019 MediaTek Inc.
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 *  * Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 *  * 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.
 *  * Neither the name of the copyright holder nor the names of its
 *    contributors may be used to endorse or promote products derived
 *    from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "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 COPYRIGHT
 * HOLDER OR CONTRIBUTORS 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.
 *
 *****************************************************************************/

/*! @file c_sort_search.h
 * $Revision: #1 $
 * $Date: 2015/05/29 $
 * $Author: brianpc.huang $
 *
 * @par Description: 
 *         This header file contains sorting and searching function API for
 *         the applications.
 *         
 *---------------------------------------------------------------------------*/

/*----------------------------------------------------------------------------*/
/*! @addtogroup groupMW_UTIL
  *  @{  
  */
/*----------------------------------------------------------------------------*/
#ifndef _C_SORT_SEARCH_H_
#define _C_SORT_SEARCH_H_

/*---------------------------------------------------------------------------
                    include files
----------------------------------------------------------------------------*/

#include "u_sort_search.h"

/*-------------------------------------------------------------------------
                    functions declarations
 --------------------------------------------------------------------------*/

/*
  Quicksort function.
*/
/*------------------------------------------------------------------*/
/*! @brief  This API executes quick sort function.
*  @param [in]   pv_array           Input array to be sorted.
*  @param [in]   z_num_elem      Number of element in the 'pv_array'.
*  @param [in]   z_size_of_elem  The size of individual element in the 'pv_array'.
*  @param [in]   pf_cmp_fct        Compare function to compare two elements in 'pv_array'.
*  @param [in]   pv_opt_param    Optional parameters pass to the compare function.
*  @param [out] pv_array           Array with elements sorted.
*  @retval      -SSR_OK                     Routine successful.
*  @retval      -SSR_INV_ARG            pv_array is NULL, or z_num_elem is 0, or z_size_of_elem is 0, or pf_cmp_fct is NULL.
*  @retval      -SSR_OUT_OF_MEM     Can not allocate internal memory for the sorting function.
*/
/*------------------------------------------------------------------*/ 
extern INT32 c_qsort
(
    VOID*            pv_array,
    SIZE_T           z_num_elem,
    SIZE_T           z_size_of_elem,
    x_sort_cmp_fct   pf_cmp_fct,
    VOID*            pv_opt_param
);

/*
  Binary search function.
*/
/*------------------------------------------------------------------*/
/*! @brief  This API perform perform a recursive search on sorted array.
*              If the input list, 'pv_array' is not sorted or is not sorted
*              using the same key parameter as for searching, then this API
*              will failed.
*  @param [in]   pv_array               Address of the array containing sorted elements.
*                                                   The sorted elements can be an array of sorted
*                                                   indices into a array object.
*  @param [in]   z_num_elem          Count of element in the 'pv_array' array.
*  @param [in]   z_size_of_elem       Size of element in the 'pv_array' array.
*  @param [in]   pf_cmp_fct             A function that compare the element of
*                                                    'pv_array' array and the search parameter
*                                                    value. Note: if the 'pv_array' array
*                                                    contains indices to the object array, the
*                                                    comparison is performed between the 'actual'
*                                                    object and the search key parameter..
*  @param [in]   pv_search_param    Parameter used to search the object array.
*  @param [in]   i4_idx                     Specifies the index into element in 
*                                                     the 'pv_array' with the same 'pv_search_key' 
*                                                     value to be returned from the search operation.
*  @param [in]   pv_opt_param         Pointer to the optional parameter passed to the compare function.
*  @param [out]  pi4_result              Variable to store the index in element
*                                                    in 'pv_array' array that match the search
*                                                    parameter.
*  @retval      -SSR_OK                     Routine successful.
*  @retval      -SSR_INV_ARG            pv_array is NULL, or z_num_elem is 0, or z_size_of_elem is 0, or pf_cmp_fct is NULL.
*  @retval      -SSR_OUT_OF_MEM     Can not allocate internal memory for the sorting function.
*/
/*------------------------------------------------------------------*/
extern INT32 c_binary_search
(
    const VOID*      pv_array,
    SIZE_T           z_num_elem,
    SIZE_T           z_size_of_elem,
    x_search_cmp_fct pf_cmp_fct,
    const VOID*      pv_search_param,
    INT32            i4_idx,
    VOID*            pv_opt_param,
    INT32*           pi4_result
);

#endif /* _C_SORT_SEARCH_H_ */


/*----------------------------------------------------------------------------*/
/*! @} */                                               /* end of groupMW_UTIL*/
/*----------------------------------------------------------------------------*/


