---

gnn_node_vector.c

Go to the documentation of this file.

/***************************************************************************
 *  @file gnn_node_vector.c
 *  @brief gnn_node_vector Implementation.
 *
 *  @date   : 30-09-03 20:18
 *  @author : Pedro Ortega C. <peortega@dcc.uchile.cl>
 *  Copyright  2003  Pedro Ortega C.
 ****************************************************************************/
/*
 *  This program is free software; you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation; either version 2 of the License, or
 *  (at your option) any later version.
 *
 *  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 the
 *  GNU Library General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with this program; if not, write to the Free Software
 *  Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
 */

/**
 * @defgroup gnn_node_vector_doc gnn_node_vector : Vector of nodes.
 * @ingroup gnn_node_doc
 *
 * A node vector is a vector which can contain \em pointers to nodes.
 *
 * Node vectors are defined by a \ref gnn_node_vector structure which
 * describes a slice of an array of \ref gnn_node pointers. Different
 * vectors can be created which point to the same block. A vector
 * slice is a set of equally-spaced elements of an area of memory.
 *
 * The \ref gnn_node_vector structure contains five components,
 * the size, the stride, a pointer to the memory where the elements are stored, data, a pointer to the block owned by the vector, block, if any, and an ownership flag, owner. The structure is very simple and looks like this,
 *
 * \code
 * typedef struct
 * {
 *     size_t size;
 *     size_t stride;
 *     size_t blocksize;
 *     double * data;
 *     int owner;
 * } gnn_node_vector;
 * \endcode
 *
 * The \em size corresponds to the number of vector elements. The valid indices
 * are 0, 1, 2, ..., \em size-1. The \em stride is the step size from one
 * element to another in physical memory, measured in \c sizeof(gnn_node*).
 * The pointer \em data points to the first vector element. If the vector
 * own this pointer array, i.e. if it was created and will be destroyed with
 * it, then \em owner is equal to 1. If it doesn't own the array, then
 * \em owner is 0, and at deallocation of the \ref gnn_node_vector, the
 * array isn't deallocated. The \em blocksize field measures the number of
 * memory units that the vector spans.
 */



/******************************************/
/* Include Files                          */
/******************************************/

#include "gnn_node.h"



/******************************************/
/* Public Interface                       */
/******************************************/

/**
 * @brief Creates a new \ref gnn_node vector.
 * @ingroup gnn_node_vector_doc
 *
 * This function creates a new vector with NULL pointers of size \c size.
 * The underlying memory block will be owned by the vector.
 *
 * @param  size The number of elements.
 * @return A pointer to a new \ref gnn_node_vector.
 */
gnn_node_vector *
gnn_node_vector_new (size_t size)
{
    gnn_node_vector *v;
    
    assert (size > 1);
    
    /* alloc node */
    v = (gnn_node_vector *) malloc (sizeof (*v));
    if (v == NULL)
    {
        GSL_ERROR_VAL ("couldn't allocate memory for gnn_node_vector",
                       GSL_ENOMEM, NULL);
    }

    /* allocate block */
    v->data = (gnn_node **) calloc (sizeof (gnn_node *) * size, 1);
    if (v->data == NULL)
    {
        gnn_node_vector_destroy_all (v);
        GSL_ERROR_VAL ("couldn't allocate memory for gnn_node_vector block",
                       GSL_ENOMEM, NULL);
    }

    /* set internal fields */
    v->size      = size;
    v->stride    = 1;
    v->blocksize = size;
    v->owner     = 1;
    
    return v;
}

/**
 * @brief Frees \ref gnn_node vector.
 * @ingroup gnn_node_vector_doc
 *
 * This function frees the memory of a \ref gnn_node_vector. The pointed
 * nodes won't be destroyed.
 *
 * @param  v A pointer to a \ref gnn_node_vector.
 */
void
gnn_node_vector_free (gnn_node_vector *v)
{
    size_t j;

    assert (v != NULL);

    free (v->data);
    free (v);
}

/**
 * @brief Frees \ref gnn_node vector and the pointed nodes.
 * @ingroup gnn_node_vector_doc
 *
 * This function frees the memory of a \ref gnn_node_vector and destroys all
 * its pointed nodes by calling \ref gnn_node_destroy on each one of them.
 *
 * @param  v A pointer to a \ref gnn_node_vector.
 */
void
gnn_node_vector_destroy_all (gnn_node_vector *v)
{
    size_t j;

    assert (v != NULL);

    if (v->data != NULL)
    {
        for (j=0; j<v->size; ++j)
        {
            if (v->data[j * v->stride] != NULL)
                gnn_node_destroy (v->data[j * v->stride]);
        }
    }
    free (v->data);
    free (v);
}

/**
 * @brief Gets an element.
 * @ingroup gnn_node_vector_doc
 *
 * This function returns the pointer located at the i-th position.
 *
 * @param  v A pointer to a \ref gnn_node_vector.
 * @param  i The index of the element to be retrieved.
 * @Return Returns the i-th elements, which can point to a node or NULL.
 */
gnn_node *
gnn_node_vector_get (gnn_node_vector *v, size_t i)
{
    assert (v != NULL);

    if (i < 0 || v->size <= i)
        GSL_ERROR_VAL ("access out of bounds", GSL_EINVAL, NULL);

    return v->data[i * v->stride];
}

/**
 * @brief Sets an element.
 * @ingroup gnn_node_vector_doc
 *
 * This function sets a new value for the element located at the i-th position.
 * It should be a pointer to a valid \ref gnn_node or NULL. You should be
 * carefull and not delete a needed pointer in order to not lose memory.
 *
 * @param  v A pointer to a \ref gnn_node_vector.
 * @param  i The index of the element to be retrieved.
 * @param  n A pointer to a \ref gnn_node or NULL.
 * @Return Returns 0 if succeeded.
 */
int
gnn_node_vector_set (gnn_node_vector *v, size_t i, gnn_node *n)
{
    assert (v != NULL);

    if (i < 0 || v->size <= i)
        GSL_ERROR ("access out of bounds", GSL_EINVAL);

    v->data[i * v->stride] = n;

    return 0;
}

/**
 * @brief Checks if vector is null.
 * @ingroup gnn_node_vector_doc
 *
 * This function returns 1 if all elements are equal to  NULL.
 *
 * @param  v A pointer to a \ref gnn_node_vector.
 * @Return Returns 1 (null) or 0 (not null).
 */
int
gnn_node_vector_isnull (gnn_node_vector *v)
{
    size_t j;

    assert (v != NULL);

    for (j=0; j<v->size; ++j)
    {
        if (v->data[j * v->stride] != NULL)
            return 0;
    }

    return 1;
}

/**
 * @brief Returns the number of elements pointing to a node.
 * @ingroup gnn_node_vector_doc
 *
 * This function counts the number of elements pointing to a non-NULL location.
 *
 * @param  v A pointer to a \ref gnn_node_vector.
 * @Return Returns the count.
 */
size_t
gnn_node_vector_count_nodes (gnn_node_vector *v)
{
    size_t i;
    size_t count;

    assert (v != NULL);

    /* count the number of non-null nodes */
    count = 0;
    for (i=0; i<v->size; ++i)
        if (gnn_node_vector_get (v, i) != NULL)
            count++;
            
    return count;
}

/**
 * @brief Swap two vectors.
 * @ingroup gnn_node_vector_doc
 *
 * This function swaps the elements of the node vectors. This is accomplished
 * by interchanging its underlying arrays.
 *
 * @param  v A pointer to a \ref gnn_node_vector.
 * @param  w A pointer to a \ref gnn_node_vector.
 * @Return Returns 0 if succeeded.
 */
int
gnn_node_vector_swap (gnn_node_vector *v, gnn_node_vector *w)
{
    gnn_node_vector n;

    assert (v != NULL);
    assert (w != NULL);

     n = *v;
    *v = *w;
    *w =  n;

    return 0;
}

/**
 * @brief Swap two vector elements.
 * @ingroup gnn_node_vector_doc
 *
 * This function swaps the element located at \c i with the element located
 * at position \c j.
 *
 * @param  v A pointer to a \ref gnn_node_vector.
 * @param  i An index.
 * @param  j An index.
 * @Return Returns 0 if succeeded.
 */
int
gnn_node_vector_swap_elements (gnn_node_vector *v, size_t i, size_t j)
{
    gnn_node *n;

    assert (v != NULL);

    if ( i < 0 || v->size <= i || j < 0 || v->size <= j )
        GSL_ERROR ("access out of bounds", GSL_EINVAL);

    n = v->data[i * v->stride];
    v->data[i * v->stride] = v->data[j * v->stride];
    v->data[j * v->stride] = n;

    return 0;
}

/**
 * @brief Reverse a vector's elements.
 * @ingroup gnn_node_vector_doc
 *
 * @param  v A pointer to a \ref gnn_node_vector.
 * @Return Returns 0 if succeeded.
 */
int
gnn_node_vector_reverse (gnn_node_vector *v)
{
    size_t j;
    
    assert (v != NULL);
    
    for (j=0; j<v->size / 2; ++j)
    {
        gnn_node_vector_swap_elements (v, j, v->size - j - 1);
    }
    
    return 0;
}

/**
 * @brief Duplicate a vector.
 * @ingroup gnn_node_vector_doc
 *
 * This function duplicates a given vector, by creating a new fresh one
 * pointing to the same nodes.
 *
 * @param  v A pointer to a \ref gnn_node_vector.
 * @Return A pointer to a new \ref gnn_node_vector or NULL if failed.
 */
gnn_node_vector *
gnn_node_vector_dup (gnn_node_vector *v)
{
    gnn_node_vector *w;
    
    assert (v != NULL);

    w = gnn_node_vector_new (v->size);
    if (w == NULL)
    {
        GSL_ERROR_VAL ("couldn't allocate memory for duplicate",
                       GSL_ENOMEM, NULL);
    }
    
    gnn_node_vector_copy (w, v);
    
    return w;
}

/**
 * @brief Copy a vector.
 * @ingroup gnn_node_vector_doc
 *
 * This function copies the elements of the vector \c w into \c v.
 *
 * @param  v A pointer to a destiny \ref gnn_node_vector.
 * @param  v A pointer to a source \ref gnn_node_vector.
 * @Return Returns 0 if succeeded.
 */
int
gnn_node_vector_copy (gnn_node_vector *v, const gnn_node_vector *w)
{
    size_t j;
    
    assert (v != NULL);
    assert (w != NULL);
    
    if (v->size != w->size)
    {
        GSL_ERROR ("vectors should be of the same size", GSL_EINVAL);
    }
    
    for (j=0; j<v->size; ++j)
    {
        v->data[j * v->stride] = w->data[j * w->stride];
    }
    
    return 0;
}



/* Views */

/**
 * @brief Creates a subvector view of a vector.
 * @ingroup gnn_node_vector_doc
 *
 * This function creates a subvector view of the given vector, starting at \c i
 * and ending at \c n. The returned gnn_node_view contains a \c vector field,
 * where the subvector will be stored. To obtain a pointer of this vector,
 * use the \c "&" operator:
 *
 * \code
 * gnn_node_vector_view view;
 * gnn_node_vector *w;
 *
 * // v is a pointer to a gnn_node_vector
 * view = gnn_node_vector_subvector (v, 2, 5);
 *
 * // get a pointer
 * w = &(view.vector);
 * \endcode
 *
 * @param  v A pointer to a \ref gnn_node_vector.
 * @param  i The starting index.
 * @param  n The size of the subvector.
 * @Return Returns a vector view.
 */
gnn_node_vector_view
gnn_node_vector_subvector (gnn_node_vector *v, size_t i, size_t n)
{
    return gnn_node_vector_subvector_with_stride (v, i, 1, n);
}

/**
 * @brief Creates a subvector view of a vector.
 * @ingroup gnn_node_vector_doc
 *
 * This function creates a subvector view of the given vector, starting at \c i
 * and ending at \c n, with stride \c stride. The returned gnn_node_view
 * contains a \c vector field,
 * where the subvector will be stored. To obtain a pointer of this vector,
 * use the \c "&" operator:
 *
 * \code
 * gnn_node_vector_view view;
 * gnn_node_vector *w;
 *
 * // obtain a view of the first 5 odd elements of the vector v
 * view = gnn_node_vector_subvector_with_stride (v, 1, 2, 5);
 *
 * // get a pointer
 * w = &(view.vector);
 * \endcode
 *
 * @param  v A pointer to a \ref gnn_node_vector.
 * @param  i The starting index.
 * @param  stried The stride.
 * @param  n The size of the subvector.
 * @Return Returns a vector view.
 */
gnn_node_vector_view
gnn_node_vector_subvector_with_stride (gnn_node_vector *v,
                                       size_t i,
                                       size_t stride,
                                       size_t n)
{
    size_t bn; /* required block size */
    gnn_node_vector_view view;

    assert (v != NULL);

    /* clear view */
    view.vector.size      = 0;
    view.vector.stride    = 0;
    view.vector.blocksize = 0;
    view.vector.data      = NULL;
    view.vector.owner     = 0;

    /* compute required block size */
    bn = n * stride - stride + 1;

    /* check bounds */
    if (i < 0 || v->size <= i)
    {
        GSL_ERROR_VAL ("starting index out of bounds", GSL_EINVAL, view);
    }
    if (i+bn < 0 || v->size <= i+bn)
    {
        GSL_ERROR_VAL ("the required subvector doesn't fit into the vector",
                       GSL_EINVAL, view);
    }

    /* set view */
    view.vector.size      = n;
    view.vector.stride    = stride * v->stride;
    view.vector.blocksize = (n-1) * view.vector.stride + 1;
    view.vector.data      = &(v->data[i * v->stride]);

    return view;
}

---