/*
 * This file is part of the Poliqarp suite.
 * 
 * Copyright (C) 2004-2009 by Instytut Podstaw Informatyki Polskiej
 * Akademii Nauk (IPI PAN; Institute of Computer Science, Polish
 * Academy of Sciences; cf. www.ipipan.waw.pl).  All rights reserved.
 * 
 * This file may be distributed and/or modified under the terms of the
 * GNU General Public License version 2 as published by the Free Software
 * Foundation and appearing in the file gpl.txt included in the packaging
 * of this file.  (See http://www.gnu.org/licenses/translations.html for
 * unofficial translations.)
 * 
 * A commercial license is available from IPI PAN (contact
 * Michal.Ciesiolka@ipipan.waw.pl or ipi@ipipan.waw.pl for more
 * information).  Licensees holding a valid commercial license from IPI
 * PAN may use this file in accordance with that license.
 * 
 * This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING
 * THE WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE.
 */

/**
 * @file vector.h
 * @brief Auto-resizing array holding integer values.
 *
 * A C++-style vector of integers that expands itself as needed.
 */

#ifndef POLIQARP_VECTOR_H
#define POLIQARP_VECTOR_H

#include <poliqarp-config.h>

/* Vector creation flags: */
#define VECTOR_DEFAULT  0  /**< Create a normal vector. */
#define VECTOR_ZERO     1  /**< Create a vector initially filled with zeros. */

/**
 * The vector structure.
 */
struct vector {
   uint32_t *data;   /**< The array proper. */
   size_t size;      /**< Number of elements allocated for the vector. */
   size_t used;      /**< Number of elements currently used. */
   int options;      /**< Flags of the vector, combination of VECTOR_*. */
};

/**
 * Create a new, empty vector.
 * @param v the vector to be created.
 * @param options options of the new vector.
 */
void vector_create(struct vector *v, int options);

/**
 * Free resources allocated for the vector.
 * @param v the vector to be destroyed.
 */
void vector_destroy(struct vector *v);

/**
 * Append an element to the end of the vector, resizing it if necessary.
 * @param v the vector to append new element to.
 * @param val the element to append.
 */
void vector_append(struct vector *v, uint32_t val);

/**
 * Retrieve an element from the vector. Attempt to pass an out-of-bounds
 * index to this function results in undefined behaviour.
 * @param v the vector to retrieve element from.
 * @param i index of the element to retrieve.
 * @return value of the element.
 */
uint32_t vector_get(const struct vector *v, size_t i);

/**
 * Store a value in the vector, resizing it if necessary.
 * @param v the vector to store a value in.
 * @param i index.
 * @param val value to store.
 */
void vector_set(struct vector *v, size_t i, uint32_t val);

/**
 * Increment an element of the vector.
 * @param v the vector.
 * @param i index of the element to be incremented.
 */
void vector_inc(struct vector *v, size_t i);

/**
 * Return the length of a vector.
 * @param v the vector.
 * @return length of vector v.
 */
size_t vector_length(const struct vector *v);

#endif /* POLIQARP_VECTOR_H */
