3
<!-- @(#) $Revision: 4.43 $ $Source: /cvsroot/judy/doc/ext/JudySL_3.htm,v $ --->
4
<TITLE>JudySL(3)</TITLE>
7
<TABLE border=0 width="100%"><TR>
8
<TD width="40%" align="left">JudySL(3)</TD>
9
<TD width="10%" align="center"> </TD>
10
<TD width="40%" align="right">JudySL(3)</TD>
18
C library for creating and accessing a dynamic array, using
19
a null-terminated string as an <B>Index</B> (associative array)
22
<DT><B>SYNOPSIS</B></DT>
25
cc [flags] <I>sourcefiles</I> -lJudy
27
#include <Judy.h>
29
#define MAXLINELEN 1000000 // define maximum string length
31
Word_t * PValue; // JudySL array element
32
uint8_t Index[MAXLINELEN]; // string
33
int Rc_int; // return value
34
Word_t Rc_word; // full word return value
36
Pvoid_t PJSLArray = (Pvoid_t) NULL; // initialize JudySL array
38
<A href="#JSLI" >JSLI</A>( PValue, PJSLArray, Index); // <A href="JudySL_funcs_3.htm#JudySLIns">JudySLIns()</A>
39
<A href="#JSLD" >JSLD</A>( Rc_int, PJSLArray, Index); // <A href="JudySL_funcs_3.htm#JudySLDel">JudySLDel()</A>
40
<A href="#JSLG" >JSLG</A>( PValue, PJSLArray, Index); // <A href="JudySL_funcs_3.htm#JudySLGet">JudySLGet()</A>
41
<A href="#JSLFA">JSLFA</A>(Rc_word, PJSLArray); // <A href="JudySL_funcs_3.htm#JudySLFreeArray">JudySLFreeArray()</A>
42
<A href="#JSLF" >JSLF</A>( PValue, PJSLArray, Index); // <A href="JudySL_funcs_3.htm#JudySLFirst">JudySLFirst()</A>
43
<A href="#JSLN" >JSLN</A>( PValue, PJSLArray, Index); // <A href="JudySL_funcs_3.htm#JudySLNext">JudySLNext()</A>
44
<A href="#JSLL" >JSLL</A>( PValue, PJSLArray, Index); // <A href="JudySL_funcs_3.htm#JudySLLast">JudySLLast()</A>
45
<A href="#JSLP" >JSLP</A>( PValue, PJSLArray, Index); // <A href="JudySL_funcs_3.htm#JudySLPrev">JudySLPrev()</A>
50
<DT><B>DESCRIPTION</B></DT>
52
A JudySL array is the equivalent of a sorted set of strings, each associated
53
with a <B>Value</B> (word).
54
A <B>Value</B> is addressed by an <B>Index</B> (key), which is a null-terminated
55
character string of any length.
56
Memory to support the array is allocated as index/value pairs are inserted,
57
and released as index/value pairs are deleted.
58
This is a form of associative array, where array elements are also sorted
59
lexicographically (case-sensitive) by indexes.
60
This could be thought of as
62
void * JudySLArray["Toto, I don't think we're in Kansas any more"];
65
A JudySL array is allocated with a <B>NULL</B> pointer
67
Pvoid_t PJSLArray = (Pvoid_t) NULL;
69
As with an ordinary array, there are no duplicate indexes (strings)
72
Using the macros described here, rather than the
73
<A href="JudySL_funcs_3.htm">JudySL function calls</A>,
74
the default error handling sends a
75
message to the standard error and terminates the program with
78
<DT><A name="JSLI"><B>JSLI(PValue, PJSLArray, Index)</B></A> // <A href="JudySL_funcs_3.htm#JudySLIns">JudySLIns()</A></DT>
80
Insert an <B>Index</B> string and <B>Value</B> in the JudySL array <B>PJSLArray</B>.
81
If the <B>Index</B> is successfully inserted,
82
the <B>Value</B> is initialized to 0. If the <B>Index</B> was already present,
83
the <B>Value</B> is not modified.
85
Return <B>PValue</B> pointing to <B>Index</B>'s <B>Value</B>.
86
Your program must use this pointer to modify the <B>Value</B>,
93
<B>JSLI()</B> and <B>JSLD</B> reorganize the JudySL array.
94
Therefore, pointers returned from previous <B>JudySL</B> calls become
95
invalid and must be reacquired.
97
<DT><A name="JSLD"><B>JSLD(Rc_int, PJSLArray, Index)</B></A> // <A href="JudySL_funcs_3.htm#JudySLDel">JudySLDel()</A></DT>
99
Delete the specified <B>Index</B>/<B>Value</B> pair (array element) from the
102
Return <B>Rc_int</B> set to 1 if successful.
103
array and it was previously inserted.
104
Return <B>Rc_int</B> set to 0 if <B>Index</B> was not present.
106
<DT><A name="JSLG"><B>JSLG(PValue, PJSLArray, Index)</B></A> // <A href="JudySL_funcs_3.htm#JudySLGet">JudySLGet()</A></DT>
108
Get the pointer to <B>Index</B>'s <B>Value</B>.
110
Return <B>PValue</B> pointing to <B>Index</B>'s <B>Value</B>.
111
Return <B>PValue</B> set to <B>NULL</B> if the <B>Index</B> was not present.
113
<DT><A name="JSLFA"><B>JSLFA(Rc_word, PJSLArray)</B></A> // <A href="JudySL_funcs_3.htm#JudySLFreeArray">JudySLFreeArray()</A></DT>
115
Given a pointer to a JudySL array (<B>PJSLArray</B>), free the entire array (much faster
116
than using a <B>JSLN()</B>, <B>JSLD()</B> loop.)
118
Return <B>Rc_word</B> set to the number of bytes freed and <B>PJSLArray</B> set to NULL.
120
<DT><B>JudySL Search Functions</B></DT>
122
The JudySL search functions allow you to search for indexes in the array.
123
You may search inclusively or exclusively,
124
in either forward or reverse directions.
127
<B>Index</B> is returned set to the found index, and
128
<B>PValue</B> is returned set to a pointer to <B>Index</B>'s <B>Value</B>.
130
<B>PValue</B> is returned set to <B>NULL</B>,
131
and <B>Index</B> contains no useful information.
132
<B>PValue</B> must be tested for non-<B>NULL</B> prior
133
to using <B>Index</B>,
134
since a search failure is possible.
137
To accomodate all possible returns, the <B>Index</B> buffer must be
139
as the largest string stored in the array.
141
<DT><A name="JSLF"><B>JSLF(PValue, PJSLArray, Index)</B></A> // <A href="JudySL_funcs_3.htm#JudySLFirst">JudySLFirst()</A></DT>
143
Search (inclusive) for the first index present that is equal to or greater than the
144
passed <B>Index</B> string.
145
(Start with a null string to find the first index in the array.)
146
<B>JSLF()</B> is typically used to <I>begin</I> a sorted-order scan of
147
the valid indexes in a JudySL array.
149
uint8_t Index[MAXLINELEN];
151
JSLF(PValue, PJSLArray, Index);
154
<DT><A name="JSLN"><B>JSLN(PValue, PJSLArray, Index)</B></A> // <A href="JudySL_funcs_3.htm#JudySLNext">JudySLNext()</A></DT>
156
Search (exclusive) for the next index present that is greater than the passed
158
<B>JSLN()</B> is typically used to <I>continue</I> a sorted-order scan of
159
the valid indexes in a JudySL array, or to locate a "neighbor" of a given
162
<DT><A name="JSLL"><B>JSLL(PValue, PJSLArray, Index)</B></A> // <A href="JudySL_funcs_3.htm#JudySLLast">JudySLLast()</A></DT>
164
Search (inclusive) for the last index present that is equal to or less
165
than the passed <B>Index</B> string.
166
(Start with a maximum-valued string to look up the last index in the array,
167
such as a max-length string of 0xff bytes.)
168
<B>JSLL()</B> is typically used to <I>begin</I> a reverse-sorted-order
169
scan of the valid indexes in a JudySL array.
171
<DT><A name="JSLP"><B>JSLP(PValue, PJSLArray, Index)</B></A> // <A href="JudySL_funcs_3.htm#JudySLPrev">JudySLPrev()</A></DT>
173
Search (exclusive) for the previous index present that is less than the
174
passed <B>Index</B> string.
175
<B>JSLP()</B> is typically used to <I>continue</I> a reverse-sorted-order
176
scan of the valid indexes in a JudySL array, or to locate a "neighbor" of
180
<DT><A name="JSLERR"><B>ERRORS:</B> See: </A><A href="Judy_3.htm#ERRORS">Judy_3.htm#ERRORS</A></DT>
184
<DT><B>EXAMPLE</B> of a string sort routine</DT>
186
#include <stdio.h>
187
#include <Judy.h>
189
#define MAXLINE 1000000 // max string (line) length
191
uint8_t Index[MAXLINE]; // string to insert
193
int // Usage: JudySort < file_to_sort
196
Pvoid_t PJArray = (PWord_t)NULL; // Judy array.
197
PWord_t PValue; // Judy array element.
198
Word_t Bytes; // size of JudySL array.
200
while (fgets(Index, MAXLINE, stdin) != (char *)NULL)
202
JSLI(PValue, PJArray, Index); // store string into array
203
if (PValue == PJERR) // if out of memory?
205
printf("Malloc failed -- get more ram\n");
208
++(*PValue); // count instances of string
210
Index[0] = '\0'; // start with smallest string.
211
JSLF(PValue, PJArray, Index); // get first string
212
while (PValue != NULL)
214
while ((*PValue)--) // print duplicates
216
JSLN(PValue, PJArray, Index); // get next string
218
JSLFA(Bytes, PJArray); // free array
220
fprintf(stderr, "The JudySL array used %lu bytes of memory\n", Bytes);
226
<DT><B>AUTHOR</B></DT>
228
Judy was invented by Doug Baskins and implemented by Hewlett-Packard.
231
<DT><B>SEE ALSO</B></DT>
233
<A href="Judy_3.htm">Judy(3)</A>,
234
<A href="Judy1_3.htm">Judy1(3)</A>,
235
<A href="JudyL_3.htm">JudyL(3)</A>,
236
<A href="JudyHS_3.htm">JudyHS(3)</A>,
241
<A href="http://judy.sourceforge.net">
242
http://judy.sourceforge.net</A>,
243
for further information and Application Notes.
added
removed
doc/ext/JudySL_3.htm
