← Back to branch summary

~ubuntu-branches/ubuntu/trusty/judy/trusty

« back to all changes in this revision

Viewing changes to doc/ext/Judy1_funcs_3.htm

  • Committer: Bazaar Package Importer
  • Author(s): Troy Heber
  • Date: 2005-03-22 06:55:53 UTC
  • mfrom: (1.1.1 upstream)
  • Revision ID: james.westby@ubuntu.com-20050322065553-syjpkd48r4re18dn
Tags: 1.0.1-5

* Moving LGPL link in copyright back to LGPL-2.1
* Cleanup of debian/rules: removed explicit refs to 32-bit archs, removed
  unnecessary nostrip, using --man dir to install man pages, moving from
  dh_movefiles to dh_install.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/ext/Judy1_funcs_3.htm
 
1
<HTML>
 
2
<HEAD>
 
3
<!-- @(#) $Revision: 4.8 $ $Source: /cvsroot/judy/doc/ext/Judy1_funcs_3.htm,v $ --->
 
4
<TITLE>Judy1_funcs(3)</TITLE>
 
5
</HEAD>
 
6
<BODY>
 
7
<TABLE border=0 width="100%"><TR>
 
8
<TD width="40%" align="left">Judy1_funcs(3)</TD>
 
9
<TD width="10%" align="center">     </TD>
 
10
<TD width="40%" align="right">Judy1_funcs(3)</TD>
 
11
</TR></TABLE>
 
12
<P>
 
13
<DL>
 
14
<!----------------->
 
15
<DT><B>NAME</B></DT>
 
16
<DD>
 
17
Judy1 functions -
 
18
C library for creating and accessing a dynamic array of bits, using
 
19
any value of a word as an index
 
20
<!----------------->
 
21
<P>
 
22
<DT><B>SYNOPSIS</B></DT>
 
23
<DD>
 
24
<B><PRE>
 
25
int    <A href="#Judy1Set"       >Judy1Set</A>(       PPvoid_t PPJ1Array, Word_t   Index,  PJError_t PJError);
 
26
int    <A href="#Judy1Unset"     >Judy1Unset</A>(     PPvoid_t PPJ1Array, Word_t   Index,  PJError_t PJError);
 
27
int    <A href="#Judy1Test"      >Judy1Test</A>(      Pcvoid_t  PJ1Array, Word_t   Index,  PJError_t PJError);
 
28
Word_t <A href="#Judy1Count"     >Judy1Count</A>(     Pcvoid_t  PJ1Array, Word_t   Index1, Word_t    Index2, PJError_t PJError);
 
29
int    <A href="#Judy1ByCount"   >Judy1ByCount</A>(   Pcvoid_t  PJ1Array, Word_t   Nth,    Word_t * PIndex,  PJError_t PJError);
 
30
Word_t <A href="#Judy1FreeArray" >Judy1FreeArray</A>( PPvoid_t PPJ1Array, PJError_t PJError);
 
31
Word_t <A href="#Judy1MemUsed"   >Judy1MemUsed</A>(   Pcvoid_t  PJ1Array);
 
32
int    <A href="#Judy1First"     >Judy1First</A>(     Pcvoid_t  PJ1Array, Word_t * PIndex, PJError_t PJError);
 
33
int    <A href="#Judy1Next"      >Judy1Next</A>(      Pcvoid_t  PJ1Array, Word_t * PIndex, PJError_t PJError);
 
34
int    <A href="#Judy1Last"      >Judy1Last</A>(      Pcvoid_t  PJ1Array, Word_t * PIndex, PJError_t PJError);
 
35
int    <A href="#Judy1Prev"      >Judy1Prev</A>(      Pcvoid_t  PJ1Array, Word_t * PIndex, PJError_t PJError);
 
36
int    <A href="#Judy1FirstEmpty">Judy1FirstEmpty</A>(Pcvoid_t  PJ1Array, Word_t * PIndex, PJError_t PJError);
 
37
int    <A href="#Judy1NextEmpty" >Judy1NextEmpty</A>( Pcvoid_t  PJ1Array, Word_t * PIndex, PJError_t PJError);
 
38
int    <A href="#Judy1LastEmpty" >Judy1LastEmpty</A>( Pcvoid_t  PJ1Array, Word_t * PIndex, PJError_t PJError);
 
39
int    <A href="#Judy1PrevEmpty" >Judy1PrevEmpty</A>( Pcvoid_t  PJ1Array, Word_t * PIndex, PJError_t PJError);
 
40
</PRE></B>
 
41
<!----------------->
 
42
<P>
 
43
<DT><B>DESCRIPTION</B></DT>
 
44
<DD>
 
45
A macro equivalent exists for each function call.
 
46
Because the macro forms are sometimes faster and have a simpler error
 
47
handling interface than the equivalent functions,
 
48
they are the preferred way of calling the Judy1 functions.
 
49
See <A href="Judy1_3.htm">Judy1(3)</A>
 
50
for more information.
 
51
The function call definitions are included here for completeness.
 
52
<P>
 
53
One of the difficulties in using the Judy1 function calls lies in
 
54
determining whether to pass a pointer or the address of a pointer.
 
55
Since the functions that modify the Judy1 array must also modify the
 
56
pointer to the Judy1 array, you must pass the address of the pointer
 
57
rather than the pointer itself.
 
58
This often leads to hard-to-debug programmatic errors.
 
59
In practice, the macros allow the compiler to catch programming
 
60
errors when pointers instead of addresses of pointers are passed.
 
61
<P>
 
62
The Judy1 function calls have an additional parameter beyond
 
63
those specified in the macro calls.  This parameter is either a
 
64
pointer to an error structure, or <B>NULL</B> (in which case the
 
65
detailed error information is not returned).
 
66
<P>
 
67
In the following descriptions, the functions are described in
 
68
terms of how the macros use them (only in the case of
 
69
<B>#define JUDYERROR_NOTEST 1</B>).  This is the suggested use
 
70
of the macros after your program has been fully debugged.
 
71
When the <B>JUDYERROR_NOTEST</B> macro is not specified,
 
72
an error structure is declared to store error information
 
73
returned from the Judy1 functions when an error occurs.
 
74
<P>
 
75
Notice the placement of the <B>&amp;</B> in the different functions.
 
76
<P>
 
77
<DL>
 
78
<DT><A name="Judy1Set"><B>Judy1Set(&amp;PJ1Array, Index, &amp;JError)</B></A></DT>
 
79
<DD>
 
80
<PRE>
 
81
#define J1S(Rc_int, PJ1Array, Index) \
 
82
   Rc_int = Judy1Set(&amp;PJ1Array, Index, PJE0)
 
83
 
 
84
</PRE>
 
85
<P>
 
86
<DT><A name="Judy1Unset"><B>Judy1Unset(&amp;PJ1Array, Index, &amp;JError)</B></A></DT>
 
87
<DD>
 
88
<PRE>
 
89
#define J1U(Rc_int, PJ1Array, Index) \
 
90
   Rc_int = Judy1Unset(&amp;PJ1Array, Index, PJE0)
 
91
 
 
92
</PRE>
 
93
<P>
 
94
<DT><A name="Judy1Test"><B>Judy1Test(PJ1Array, Index, &amp;JError)</B></A></DT>
 
95
<DD>
 
96
<PRE>
 
97
#define J1T(Rc_int, PJ1Array, Index) \
 
98
   Rc_int = Judy1Test(PJ1Array, Index, PJE0)
 
99
 
 
100
</PRE>
 
101
<P>
 
102
<DT><A name="Judy1Count"><B>Judy1Count(PJ1Array, Index1, Index2, &amp;JError)</B></A></DT>
 
103
<DD>
 
104
<PRE>
 
105
#define J1C(Rc_word, PJ1Array, Index1, Index2) \
 
106
   Rc_word = Judy1Count(PJ1Array, Index1, Index2, PJE0)
 
107
 
 
108
</PRE>
 
109
A return value of 0 can be an error, valid as a count, or it can indicate a special case
 
110
for a fully-populated array (32-bit machines only).  If necessary, the following
 
111
code can be used to disambiguate this return:
 
112
<PRE>
 
113
JError_t JError;
 
114
 
 
115
Rc_word = Judy1Count(PJ1Array, Index1, Index2, &amp;JError);
 
116
if (Rc_word == 0)
 
117
{
 
118
    if (JU_ERRNO(&amp;JError) == JU_ERRNO_NONE)
 
119
        printf("Judy1 array population == 0\n");
 
120
    if (JU_ERRNO(&amp;JError) == JU_ERRNO_FULL)
 
121
        printf("Judy1 array population == 2^32\n");
 
122
    if (JU_ERRNO(&amp;JError) == JU_ERRNO_NULLPPARRAY)
 
123
        goto NullArray;
 
124
    if (JU_ERRNO(&amp;JError) >  JU_ERRNO_NFMAX)
 
125
        goto Null_or_CorruptArray;
 
126
}
 
127
</PRE>
 
128
<P>
 
129
<DT><A name="Judy1ByCount"><B>Judy1ByCount(PJ1Array, Nth, &amp;Index, &amp;JError)</B></A></DT>
 
130
<DD>
 
131
<PRE>
 
132
#define J1BC(Rc_int, PJ1Array, Nth, Index) \
 
133
   Rc_int = Judy1ByCount(PJ1Array, Nth, &amp;Index, PJE0)
 
134
 
 
135
</PRE>
 
136
<P>
 
137
<DT><A name="Judy1FreeArray"><B>Judy1FreeArray(&amp;PJ1Array, &amp;JError)</B></A></DT>
 
138
<DD>
 
139
<PRE>
 
140
#define J1FA(Rc_word, PJ1Array) \
 
141
   Rc_word = Judy1FreeArray(&amp;PJ1Array, PJE0)
 
142
 
 
143
</PRE>
 
144
<P>
 
145
<DT><A name="Judy1MemUsed"><B>Judy1MemUsed(PJ1Array)</B></A></DT>
 
146
<DD>
 
147
<PRE>
 
148
#define J1MU(Rc_word, PJ1Array) \
 
149
   Rc_word = Judy1MemUsed(PJ1Array)
 
150
 
 
151
</PRE>
 
152
<P>
 
153
<DT><A name="Judy1First"><B>Judy1First(PJ1Array, &amp;Index, &amp;JError)</B></A></DT>
 
154
<DD>
 
155
<PRE>
 
156
#define J1F(Rc_int, PJ1Array, Index) \
 
157
   Rc_int = Judy1First(PJ1Array, &amp;Index, PJE0)
 
158
 
 
159
</PRE>
 
160
<P>
 
161
<DT><A name="Judy1Next"><B>Judy1Next(PJ1Array, &amp;Index, &amp;JError)</B></A></DT>
 
162
<DD>
 
163
<PRE>
 
164
#define J1N(Rc_int, PJ1Array, Index) \
 
165
   Rc_int = Judy1Next(PJ1Array, &amp;Index, PJE0)
 
166
 
 
167
</PRE>
 
168
<P>
 
169
<DT><A name="Judy1Last"><B>Judy1Last(PJ1Array, &amp;Index, &amp;JError)</B></A></DT>
 
170
<DD>
 
171
<PRE>
 
172
#define J1L(Rc_int, PJ1Array, Index) \
 
173
   Rc_int = Judy1Last(PJ1Array, &amp;Index, PJE0)
 
174
 
 
175
</PRE>
 
176
<P>
 
177
<DT><A name="Judy1Prev"><B>Judy1Prev(PJ1Array, &amp;Index, &amp;JError)</B></A></DT>
 
178
<DD>
 
179
<PRE>
 
180
#define J1P(Rc_int, PJ1Array, Index) \
 
181
   Rc_int = Judy1Prev(PJ1Array, &amp;Index, PJE0)
 
182
 
 
183
</PRE>
 
184
<P>
 
185
<DT><A name="Judy1FirstEmpty"><B>Judy1FirstEmpty(PJ1Array, &amp;Index, &amp;JError)</B></A></DT>
 
186
<DD>
 
187
<PRE>
 
188
#define J1FE(Rc_int, PJ1Array, Index) \
 
189
   Rc_int = Judy1FirstEmpty(PJ1Array, &amp;Index, PJE0)
 
190
 
 
191
</PRE>
 
192
<P>
 
193
<DT><A name="Judy1NextEmpty"><B>Judy1NextEmpty(PJ1Array, &amp;Index, &amp;JError)</B></A></DT>
 
194
<DD>
 
195
<PRE>
 
196
#define J1NE(Rc_int, PJ1Array, Index) \
 
197
   Rc_int = Judy1NextEmpty(PJ1Array, &amp;Index, PJE0)
 
198
 
 
199
</PRE>
 
200
<P>
 
201
<DT><A name="Judy1LastEmpty"><B>Judy1LastEmpty(PJ1Array, &amp;Index, &amp;JError)</B></A></DT>
 
202
<DD>
 
203
<PRE>
 
204
#define J1LE(Rc_int, PJ1Array, Index) \
 
205
   Rc_int = Judy1LastEmpty(PJ1Array, &amp;Index, PJE0)
 
206
 
 
207
</PRE>
 
208
<P>
 
209
<DT><A name="Judy1PrevEmpty"><B>Judy1PrevEmpty(PJ1Array, &amp;Index, &amp;JError)</B></A></DT>
 
210
<DD>
 
211
<PRE>
 
212
#define J1PE(Rc_int, PJ1Array, Index) \
 
213
   Rc_int = Judy1PrevEmpty(PJ1Array, &amp;Index, PJE0)
 
214
 
 
215
</PRE>
 
216
</DL>
 
217
<P>
 
218
Definitions for all of the Judy functions, the types
 
219
<B>Pvoid_t</B>,
 
220
<B>Pcvoid_t</B>,
 
221
<B>PPvoid_t</B>,
 
222
<B>Word_t</B>,
 
223
<B>JError_t</B>,
 
224
and
 
225
<B>PJError_t</B>,
 
226
the constants
 
227
<B>NULL</B>,
 
228
<B>JU_ERRNO_*</B>,
 
229
<B>JERR</B>,
 
230
and
 
231
<B>PJE0</B>,
 
232
are provided in the <B>Judy.h</B> header file
 
233
(/usr/include/Judy.h).
 
234
<B>Note</B>:  Callers should define Judy1 arrays as type <B>Pvoid_t</B>,
 
235
which can be passed by value to functions that take
 
236
<B>Pcvoid_t</B> (constant <B>Pvoid_t</B>),
 
237
and also by address to functions that take <B>PPvoid_t</B>.
 
238
<!----------------->
 
239
<P>
 
240
<DT><B>AUTHOR</B></DT>
 
241
<DD>
 
242
Judy was invented by Doug Baskins and implemented by Hewlett-Packard.
 
243
<!----------------->
 
244
<P>
 
245
<DT><B>SEE ALSO</B></DT>
 
246
<DD>
 
247
<A href="Judy_3.htm">Judy(3)</A>,
 
248
<A href="JudyL_3.htm">JudyL(3)</A>,
 
249
<A href="JudySL_3.htm">JudySL(3)</A>,
 
250
<A href="JudyHS_3.htm">JudyHS(3)</A>,
 
251
<BR>
 
252
<I>malloc()</I>,
 
253
<BR>
 
254
the Judy website,
 
255
<A href="http://judy.sourceforge.net">
 
256
http://judy.sourceforge.net</A>,
 
257
for more information and Application Notes.
 
258
</DL>
 
259
</BODY>
 
260
</HTML>