temelia/release/include/vertex.h

/*!
 Temelia - graph_t vertex interface.

 Copyright (C) 2008, 2009 Ceata (http://cod.ceata.org/proiecte/temelia).

 @author Dascalu Laurentiu

 This program is free software; you can redistribute it and
 modify it under the terms of the GNU General Public License
 as published by the Free Software Foundation; either version 3
 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 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., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
 */

#ifndef VERTEX_H_
#define VERTEX_H_

#include "platform.h"
#include "graph_constants.h"

struct _vertex_t;
typedef struct _vertex_t *vertex_t;

/*!
 * @brief Returns a new vertex having label, identifier and key.
 * Complexity O(1)
 *
 * @param Label
 * @param Identifier
 * @param Key attached to vertex
 */
DECLSPEC vertex_t vertex_new(char *label, unsigned int identifier, void *key);

/*!
 * @brief Frees the memory occupied by vertex.
 * Complexity O(1)
 *
 * @param Vertex
 */
DECLSPEC void vertex_delete(vertex_t vertex);

/*!
 * @brief Returns vertex label.
 * Complexity O(1)
 *
 * @param Vertex
 */
DECLSPEC char *vertex_get_label(vertex_t vertex);

/*!
 * @brief Returns vertex cost.
 * Complexity O(1)
 *
 * @param Vertex
 */
DECLSPEC double vertex_get_cost(vertex_t vertex);

/*!
 * @brief Returns vertex identifier.
 * Complexity O(1)
 *
 * @param Vertex
 */
DECLSPEC unsigned int vertex_get_identifier(vertex_t vertex);

/*!
 * @brief Returns vertex key.
 * Complexity O(1)
 *
 * @param Vertex
 */
DECLSPEC void *vertex_get_key(vertex_t vertex);

/*!
 * @brief Returns vertex color.
 * Complexity O(1)
 *
 * @param Vertex
 */
DECLSPEC char vertex_get_color(vertex_t vertex);

/*!
 * @brief Returns 1 if vertex was visited and 0 if not.
 * Complexity O(1)
 *
 * @param Vertex
 */
DECLSPEC char vertex_get_visited(vertex_t vertex);

/*!
 * @brief Returns the parent identifier of this vertex.
 * Complexity O(1)
 *
 * @param Vertex
 */
DECLSPEC unsigned int vertex_get_parent_identifier(vertex_t vertex);

/*!
 * @brief Returns the time when the vertex was discovered.
 * Complexity O(1)
 *
 * @param Vertex
 */
DECLSPEC unsigned int vertex_get_time_start(vertex_t vertex);

/*!
 * @brief Returns the time when the vertex visitation ended.
 * Complexity O(1)
 *
 * @param Vertex
 */
DECLSPEC unsigned int vertex_get_time_stop(vertex_t vertex);

/*!
 * @brief Sets vertex label.
 * Complexity O(1)
 *
 * @param Vertex
 * @param Label reference
 */
DECLSPEC void vertex_set_label(vertex_t vertex, char *label);

/*!
 * @brief Sets vertex cost.
 * Complexity O(1)
 *
 * @param Vertex
 * @param Cost
 */
DECLSPEC void vertex_set_cost(vertex_t vertex, double cost);

/*!
 * @brief Sets vertex identifier.
 * Complexity O(1)
 *
 * @param Vertex
 * @param Identifier
 */
DECLSPEC void vertex_set_identifier(vertex_t vertex, unsigned int identifier);

/*!
 * @brief Sets vertex key.
 * Complexity O(1)
 *
 * @param Vertex
 * @param Key reference
 */
DECLSPEC void vertex_set_key(vertex_t vertex, void *key);

/*!
 * @brief Sets vertex color. You may use predefined color as WHITE, GRAY and BLACK.
 * Complexity O(1)
 *
 * @param Vertex
 * @param Color
 */
DECLSPEC void vertex_set_color(vertex_t vertex, char color);

/*!
 * @brief Sets vertex visited status. It's used by DFS/BFS travels and you may use it to implement
 * your own algorithms.
 * Complexity O(1)
 *
 * @param Vertex
 * @param Visited ( 1 ) or unvisited ( 0 ); actually node state depends on the program logic
 */
DECLSPEC void vertex_set_visited(vertex_t vertex, char visited);

/*!
 * @brief Sets the parent identifier of this vertex.
 * @param Vertex
 * @param Parent identifier
 */
DECLSPEC void vertex_set_parent_identifier(vertex_t vertex, unsigned int parent_identifier);

/*!
 * @brief Sets the time when the vertex was discovered.
 * Complexity O(1)
 *
 * @param Vertex
 * @param Time start value
 */
DECLSPEC void vertex_set_time_start(vertex_t vertex, unsigned int time_start);

/*!
 * @brief Sets the time when the vertex visitation ended.
 * Complexity O(1)
 *
 * @param Vertex
 * @param Time stop value
 */
DECLSPEC void vertex_set_time_stop(vertex_t vertex, unsigned int time_stop);

/*!
 * @brief Debugs vertex's content into stream.
 * Complexity O(1)
 *
 * @param Vertex
 * @param Stream, should be FILE *
 */
DECLSPEC void vertex_debug(vertex_t vertex, void *stream);

#endif /*VERTEX_H_*/