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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 3410 - (show annotations) (download) (as text)
Thu Jul 12 03:39:49 2018 UTC (4 years, 4 months ago) by jpye
File MIME type: text/x-chdr
File size: 4310 byte(s)
completing testing of pairlist

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 key is a 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

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