---

gnn_input.c

Go to the documentation of this file.

/***************************************************************************
 *  @file gnn_input.c
 *  @brief Input Implementation.
 *
 *  @date   : 21-09-03 19:47
 *  @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_input_doc gnn_input : Reading and handling of sets of vectors.
 * @ingroup libgnn_dataset
 *
 * The \ref gnn_input type defines a common interface for vector sets
 * handlers.
 *
 * \ref gnn_input datatypes are special objects that read and provide access
 * to sets of vectors. The raw \ref gnn_input structure defines a common
 * interface that should be implemented by extensions of this type. Typical
 * implementations can read vectors from files, memory, ports, etc.
 */



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

#include "gnn_input.h"
#include "gnn_utilities.h"


/******************************************/
/* Static Declaration                     */
/******************************************/

static int
gnn_input_default_reset (gnn_input *set);

void
gnn_input_default_destroy (gnn_input *set);



/******************************************/
/* Static Implementation                  */
/******************************************/

/**
 * @brief Default "reset" function for a input set.
 * @ingroup gnn_input_doc
 *
 * This function is the default "reset" function for a input set.
 * Actuallly, it doesn't anything.
 *
 * @param  set A pointer to a \ref gnn_input.
 * @return 0 if succeeded.
 */
static int
gnn_input_default_reset (gnn_input *set)
{
    assert (set != NULL);

    return 0;
}



/**
 * @brief Default "destroy" function for a dataset.
 * @ingroup gnn_input_doc
 *
 * This function is the default "destroy" function for an input set. It
 * assumes that there isn't any additional data for the specific dataset type,
 * so it actually just returns.
 *
 * @param  set A pointer to a \ref gnn_input.
 */
void
gnn_input_default_destroy (gnn_input *set)
{
    return;
}



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

/**
 * @brief Initializes a \ref gnn_input.
 * @ingroup gnn_input_doc
 *
 * This function initializes a given vector reader, setting its properties
 * and installing its functions.
 *
 * If the "reset", or "destroy" functions aren't provided, then the default
 * functions \ref gnn_input_default_reset and \ref gnn_input_default_destroy
 * are installed respectively. The "get" function is mandatory, and should
 * always be provided.
 *
 * As an example, suppose that you have made your own extension to the
 * \ref gnn_input datatype, one that reads from a serial port, which you
 * called "serial_reader". Also, suppose you have already coded the
 * appropiate "reset", "get" and "destroy" functions for your special
 * reader. Then,
 * \code
   serial_reader *myinput; // a pointer to the input reader to be created
   gnn_input     *set;     // a pointer to the same structure, but viewed as a
                           // gnn_input

   // allocate memory for the input reader
   myinput = (serial_reader *) malloc (sizeof (serial_reader));
   
   // view as a gnn_input
   set = (gnn_input *) myinput;

   // initialize the input (you know there are only 100 samples)
   gnn_input_init (set, 100, 5, serial_reader_reset,
                                serial_reader_get,
                                serial_reader_destroy);
 * \endcode
 * would initialize your input reader for 100 patterns, whose sample vectors
 * are of size 5.
 *
 * @param  set   A pointer to a \ref gnn_input.
 * @param  size  The number of samples that it contains.
 * @param  n     The size of the samples.
 * @param  reset   A pointer to the input's "reset" function.
 * @param  get     A pointer to the input's "get" function.
 * @param  destroy A pointer to the input's "destroy" function.
 * @return 0 if succeeded.
 */
int
gnn_input_init (gnn_input   *set,
                size_t       size,
                size_t       n,
                gnn_input_reset_type   reset,
                gnn_input_get_type     get,
                gnn_input_destroy_type destroy)
{
    assert (set != NULL);

    /* check sizes */
    if (size < 1)
    {
        GSL_ERROR ("input sets should contain a stricly positive number of"
                   "samples", GSL_EINVAL);
    }
    if (n < 1)
    {
        GSL_ERROR ("the samples should have a stricly positive number of"
                   "components", GSL_EINVAL);
    }

    /* check get function */
    if (get == NULL)
    {
        GSL_ERROR ("the \"get\" function is mandatory and should be provided",
                   GSL_EINVAL);
    }

    /* set fields */
    set->size    = size;
    set->n       = n;
    set->reset   = gnn_input_default_reset;
    set->get     = get;
    set->destroy = gnn_input_default_destroy;

    /* install functions */
    if (reset != NULL)
        set->reset = reset;
    if (destroy != NULL)
        set->destroy = destroy;

    return 0;
}


/**
 * @brief Destroy a \ref gnn_input.
 * @ingroup gnn_input_doc
 *
 * This function destroys the input reader.
 *
 * @param set A pointer to a \ref gnn_input.
 */
void
gnn_input_destroy (gnn_input *set)
{
    assert (set != NULL);

    set->destroy (set);
    free (set);
}

/**
 * @brief Reset a input set.
 * @ingroup gnn_input_doc
 *
 * This function resets the input handler.
 *
 * @param  set A pointer to a \ref gnn_input.
 * @return 0 if succeeded.
 */
int
gnn_input_reset (gnn_input *set)
{
    assert (set != NULL);

    set->reset (set);
}

/**
 * @brief Gets the k-th sample.
 * @ingroup gnn_input_doc
 *
 * This function returns a pointer to a buffer containing the k-th sample
 * vector. The content of the pointed vector will be valid until a next
 * function call on this input set.
 *
 * @param  set    A pointer to a \ref gnn_input.
 * @param  k      The index of the sample to be retrieved.
 * @return Returns a pointer to a buffer containing the sample vector, or
 *         NULL else.
 */
const gsl_vector *
gnn_input_get (gnn_input *set,
               size_t       k)
{
    assert (set != NULL);

    return set->get (set, k);
}

/**
 * @brief Gets the number of samples in the set.
 * @ingroup gnn_input_doc
 *
 * This function returns the set's size.
 *
 * @param  set A pointer to a \ref gnn_input.
 * @return Returns the size.
 */
size_t
gnn_input_get_size (gnn_input *set)
{
    assert (set != NULL);

    return set->size;
}

/**
 * @brief Gets the sample's size.
 * @ingroup gnn_input_doc
 *
 * This function returns the size of the samples.
 *
 * @param  set A pointer to a \ref gnn_input.
 * @return Returns the size.
 */
size_t
gnn_input_sample_get_size (gnn_input *set)
{
    assert (set != NULL);
    
    return set->n;
}

---