ascend/general/pairlist.h

/*  ASCEND modelling environment
    Copyright (C) 2006 Benjamin Andrew Allan
    Copyright (C) 2006 Carnegie Mellon University

    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, 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, see <http://www.gnu.org/licenses/>.
*//** @defgroup general_pairlist General Pointer-pair manager

    This module uses (internally) a pair of gl_list_t
    to manage pointer pairs.

    The following definitions provide a quick-and-dirty pointer lookup by
    pointer key. The lookup is order N. The table does not treat NULL keys
    or values specially. elements of the pairlist are numbered [1..length].
*//*
    by Benjamin Andrew Allan, 10/2006
    Dates:        10/2006 - original version
*/

#ifndef ASC_PAIRLIST_H
#define ASC_PAIRLIST_H
#include <ascend/utilities/config.h>
#include "platform.h"
#include <stdio.h>

/** @addtogroup general_pairlist General Pointer-pair Manager
    @{
*/

struct pairlist_t;
struct gl_list_t;

#define pairlist_DEBUG FALSE
/**<
 *  Flag controlling extra checking of the pairlist management routines.
 *  Setting pairlist_DEBUG to TRUE causes the pairlist_store routines to do
 *  some RATHER expensive checking. It should be set to FALSE.
 */

ASC_DLLSPEC struct pairlist_t * pairlist_create(unsigned long capacity);
/**<
 *  Creates and returns a new pairlist.
 *  Complexity O(1).
 *
 *  @param capacity the initial capacity of the list; the initial size is 0.
 *
 *  @return A pointer to the newly created pairlist, NULL if an error occurred.
 */

ASC_DLLSPEC void *pairlist_keyAt(struct pairlist_t * pl, unsigned long eindex);
/**<
 *  Get the key at eindex'th element of the list.
 *  Complexity O(1).
 *  @return the value pointer.
 */

ASC_DLLSPEC void *pairlist_valueAt(struct pairlist_t * pl, unsigned long eindex);
/**<
 *  Get the value at eindex'th element of the list.
 *  Complexity O(1).
 *  @return the value pointer.
 */

ASC_DLLSPEC unsigned long pairlist_contains(struct pairlist_t * pl, void *key);
/**<
 *  Return the index of the key, if it is in the list, or 0 if not.
 *  Complexity O(n).
 *  @return the key index.
 */

ASC_DLLSPEC unsigned long pairlist_append(struct pairlist_t * pl, void *key, void * value);
/**<
 *  Add a pair to the list. Uniqueness not guaranteed. Complexity O(1).
 *  @return the key index.
 */

ASC_DLLSPEC unsigned long pairlist_append_unique(struct pairlist_t * pl, void *key, void * value);
/**<
 *  Add a pair to the list. Uniqueness of key guaranteed. If duplicate,
 *  value is ignored. Complexity O(n).
 *  @return the key index.
 */

ASC_DLLSPEC void *pairlist_set(struct pairlist_t *pl, void *key, void *value);
/**<
    Add a pair to the list. If duplicate, old value is overwritten with new value.
    If an old value was found, its pointer is returned (so that the user can
    destroy the dereferenced data if required). If no old value was found with
    this key, NULL is returned.
*/

ASC_DLLSPEC void pairlist_clear(struct pairlist_t * pl);
/**<
 *  Forget the previous contents of a list.
 *  @param the list to clear.
 */

ASC_DLLSPEC void pairlist_destroy(struct pairlist_t * pl);
/**<
 *  Deallocates everything associated with the pl.
 *  @param pl The pairlist store to destroy.
 */

ASC_DLLSPEC struct gl_list_t *pairlist_values_and_destroy(struct pairlist_t *pl);
/**<
    Return the 'values' list from the pairlist, and destroy the
    pairlist object.
*/

ASC_DLLSPEC long pairlist_length(struct pairlist_t * pl);
/**<
 *  @return the amount of data in the list.
 *  @param pl The pairlist store to destroy.
 */

extern void pairlist_print(FILE *fp, struct pairlist_t * pl);
/**<
 *  Prints statistics about a struct pairlist_t * to the file stream given.
 *
 *  @param fp     The open file stream on which to print the report.
 *  @param pl     The pairlist store on which to report.
 */

/* @} */

#endif /* ASC_PAIRLIST_H */

1	/* ASCEND modelling environment
2	Copyright (C) 2006 Benjamin Andrew Allan
3	Copyright (C) 2006 Carnegie Mellon University
4
5	This program is free software; you can redistribute it and/or modify
6	it under the terms of the GNU General Public License as published by
7	the Free Software Foundation; either version 2, or (at your option)
8	any later version.
9
10	This program is distributed in the hope that it will be useful,
11	but WITHOUT ANY WARRANTY; without even the implied warranty of
12	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13	GNU General Public License for more details.
14
15	You should have received a copy of the GNU General Public License
16	along with this program. If not, see <http://www.gnu.org/licenses/>.
17	//* @defgroup general_pairlist General Pointer-pair manager
18
19	This module uses (internally) a pair of gl_list_t
20	to manage pointer pairs.
21
22	The following definitions provide a quick-and-dirty pointer lookup by
23	pointer key. The lookup is order N. The table does not treat NULL keys
24	or values specially. elements of the pairlist are numbered [1..length].
25	//
26	by Benjamin Andrew Allan, 10/2006
27	Dates: 10/2006 - original version
28	*/
29
30	#ifndef ASC_PAIRLIST_H
31	#define ASC_PAIRLIST_H
32	#include <ascend/utilities/config.h>
33	#include "platform.h"
34	#include <stdio.h>
35
36	/** @addtogroup general_pairlist General Pointer-pair Manager
37	@{
38	*/
39
40	struct pairlist_t;
41	struct gl_list_t;
42
43	#define pairlist_DEBUG FALSE
44	/**<
45	* Flag controlling extra checking of the pairlist management routines.
46	* Setting pairlist_DEBUG to TRUE causes the pairlist_store routines to do
47	* some RATHER expensive checking. It should be set to FALSE.
48	*/
49
50	ASC_DLLSPEC struct pairlist_t * pairlist_create(unsigned long capacity);
51	/**<
52	* Creates and returns a new pairlist.
53	* Complexity O(1).
54	*
55	* @param capacity the initial capacity of the list; the initial size is 0.
56	*
57	* @return A pointer to the newly created pairlist, NULL if an error occurred.
58	*/
59
60	ASC_DLLSPEC void pairlist_keyAt(struct pairlist_t pl, unsigned long eindex);
61	/**<
62	* Get the key at eindex'th element of the list.
63	* Complexity O(1).
64	* @return the value pointer.
65	*/
66
67	ASC_DLLSPEC void pairlist_valueAt(struct pairlist_t pl, unsigned long eindex);
68	/**<
69	* Get the value at eindex'th element of the list.
70	* Complexity O(1).
71	* @return the value pointer.
72	*/
73
74	ASC_DLLSPEC unsigned long pairlist_contains(struct pairlist_t * pl, void *key);
75	/**<
76	* Return the index of the key, if it is in the list, or 0 if not.
77	* Complexity O(n).
78	* @return the key index.
79	*/
80
81	ASC_DLLSPEC unsigned long pairlist_append(struct pairlist_t * pl, void key, void value);
82	/**<
83	* Add a pair to the list. Uniqueness not guaranteed. Complexity O(1).
84	* @return the key index.
85	*/
86
87	ASC_DLLSPEC unsigned long pairlist_append_unique(struct pairlist_t * pl, void key, void value);
88	/**<
89	* Add a pair to the list. Uniqueness of key guaranteed. If duplicate,
90	* value is ignored. Complexity O(n).
91	* @return the key index.
92	*/
93
94	ASC_DLLSPEC void pairlist_set(struct pairlist_t pl, void key, void value);
95	/**<
96	Add a pair to the list. If duplicate, old value is overwritten with new value.
97	If an old value was found, its pointer is returned (so that the user can
98	destroy the dereferenced data if required). If no old value was found with
99	this key, NULL is returned.
100	*/
101
102	ASC_DLLSPEC void pairlist_clear(struct pairlist_t * pl);
103	/**<
104	* Forget the previous contents of a list.
105	* @param the list to clear.
106	*/
107
108	ASC_DLLSPEC void pairlist_destroy(struct pairlist_t * pl);
109	/**<
110	* Deallocates everything associated with the pl.
111	* @param pl The pairlist store to destroy.
112	*/
113
114	ASC_DLLSPEC struct gl_list_t pairlist_values_and_destroy(struct pairlist_t pl);
115	/**<
116	Return the 'values' list from the pairlist, and destroy the
117	pairlist object.
118	*/
119
120	ASC_DLLSPEC long pairlist_length(struct pairlist_t * pl);
121	/**<
122	* @return the amount of data in the list.
123	* @param pl The pairlist store to destroy.
124	*/
125
126	extern void pairlist_print(FILE fp, struct pairlist_t pl);
127	/**<
128	* Prints statistics about a struct pairlist_t * to the file stream given.
129	*
130	* @param fp The open file stream on which to print the report.
131	* @param pl The pairlist store on which to report.
132	*/
133
134	/* @} */
135
136	#endif /* ASC_PAIRLIST_H */
137