/* Copyright 2006 Garrett Rooney.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 * @file etl_array.h
 * @brief Functions for manipulating variable length arrays
 */

#ifndef ETL_ARRAY_H
#define ETL_ARRAY_H

#include <stdbool.h>
#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */

/** A variable length array. */
typedef struct etl_array_t etl_array_t;

/** Create a new array, with initial capacity @a capacity. */
etl_array_t *etl_array_create(uint32_t capacity);

/** A callback function for use while destroying an array. */
typedef void (*etl_array_elt_destroy_t)(void *elt, void *baton);

/** Destroy @a arr, calling @a destroy with @a baton on each element. */
void
etl_array_destroy(etl_array_t *arr,
                  etl_array_elt_destroy_t destroy,
                  void *baton);

/** Return the number of elements in @a arr. */
uint32_t etl_array_nelts(const etl_array_t *arr);

/**
 * Return the element at @a idx in @a arr, or @c NULL if @a idx is
 * larger than the maximum element in @a arr.
 */
const void *etl_array_idx(const etl_array_t *arr, uint32_t idx);

/** Push @a item onto @a arr. */
void etl_array_push(etl_array_t *arr, void *item);

/** Pop an item off of @a arr. */
void *etl_array_pop(etl_array_t *arr);

#ifdef __cplusplus
}
#endif /* __cplusplus */

#endif /* ETL_ARRAY_H */