/[ascend]/trunk/ascend/general/pairlist.h
ViewVC logotype

Contents of /trunk/ascend/general/pairlist.h

Parent Directory Parent Directory | Revision Log Revision Log


Revision 2011 - (show annotations) (download) (as text)
Tue Apr 28 08:58:48 2009 UTC (15 years ago) by jpye
File MIME type: text/x-chdr
File size: 4289 byte(s)
Moving libascend components from #/base/generic into #/ascend
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, write to the Free Software
17 Foundation, Inc., 59 Temple Place - Suite 330,
18 Boston, MA 02111-1307, USA.
19 *//** @file
20 Ascend pointer pair manager.
21
22 This module uses (internally) a pair of gl_list_t
23 to manage pointer pairs.
24
25 The following definitions provide a quick-and-dirty pointer lookup by
26 pointer key. The lookup is order N. The table does not treat NULL keys
27 or values specially. elements of the pairlist are numbered [1..length].
28
29 Requires:
30 #include <stdio.h>
31 #include "utilities/ascConfig.h"
32 #include "compiler.h"
33 *//*
34 by Benjamin Andrew Allan
35 Created: 10/2006
36
37 Dates: 10/2006 - original version
38 */
39
40 #ifndef ASC_PAIRLIST_H
41 #define ASC_PAIRLIST_H
42
43 struct pairlist_t;
44 struct gl_list_t;
45
46 #define pairlist_DEBUG FALSE
47 /**<
48 * Flag controlling extra checking of the pairlist management routines.
49 * Setting pairlist_DEBUG to TRUE causes the pairlist_store routines to do
50 * some RATHER expensive checking. It should be set to FALSE.
51 */
52
53 ASC_DLLSPEC struct pairlist_t * pairlist_create(unsigned long capacity);
54 /**<
55 * Creates and returns a new pairlist.
56 * Complexity O(1).
57 *
58 * @param capacity the initial capacity of the list; the initial size is 0.
59 *
60 * @return A pointer to the newly created pairlist, NULL if an error occurred.
61 */
62
63 ASC_DLLSPEC void *pairlist_keyAt(struct pairlist_t * pl, unsigned long eindex);
64 /**<
65 * Get the key at eindex'th element of the list.
66 * Complexity O(1).
67 * @return the value pointer.
68 */
69
70 ASC_DLLSPEC void *pairlist_valueAt(struct pairlist_t * pl, unsigned long eindex);
71 /**<
72 * Get the value at eindex'th element of the list.
73 * Complexity O(1).
74 * @return the value pointer.
75 */
76
77 ASC_DLLSPEC unsigned long pairlist_contains(struct pairlist_t * pl, void *key);
78 /**<
79 * Return the index of the key, if it is in the list, or 0 if not.
80 * Complexity O(n).
81 * @return the key index.
82 */
83
84 ASC_DLLSPEC unsigned long pairlist_append(struct pairlist_t * pl, void *key, void * value);
85 /**<
86 * Add a pair to the list. Uniqueness not guaranteed. Complexity O(1).
87 * @return the key index.
88 */
89
90 ASC_DLLSPEC unsigned long pairlist_append_unique(struct pairlist_t * pl, void *key, void * value);
91 /**<
92 * Add a pair to the list. Uniqueness of key guaranteed. If duplicate,
93 * value is ignored. Complexity O(n).
94 * @return the key index.
95 */
96
97 ASC_DLLSPEC void *pairlist_set(struct pairlist_t *pl, void *key, void *value);
98 /**<
99 Add a pair to the list. If duplicate, old value is overwritten with new value.
100 If an old value was found, its pointer is returned (so that the user can
101 destroy the dereferenced data if required). If no old value was found with
102 this key, NULL is returned.
103 */
104
105 ASC_DLLSPEC void pairlist_clear(struct pairlist_t * pl);
106 /**<
107 * Forget the previous contents of a list.
108 * @param the list to clear.
109 */
110
111 ASC_DLLSPEC void pairlist_destroy(struct pairlist_t * pl);
112 /**<
113 * Deallocates everything associated with the pl.
114 * @param pl The pairlist store to destroy.
115 */
116
117 ASC_DLLSPEC struct gl_list_t *pairlist_values_and_destroy(struct pairlist_t *pl);
118 /**<
119 Return the 'values' list from the pairlist, and destroy the
120 pairlist object.
121 */
122
123 ASC_DLLSPEC long pairlist_length(struct pairlist_t * pl);
124 /**<
125 * @return the amount of data in the list.
126 * @param pl The pairlist store to destroy.
127 */
128
129 extern void pairlist_print(FILE *fp, struct pairlist_t * pl);
130 /**<
131 * Prints statistics about a struct pairlist_t * to the file stream given.
132 *
133 * @param fp The open file stream on which to print the report.
134 * @param pl The pairlist store on which to report.
135 */
136
137 #endif /* ASC_PAIRLIST_H */
138

john.pye@anu.edu.au
ViewVC Help
Powered by ViewVC 1.1.22