3
<!-- @(#) $Revision: 4.41 $ $Source: /judy/doc/ext/JudySL_3x.htm $ --->
4
<TITLE>JudySL(3X)</TITLE>
8
<TABLE border=0 width="100%"><TR>
9
<TD width="40%" align="left">JudySL(3X)</TD>
10
<TD width="10%" align="center"> </TD>
11
<TD width="40%" align="right">JudySL(3X)</TD>
21
C library for creating and accessing a dynamic array, using
22
a null-terminated string as an index (associative array)
26
<DT><B>SYNOPSIS</B></DT>
29
cc [flags] <I>sourcefiles</I> -lJudy
31
#include <Judy.h>
33
#define MAXLINELEN 65536 // define maximum string length
35
Word_t * PValue; // JudySL array element
36
char Index[MAXLINELEN]; // string
37
int Rc_int; // return value
38
Word_t Rc_word; // full word return value
40
Pvoid_t PJSLArray = (Pvoid_t) NULL; // initialize JudySL array
42
<A href="#JSLI" >JSLI</A>( PValue, PJSLArray, Index); // <A href="JudySL_funcs_3x.htm#JudySLIns">JudySLIns()</A>
43
<A href="#JSLD" >JSLD</A>( Rc_int, PJSLArray, Index); // <A href="JudySL_funcs_3x.htm#JudySLDel">JudySLDel()</A>
44
<A href="#JSLG" >JSLG</A>( PValue, PJSLArray, Index); // <A href="JudySL_funcs_3x.htm#JudySLGet">JudySLGet()</A>
45
<A href="#JSLFA">JSLFA</A>(Rc_word, PJSLArray); // <A href="JudySL_funcs_3x.htm#JudySLFreeArray">JudySLFreeArray()</A>
46
<A href="#JSLF" >JSLF</A>( PValue, PJSLArray, Index); // <A href="JudySL_funcs_3x.htm#JudySLFirst">JudySLFirst()</A>
47
<A href="#JSLN" >JSLN</A>( PValue, PJSLArray, Index); // <A href="JudySL_funcs_3x.htm#JudySLNext">JudySLNext()</A>
48
<A href="#JSLL" >JSLL</A>( PValue, PJSLArray, Index); // <A href="JudySL_funcs_3x.htm#JudySLLast">JudySLLast()</A>
49
<A href="#JSLP" >JSLP</A>( PValue, PJSLArray, Index); // <A href="JudySL_funcs_3x.htm#JudySLPrev">JudySLPrev()</A>
55
<DT><B>DESCRIPTION</B></DT>
57
A JudySL array is the equivalent of a sorted set of strings, each associated
59
A value is addressed by an <B>Index</B> (key), which is a null-terminated
60
character string of any length.
61
Memory to support the array is allocated as index/value pairs are inserted,
62
and released as index/value pairs are deleted.
63
This is a form of associative array, where array elements are also sorted
64
lexicographically (case-sensitive) by indexes.
65
This could be thought of as
67
void * JudySLArray["Toto, I don't think we're in Kansas any more"];
70
A JudySL array is allocated with a <B>NULL</B> pointer
72
Pvoid_t PJSLArray = (Pvoid_t) NULL;
74
As with an ordinary array, there are no duplicate indexes (strings)
77
Using the macros described here, rather than the
78
<A href="JudySL_funcs_3x.htm">JudySL function calls</A>,
79
the default error handling sends a
80
message to the standard error and terminates the program with
82
For other error handling methods, see the
83
<A href="#JSLERR">ERRORS</A> section.
86
Because the macro forms are faster and have a simpler error
87
handling interface than the equivalent
88
<A href="JudySL_funcs_3x.htm">functions</A>,
89
they are the preferred way to call the JudySL functions.
94
<DT><A name="JSLI"><B>JSLI(PValue, PJSLArray, Index)</B></A> // <A href="JudySL_funcs_3x.htm#JudySLIns">JudySLIns()</A></DT>
96
Insert an <B>Index</B> string and value in the JudySL array <B>PJSLArray</B>.
97
If the <B>Index</B> is successfully inserted,
98
the value is initialized to 0. If the <B>Index</B> was already present,
99
the value is not modified.
101
Return <B>PValue</B> pointing to <B>Index</B>'s value.
102
Your program must use this pointer to modify the value,
109
<B>JSLI()</B> and <B>JSLD</B> reorganize the JudySL array.
110
Therefore, pointers returned from previous <B>JudySL</B> calls become
111
invalid and must be reacquired.
114
<DT><A name="JSLD"><B>JSLD(Rc_int, PJSLArray, Index)</B></A> // <A href="JudySL_funcs_3x.htm#JudySLDel">JudySLDel()</A></DT>
116
Delete the specified <B>Index</B>/value pair (array element) from the
119
Return <B>Rc_int</B> set to 1 if successful.
120
array and it was previously inserted.
121
Return <B>Rc_int</B> set to 0 if <B>Index</B> was not present.
124
<DT><A name="JSLG"><B>JSLG(PValue, PJSLArray, Index)</B></A> // <A href="JudySL_funcs_3x.htm#JudySLGet">JudySLGet()</A></DT>
126
Get the pointer to <B>Index</B>'s value.
128
Return <B>PValue</B> pointing to <B>Index</B>'s value.
129
Return <B>PValue</B> set to <B>NULL</B> if the <B>Index</B> was not present.
132
<DT><A name="JSLFA"><B>JSLFA(Rc_word, PJSLArray)</B></A> // <A href="JudySL_funcs_3x.htm#JudySLFreeArray">JudySLFreeArray()</A></DT>
134
Given a pointer to a JudySL array (<B>PJSLArray</B>), free the entire array (much faster
135
than using a <B>JSLN()</B>, <B>JSLD()</B> loop.)
137
Return <B>Rc_word</B> set to the number of bytes freed and <B>PJSLArray</B> set to NULL.
140
<DT><B>JudySL Search Functions</B></DT>
142
The JudySL search functions allow you to search for indexes in the array.
143
You may search inclusively or exclusively,
144
in either forward or reverse directions.
147
<B>Index</B> is returned set to the found index, and
148
<B>PValue</B> is returned set to a pointer to <B>Index</B>'s value.
150
<B>PValue</B> is returned set to <B>NULL</B>,
151
and <B>Index</B> contains no useful information.
152
<B>PValue</B> must be tested for non-<B>NULL</B> prior
153
to using <B>Index</B>,
154
since a search failure is possible.
157
To accomodate all possible returns, the <B>Index</B> buffer must be
159
as the largest string stored in the array.
161
<DT><A name="JSLF"><B>JSLF(PValue, PJSLArray, Index)</B></A> // <A href="JudySL_funcs_3x.htm#JudySLFirst">JudySLFirst()</A></DT>
163
Search (inclusive) for the first index present that is equal to or greater than the
164
passed <B>Index</B> string.
165
(Start with a null string to find the first index in the array.)
166
<B>JSLF()</B> is typically used to <I>begin</I> a sorted-order scan of
167
the valid indexes in a JudySL array.
169
char Index[MAXLINELEN];
171
JSLF(PValue, PJSLArray, Index);
175
<DT><A name="JSLN"><B>JSLN(PValue, PJSLArray, Index)</B></A> // <A href="JudySL_funcs_3x.htm#JudySLNext">JudySLNext()</A></DT>
177
Search (exclusive) for the next index present that is greater than the passed
179
<B>JSLN()</B> is typically used to <I>continue</I> a sorted-order scan of
180
the valid indexes in a JudySL array, or to locate a "neighbor" of a given
184
<DT><A name="JSLL"><B>JSLL(PValue, PJSLArray, Index)</B></A> // <A href="JudySL_funcs_3x.htm#JudySLLast">JudySLLast()</A></DT>
186
Search (inclusive) for the last index present that is equal to or less
187
than the passed <B>Index</B> string.
188
(Start with a maximum-valued string to look up the last index in the array,
189
such as a max-length string of 0xff bytes.)
190
<B>JSLL()</B> is typically used to <I>begin</I> a reverse-sorted-order
191
scan of the valid indexes in a JudySL array.
194
<DT><A name="JSLP"><B>JSLP(PValue, PJSLArray, Index)</B></A> // <A href="JudySL_funcs_3x.htm#JudySLPrev">JudySLPrev()</A></DT>
196
Search (exclusive) for the previous index present that is less than the
197
passed <B>Index</B> string.
198
<B>JSLP()</B> is typically used to <I>continue</I> a reverse-sorted-order
199
scan of the valid indexes in a JudySL array, or to locate a "neighbor" of
207
<DT><A name="JSLERR"><B>ERRORS</B></A></DT>
209
There are two categories of Judy error returns:
211
1) User programming errors (bugs) such as memory corruption or
214
2) Out-of-memory (<I>malloc</I>() failure) when modifying a JudySL array with <B>JSLI()</B>
216
<P>There are three methods of handling errors when using the macros:
218
1) Default error handling.
220
2) User-specified <B>JUDYERROR()</B> macro.
222
3) Disable macro error handling.
225
<DT><B>Default Error Handling Method</B></DT>
227
The default is to print error messages to <B>stderr</B>, for example:
229
File 'YourCfile.c', line 1234: JudySLIns(), JU_ERRNO_* == 2, ID == 321
231
This indicates that an error occurred in a <B>JSLI()</B> call at line 1234 in 'YourCfile.c'.
232
JU_ERRNO_* == 2 is JU_ERRNO_NOMEM (as defined in the Judy.h file).
233
The ID number indicates the Judy source line number where the error was detected.
235
Your program then terminates with an <B>exit(1)</B>.
238
<DT><B>User-Specified JUDYERROR() Macro Method</B> </DT>
241
The <B>JUDYERROR()</B> macro provides flexibility for handling error returns
242
as needed to suit your program while still accessing JudySL arrays using macros
243
instead of function calls. You can modify <B>JUDYERROR()</B> to distinguish between
244
the two types of errors (described above), and explicitly test for the remaining
245
JU_ERRNO_NOMEM errors possible in your program.
248
// This is an example of JudySL macro API to continue when out of memory.
250
#ifndef JUDYERROR_NOTEST
251
#include <stdio.h>
253
// This is the macro that the Judy macro APIs use for return codes of -1:
255
#define JUDYERROR(CallerFile, CallerLine, JudyFunc, JudyErrno, JudyErrID) \
257
if ((JudyErrno) != JU_ERRNO_NOMEM) /* ! a malloc() failure */ \
259
(void) fprintf(stderr, "File '%s', line %d: %s(), " \
260
"JU_ERRNO_* == %d, ID == %d\n", \
261
CallerFile, CallerLine, \
262
JudyFunc, JudyErrno, JudyErrID); \
266
#endif // JUDYERROR_NOTEST not defined
268
This error handling macro must be included before the <B>#include <Judy.h></B>
269
statement in your program.
272
<DT><B>Disable Macro Error Handling</B> </DT>
275
When your program is "bug free",
276
the only errors occurring should be <I>malloc</I>(3) errors.
277
You can turn off error handling included in
278
the JudySL macros by using
280
#define JUDYERROR_NOTEST 1
282
(in your program code), or
284
cc -DJUDYERROR_NOTEST <I>sourcefile</I> -lJudy
286
(on your command line).
291
<DT><B>EXAMPLES</B></DT>
294
// This is an example of Judy macro API to continue when out of memory
296
// Put this before the #include <Judy.h>
297
// #define JUDYERROR_NOTEST // or defined with cc -DJUDYERROR_NOTEST ...
299
#ifndef JUDYERROR_NOTEST
300
#include <stdio.h>
302
// This is the macro the Judy macro APIs use for return codes of -1
303
#define JUDYERROR(CallerFile, CallerLine, JudyFunc, JudyErrno, JudyErrID) \
305
if ((JudyErrno) != JU_ERRNO_NOMEM) /* ! malloc() failure */ \
307
(void) fprintf(stderr, "File '%s', line %d: %s(), " \
308
"JU_ERRNO_* == %d, ID == %d\n", \
309
CallerFile, CallerLine, \
310
JudyFunc, JudyErrno, JudyErrID); \
314
#endif // JUDYERROR_NOTEST
316
#include <Judy.h>
318
#define MAXLINE 65536 // max string (line) len
320
int // Usage: JudySort < file_to_sort
323
Pvoid_t PJArray = (PWord_t)NULL; // Judy array.
324
PWord_t PValue; // Judy array element.
325
Word_t Bytes; // size of JudySL array.
326
char Index[MAXLINE]; // string to check
328
while (fgets(Index, sizeof(Index), stdin) != (char *)NULL)
330
JSLI(PValue, PJArray, Index); // store string into array
331
if (PValue == PJERR) // if out of memory?
333
printf("Malloc failed -- get more ram\n");
336
++(*PValue); // count instances of string
338
Index[0] = '\0'; // start with smallest string.
339
JSLF(PValue, PJArray, Index); // get first string
340
while (PValue != NULL)
342
while ((*PValue)--) // print duplicates
344
JSLN(PValue, PJArray, Index); // get next string
346
JSLFA(Bytes, PJArray); // free array
348
fprintf(stderr, "The JudySL array used %lu bytes of memory\n", Bytes);
355
<DT><B>AUTHOR</B></DT>
357
Judy was invented by Doug Baskins and implemented by Hewlett-Packard.
361
<DT><B>SEE ALSO</B></DT>
363
<A href="Judy_3x.htm">Judy(3X)</A>,
364
<A href="Judy1_3x.htm">Judy1(3X)</A>,
365
<A href="Judy1_funcs_3x.htm">Judy1_funcs(3X)</A>,
366
<A href="JudyL_3x.htm">JudyL(3X)</A>,
367
<A href="JudyL_funcs_3x.htm">JudyL_funcs(3X)</A>,
368
<A href="JudySL_funcs_3x.htm">JudySL_funcs(3X)</A>,
373
<A href="http://www.sourcejudy.com/">
374
http://www.sourcejudy.com/</A>,
375
for further information and Application Notes.
added
removed
doc/ext/JudySL_3x.htm
