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

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

Parent Directory Parent Directory | Revision Log Revision Log


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

1 johnpye 1031 /* 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 jpye 2648 along with this program. If not, see <http://www.gnu.org/licenses/>.
17 jpye 2383 *//** @defgroup general_pairlist General Pointer-pair manager
18 johnpye 1031
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 jpye 3258 by Benjamin Andrew Allan, 10/2006
27 johnpye 1031 Dates: 10/2006 - original version
28     */
29    
30 jpye 1498 #ifndef ASC_PAIRLIST_H
31     #define ASC_PAIRLIST_H
32 jpye 3258 #include <ascend/utilities/config.h>
33     #include "platform.h"
34     #include <stdio.h>
35 johnpye 1031
36 jpye 2316 /** @addtogroup general_pairlist General Pointer-pair Manager
37     @{
38     */
39    
40 johnpye 1031 struct pairlist_t;
41 jpye 1929 struct gl_list_t;
42 johnpye 1031
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 johnpye 1063 ASC_DLLSPEC struct pairlist_t * pairlist_create(unsigned long capacity);
51 johnpye 1031 /**<
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 johnpye 1063 ASC_DLLSPEC void *pairlist_keyAt(struct pairlist_t * pl, unsigned long eindex);
61 johnpye 1031 /**<
62     * Get the key at eindex'th element of the list.
63     * Complexity O(1).
64     * @return the value pointer.
65     */
66    
67 johnpye 1063 ASC_DLLSPEC void *pairlist_valueAt(struct pairlist_t * pl, unsigned long eindex);
68 johnpye 1031 /**<
69     * Get the value at eindex'th element of the list.
70     * Complexity O(1).
71     * @return the value pointer.
72     */
73    
74 johnpye 1063 ASC_DLLSPEC unsigned long pairlist_contains(struct pairlist_t * pl, void *key);
75 johnpye 1031 /**<
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 johnpye 1063 ASC_DLLSPEC unsigned long pairlist_append(struct pairlist_t * pl, void *key, void * value);
82 johnpye 1031 /**<
83     * Add a pair to the list. Uniqueness not guaranteed. Complexity O(1).
84     * @return the key index.
85     */
86    
87 johnpye 1063 ASC_DLLSPEC unsigned long pairlist_append_unique(struct pairlist_t * pl, void *key, void * value);
88 johnpye 1031 /**<
89 jpye 3410 * Add a pair to the list. Uniqueness of key guaranteed. If key is a duplicate,
90 johnpye 1031 * value is ignored. Complexity O(n).
91     * @return the key index.
92     */
93    
94 jpye 1929 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 johnpye 1031
102 johnpye 1063 ASC_DLLSPEC void pairlist_clear(struct pairlist_t * pl);
103 johnpye 1031 /**<
104     * Forget the previous contents of a list.
105     * @param the list to clear.
106     */
107    
108 johnpye 1063 ASC_DLLSPEC void pairlist_destroy(struct pairlist_t * pl);
109 johnpye 1031 /**<
110     * Deallocates everything associated with the pl.
111     * @param pl The pairlist store to destroy.
112     */
113    
114 jpye 1929 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 johnpye 1063 ASC_DLLSPEC long pairlist_length(struct pairlist_t * pl);
121 johnpye 1031 /**<
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 jpye 2316 /* @} */
135    
136 jpye 1498 #endif /* ASC_PAIRLIST_H */
137 johnpye 1031

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