Merge branch 'rightlib' into mergelibs-241019-1758

1 files changed, 276 insertions, 0 deletions

diff --git a/contrib/libs/c-ares/src/lib/include/ares_array.h b/contrib/libs/c-ares/src/lib/include/ares_array.h
new file mode 100644
index 0000000000..f1a2e155f3
--- /dev/null
+++ b/contrib/libs/c-ares/src/lib/include/ares_array.h
@@ -0,0 +1,276 @@
+/* MIT License
+ *
+ * Copyright (c) 2024 Brad House
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice (including the next
+ * paragraph) shall be included in all copies or substantial portions of the
+ * Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ *
+ * SPDX-License-Identifier: MIT
+ */
+#ifndef __ARES__ARRAY_H
+#define __ARES__ARRAY_H
+
+#include "ares.h"
+
+/*! \addtogroup ares_array Array Data Structure
+ *
+ * This is an array with helpers.  It is meant to have as little overhead
+ * as possible over direct array management by applications but to provide
+ * safety and some optimization features.  It can also return the array in
+ * native form once all manipulation has been performed.
+ *
+ * @{
+ */
+
+struct ares_array;
+
+/*! Opaque data structure for array */
+typedef struct ares_array ares_array_t;
+
+/*! Callback to free user-defined member data
+ *
+ *  \param[in] data  pointer to member of array to be destroyed. The pointer
+ *                   itself must not be destroyed, just the data it contains.
+ */
+typedef void (*ares_array_destructor_t)(void *data);
+
+/*! Callback to compare two array elements used for sorting
+ *
+ *  \param[in] data1 array member 1
+ *  \param[in] data2 array member 2
+ *  \return < 0 if data1 < data2, > 0 if data1 > data2, 0 if data1 == data2
+ */
+typedef int (*ares_array_cmp_t)(const void *data1, const void *data2);
+
+/*! Create an array object
+ *
+ *  NOTE: members of the array are typically going to be an going to be a
+ *        struct with compiler/ABI specific padding to ensure proper alignment.
+ *        Care needs to be taken if using primitive types, especially floating
+ *        point numbers which size may not indicate the required alignment.
+ *        For example, a double may be 80 bits (10 bytes), but required
+ *        alignment of 16 bytes.  In such a case, a member_size of 16 would be
+ *        required to be used.
+ *
+ *  \param[in] destruct     Optional. Destructor to call on a removed member
+ *  \param[in] member_size  Size of array member, usually determined using
+ *                          sizeof() for the member such as a struct.
+ *
+ *  \return array object or NULL on out of memory
+ */
+CARES_EXTERN ares_array_t *ares_array_create(size_t member_size,
+                                             ares_array_destructor_t destruct);
+
+
+/*! Request the array be at least the requested size.  Useful if the desired
+ *  array size is known prior to populating the array to prevent reallocations.
+ *
+ *  \param[in] arr  Initialized array object.
+ *  \param[in] size Minimum number of members
+ *  \return ARES_SUCCESS on success, ARES_EFORMERR on misuse,
+ *    ARES_ENOMEM on out of memory */
+CARES_EXTERN ares_status_t ares_array_set_size(ares_array_t *arr, size_t size);
+
+/*! Sort the array using the given comparison function.  This is not
+ *  persistent, any future elements inserted will not maintain this sort.
+ *
+ *  \param[in]  arr      Initialized array object.
+ *  \param[in]  cb       Sort callback
+ *  \return ARES_SUCCESS on success
+ */
+CARES_EXTERN ares_status_t ares_array_sort(ares_array_t    *arr,
+                                           ares_array_cmp_t cmp);
+
+/*! Destroy an array object.  If a destructor is set, will be called on each
+ *  member of the array.
+ *
+ *  \param[in] arr     Initialized array object.
+ */
+CARES_EXTERN void          ares_array_destroy(ares_array_t *arr);
+
+/*! Retrieve the array in the native format.  This will also destroy the
+ *  container.  It is the responsibility of the caller to free the returned
+ *  pointer and also any data within each array element.
+ *
+ *  \param[in] arr  Initialized array object
+ *  \param[out] num_members the number of members in the returned array
+ *  \return pointer to native array on success, NULL on failure.
+ */
+CARES_EXTERN void  *ares_array_finish(ares_array_t *arr, size_t *num_members);
+
+/*! Retrieve the number of members in the array
+ *
+ *  \param[in] arr     Initialized array object.
+ *  \return numbrer of members
+ */
+CARES_EXTERN size_t ares_array_len(const ares_array_t *arr);
+
+/*! Insert a new array member at the given index
+ *
+ *  \param[out] elem_ptr Optional. Pointer to the returned array element.
+ *  \param[in]  arr      Initialized array object.
+ *  \param[in]  idx      Index in array to place new element, will shift any
+ *                       elements down that exist after this point.
+ *  \return ARES_SUCCESS on success, ARES_EFORMERR on bad index,
+ *          ARES_ENOMEM on out of memory.
+ */
+CARES_EXTERN ares_status_t ares_array_insert_at(void        **elem_ptr,
+                                                ares_array_t *arr, size_t idx);
+
+/*! Insert a new array member at the end of the array
+ *
+ *  \param[out] elem_ptr Optional. Pointer to the returned array element.
+ *  \param[in]  arr      Initialized array object.
+ *  \return ARES_SUCCESS on success, ARES_ENOMEM on out of memory.
+ */
+CARES_EXTERN ares_status_t ares_array_insert_last(void        **elem_ptr,
+                                                  ares_array_t *arr);
+
+/*! Insert a new array member at the beginning of the array
+ *
+ *  \param[out] elem_ptr Optional. Pointer to the returned array element.
+ *  \param[in]  arr      Initialized array object.
+ *  \return ARES_SUCCESS on success, ARES_ENOMEM on out of memory.
+ */
+CARES_EXTERN ares_status_t ares_array_insert_first(void        **elem_ptr,
+                                                   ares_array_t *arr);
+
+
+/*! Insert a new array member at the given index and copy the data pointed
+ *  to by the data pointer into the array.  This will copy member_size bytes
+ *  from the provided pointer, this may not be safe for some data types
+ *  that may have a smaller size than the provided member_size which includes
+ *  padding as discussed in ares_array_create().
+ *
+ *  \param[in]  arr      Initialized array object.
+ *  \param[in]  idx      Index in array to place new element, will shift any
+ *                       elements down that exist after this point.
+ *  \param[in]  data_ptr Pointer to data to copy into array.
+ *  \return ARES_SUCCESS on success, ARES_EFORMERR on bad index or null data
+ * ptr, ARES_ENOMEM on out of memory.
+ */
+CARES_EXTERN ares_status_t ares_array_insertdata_at(ares_array_t *arr,
+                                                    size_t        idx,
+                                                    const void   *data_ptr);
+
+/*! Insert a new array member at the end of the array and copy the data pointed
+ *  to by the data pointer into the array.  This will copy member_size bytes
+ *  from the provided pointer, this may not be safe for some data types
+ *  that may have a smaller size than the provided member_size which includes
+ *  padding as discussed in ares_array_create().
+ *
+ *  \param[in]  arr      Initialized array object.
+ *  \param[in]  data_ptr Pointer to data to copy into array.
+ *  \return ARES_SUCCESS on success, ARES_EFORMERR on bad index or null data
+ * ptr, ARES_ENOMEM on out of memory.
+ */
+CARES_EXTERN ares_status_t ares_array_insertdata_last(ares_array_t *arr,
+                                                      const void   *data_ptr);
+
+/*! Insert a new array member at the beginning of the array and copy the data
+ * pointed to by the data pointer into the array.  This will copy member_size
+ * bytes from the provided pointer, this may not be safe for some data types
+ *  that may have a smaller size than the provided member_size which includes
+ *  padding as discussed in ares_array_create().
+ *
+ *  \param[in]  arr      Initialized array object.
+ *  \param[in]  data_ptr Pointer to data to copy into array.
+ *  \return ARES_SUCCESS on success, ARES_EFORMERR on bad index or null data
+ * ptr, ARES_ENOMEM on out of memory.
+ */
+CARES_EXTERN ares_status_t ares_array_insertdata_first(ares_array_t *arr,
+                                                       const void   *data_ptr);
+
+/*! Fetch a pointer to the given element in the array
+ *  \param[in]  array  Initialized array object
+ *  \param[in]  idx    Index to fetch
+ *  \return pointer on success, NULL on failure */
+CARES_EXTERN void         *ares_array_at(ares_array_t *arr, size_t idx);
+
+/*! Fetch a pointer to the first element in the array
+ *  \param[in]  array  Initialized array object
+ *  \return pointer on success, NULL on failure */
+CARES_EXTERN void         *ares_array_first(ares_array_t *arr);
+
+/*! Fetch a pointer to the last element in the array
+ *  \param[in]  array  Initialized array object
+ *  \return pointer on success, NULL on failure */
+CARES_EXTERN void         *ares_array_last(ares_array_t *arr);
+
+/*! Fetch a constant pointer to the given element in the array
+ *  \param[in]  array  Initialized array object
+ *  \param[in]  idx    Index to fetch
+ *  \return pointer on success, NULL on failure */
+CARES_EXTERN const void   *ares_array_at_const(const ares_array_t *arr,
+                                               size_t              idx);
+
+/*! Fetch a constant pointer to the first element in the array
+ *  \param[in]  array  Initialized array object
+ *  \return pointer on success, NULL on failure */
+CARES_EXTERN const void   *ares_array_first_const(const ares_array_t *arr);
+
+/*! Fetch a constant pointer to the last element in the array
+ *  \param[in]  array  Initialized array object
+ *  \return pointer on success, NULL on failure */
+CARES_EXTERN const void   *ares_array_last_const(const ares_array_t *arr);
+
+/*! Claim the data from the specified array index, copying it to the buffer
+ *  provided by the caller.  The index specified in the array will then be
+ *  removed (without calling any possible destructor)
+ *
+ *  \param[in,out] dest      Optional. Buffer to hold array member. Pass NULL
+ *                           if not needed.  This could leak memory if array
+ *                           member needs destructor if not provided.
+ *  \param[in]     dest_size Size of buffer provided, used as a sanity check.
+ *                           Must match member_size provided to
+ *                           ares_array_create() if dest_size specified.
+ *  \param[in]     arr       Initialized array object
+ *  \param[in]     idx       Index to claim
+ *  \return ARES_SUCCESS on success, ARES_EFORMERR on usage failure.
+ */
+CARES_EXTERN ares_status_t ares_array_claim_at(void *dest, size_t dest_size,
+                                               ares_array_t *arr, size_t idx);
+
+/*! Remove the member at the specified array index.  The destructor will be
+ *  called.
+ *
+ *  \param[in] arr  Initialized array object
+ *  \param[in] idx  Index to remove
+ *  \return ARES_SUCCESS if removed, ARES_EFORMERR on invalid use
+ */
+CARES_EXTERN ares_status_t ares_array_remove_at(ares_array_t *arr, size_t idx);
+
+/*! Remove the first member of the array.
+ *
+ *  \param[in] arr  Initialized array object
+ *  \return ARES_SUCCESS if removed, ARES_EFORMERR on invalid use
+ */
+CARES_EXTERN ares_status_t ares_array_remove_first(ares_array_t *arr);
+
+/*! Remove the last member of the array.
+ *
+ *  \param[in] arr  Initialized array object
+ *  \return ARES_SUCCESS if removed, ARES_EFORMERR on invalid use
+ */
+CARES_EXTERN ares_status_t ares_array_remove_last(ares_array_t *arr);
+
+
+/*! @} */
+
+#endif /* __ARES__ARRAY_H */