source: trunk/include/range_list.h @ 168

Last change on this file since 168 was 168, checked in by tim, 14 years ago

merged remaining smb_deps items into regfi

began formatting API comments for use with doxygen

  • Property svn:keywords set to Id
File size: 5.4 KB
Line 
1/**
2 * @file
3 *
4 * Copyright (C) 2008-2009 Timothy D. Morgan
5 *
6 * This program is free software; you can redistribute it and/or modify
7 * it under the terms of the GNU General Public License as published by
8 * the Free Software Foundation; version 3 of the License.
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., 675 Mass Ave, Cambridge, MA 02139, USA. 
18 *
19 * $Id: range_list.h 168 2010-03-03 00:08:42Z tim $
20 */
21
22#ifndef _RANGE_LIST_H
23#define _RANGE_LIST_H
24
25#include <stdlib.h>
26#include <stdbool.h>
27#include <stdint.h>
28#include <string.h>
29#include <math.h>
30#include "talloc.h"
31
32typedef struct _range_list_element
33{
34  uint32_t offset;
35  uint32_t length;
36  void* data;
37} range_list_element;
38
39
40typedef struct _range_list
41{
42  range_list_element** elements;
43  uint32_t elem_alloced;
44  uint32_t size;
45} range_list;
46
47
48/* range_list_new():
49 *  Allocates a new range_list.
50 *
51 * Returns:
52 *  A newly allocated range_list, or NULL if an error occurred.
53 */
54range_list* range_list_new();
55
56
57/* range_list_free():
58 *  Frees the memory associated with a range_list, including the elements, but
59 *  not any data parameters referenced by those elements.  If rl is NULL, does
60 *  nothing.
61 *
62 * Arguments:
63 *  rl -- the range_list to be free()d.
64 */
65void range_list_free(range_list* rl);
66
67
68/* range_list_size():
69 *  Query the current number of elements on a range_list
70 *
71 * Arguments:
72 *  rl -- the range_list to query
73 *
74 * Returns:
75 *  The number of elements currently in the list.
76 */
77uint32_t range_list_size(const range_list* rl);
78
79
80/* range_list_add():
81 *  Adds an element to the range_list. 
82 *  The new element must not overlap with others.
83 *  NOTE: this is a slow operation.
84 *
85 * Arguments:
86 *  rl     -- the range list to update
87 *  offset -- the starting point for the range
88 *  length -- the length of the range
89 *  data   -- misc data associated with this range element
90 * Returns:
91 *  true on success, false on failure.
92 *  Failures can occur due to memory limitations, max_size limitations,
93 *  or if the submitted range overlaps with an existing element.  Other
94 *  errors may also be possible.
95 */
96bool range_list_add(range_list* rl, uint32_t offset, uint32_t length, void* data);
97
98
99/* range_list_remove():
100 *  Removes an element from the list.  The element data structure will be
101 *  freed, but the data property will not be.
102 *
103 * Arguments:
104 *  rl     -- the range_list to modify
105 *  index  -- the element index to remove
106 *
107 * Returns:
108 *  true if the element was successfully removed, false otherwise.
109 */
110bool range_list_remove(range_list* rl, uint32_t index);
111
112
113/* range_list_get():
114 *  Retrieves the element for a given index.
115 *
116 * Arguments:
117 *  rl    -- the range_list being queried.
118 *  index -- the element index desired.
119 *
120 * Returns:
121 *  The element for a given index, or NULL if the element is not available.
122 */
123const range_list_element* range_list_get(const range_list* rl, uint32_t index);
124
125
126/* range_list_find():
127 *  Attempts to find the unique element whose range encompasses offset.
128 *
129 * Arguments:
130 *  rl     -- the range_list being queried.
131 *  offset -- the location for which an element is desired.
132 *
133 * Returns:
134 *  A matching element index or a negative value if none could be found.
135 */
136int32_t range_list_find(const range_list* rl, uint32_t offset);
137
138
139/* range_list_find_data():
140 *  Same as range_list_find(), but returns the data associated with an element.
141 *
142 * Arguments:
143 *  rl     -- the range_list being queried.
144 *  offset -- the address to search for in the ranges
145 *
146 * Returns:
147 *  The data element of the matching element index or NULL if none could
148 *  be found.
149 *
150 *  NOTE: May also return NULL if an element matched but if the data
151 *        element was never set.
152 */
153void* range_list_find_data(const range_list* rl, uint32_t offset);
154
155
156/* range_list_split_element():
157 *  Splits an existing element into two elements in place.
158 *
159 *  The resulting list will contain an additional element whose offset
160 *  is the one provided and whose length extends to the end of the old element
161 *  (the one identified by the index).  The original element's offset will
162 *  remain the same while it's length is shortened such that it is contiguous
163 *  with the newly created element.  The newly created element will have an index
164 *  of one more than the current element.
165 *
166 *  Both the original element and the newly created element will reference the
167 *  original element's data.
168 *
169 * Arguments:
170 *  rl     -- the range_list to modify
171 *  index  -- the index of the element to be split
172 *  offset -- the at which the element will be split
173 *
174 * Returns:
175 *  true if the element was successfully split, false otherwise.
176 *   
177 *
178 */
179bool range_list_split_element(range_list* rl, uint32_t index, uint32_t offset);
180
181
182/* range_list_has_range():
183 *  Determines whether or not a specified range exists contiguously within the
184 *  range_list.
185 *
186 * Arguments:
187 *  rl     -- the range_list to search
188 *  start  -- the offset at the beginning of the range
189 *  length -- the length of the range
190 *
191 * Returns:
192 *  true if the specified range exists and is complete, false otherwise.
193 */
194bool range_list_has_range(range_list* rl, uint32_t start, uint32_t length);
195
196#endif
Note: See TracBrowser for help on using the repository browser.