<HTML>
<HEAD>
<!-- @(#) $Revision: 4.43 $ $Source: /cvsroot/judy/doc/ext/JudySL_3.htm,v $ --->
<TITLE>JudySL(3)</TITLE>
</HEAD>
<BODY>
<TABLE border=0 width="100%"><TR>
<TD width="40%" align="left">JudySL(3)</TD>
<TD width="10%" align="center"> </TD>
<TD width="40%" align="right">JudySL(3)</TD>
</TR></TABLE>
<P>
<DL>
<!----------------->
<DT><B>NAME</B></DT>
<DD>
JudySL macros -
C library for creating and accessing a dynamic array, using
a null-terminated string as an <B>Index</B> (associative array)
<!----------------->
<P>
<DT><B>SYNOPSIS</B></DT>
<DD>
<B><PRE>
cc [flags] <I>sourcefiles</I> -lJudy
#include <Judy.h>
#define MAXLINELEN 1000000 // define maximum string length
Word_t * PValue; // JudySL array element
uint8_t Index[MAXLINELEN]; // string
int Rc_int; // return value
Word_t Rc_word; // full word return value
Pvoid_t PJSLArray = (Pvoid_t) NULL; // initialize JudySL array
<A href="#JSLI" >JSLI</A>( PValue, PJSLArray, Index); // <A href="JudySL_funcs_3.htm#JudySLIns">JudySLIns()</A>
<A href="#JSLD" >JSLD</A>( Rc_int, PJSLArray, Index); // <A href="JudySL_funcs_3.htm#JudySLDel">JudySLDel()</A>
<A href="#JSLG" >JSLG</A>( PValue, PJSLArray, Index); // <A href="JudySL_funcs_3.htm#JudySLGet">JudySLGet()</A>
<A href="#JSLFA">JSLFA</A>(Rc_word, PJSLArray); // <A href="JudySL_funcs_3.htm#JudySLFreeArray">JudySLFreeArray()</A>
<A href="#JSLF" >JSLF</A>( PValue, PJSLArray, Index); // <A href="JudySL_funcs_3.htm#JudySLFirst">JudySLFirst()</A>
<A href="#JSLN" >JSLN</A>( PValue, PJSLArray, Index); // <A href="JudySL_funcs_3.htm#JudySLNext">JudySLNext()</A>
<A href="#JSLL" >JSLL</A>( PValue, PJSLArray, Index); // <A href="JudySL_funcs_3.htm#JudySLLast">JudySLLast()</A>
<A href="#JSLP" >JSLP</A>( PValue, PJSLArray, Index); // <A href="JudySL_funcs_3.htm#JudySLPrev">JudySLPrev()</A>
</PRE></B>
<!----------------->
<P>
<DT><B>DESCRIPTION</B></DT>
<DD>
A JudySL array is the equivalent of a sorted set of strings, each associated
with a <B>Value</B> (word).
A <B>Value</B> is addressed by an <B>Index</B> (key), which is a null-terminated
character string of any length.
Memory to support the array is allocated as index/value pairs are inserted,
and released as index/value pairs are deleted.
This is a form of associative array, where array elements are also sorted
lexicographically (case-sensitive) by indexes.
This could be thought of as
<P><PRE>
void * JudySLArray["Toto, I don't think we're in Kansas any more"];
</PRE>
<P>
A JudySL array is allocated with a <B>NULL</B> pointer
<PRE>
Pvoid_t PJSLArray = (Pvoid_t) NULL;
</PRE>
As with an ordinary array, there are no duplicate indexes (strings)
in a JudySL array.
<P>
Using the macros described here, rather than the
<A href="JudySL_funcs_3.htm">JudySL function calls</A>,
the default error handling sends a
message to the standard error and terminates the program with
<B>exit(1)</B>.
<P>
<DT><A name="JSLI"><B>JSLI(PValue, PJSLArray, Index)</B></A> // <A href="JudySL_funcs_3.htm#JudySLIns">JudySLIns()</A></DT>
<DD>
Insert an <B>Index</B> string and <B>Value</B> in the JudySL array <B>PJSLArray</B>.
If the <B>Index</B> is successfully inserted,
the <B>Value</B> is initialized to 0. If the <B>Index</B> was already present,
the <B>Value</B> is not modified.
<P>
Return <B>PValue</B> pointing to <B>Index</B>'s <B>Value</B>.
Your program must use this pointer to modify the <B>Value</B>,
for example:
<PRE>
*PValue = 1234;
</PRE>
<P>
<B>Note</B>:
<B>JSLI()</B> and <B>JSLD</B> reorganize the JudySL array.
Therefore, pointers returned from previous <B>JudySL</B> calls become
invalid and must be reacquired.
<P>
<DT><A name="JSLD"><B>JSLD(Rc_int, PJSLArray, Index)</B></A> // <A href="JudySL_funcs_3.htm#JudySLDel">JudySLDel()</A></DT>
<DD>
Delete the specified <B>Index</B>/<B>Value</B> pair (array element) from the
JudySL array.
<P>
Return <B>Rc_int</B> set to 1 if successful.
array and it was previously inserted.
Return <B>Rc_int</B> set to 0 if <B>Index</B> was not present.
<P>
<DT><A name="JSLG"><B>JSLG(PValue, PJSLArray, Index)</B></A> // <A href="JudySL_funcs_3.htm#JudySLGet">JudySLGet()</A></DT>
<DD>
Get the pointer to <B>Index</B>'s <B>Value</B>.
<P>
Return <B>PValue</B> pointing to <B>Index</B>'s <B>Value</B>.
Return <B>PValue</B> set to <B>NULL</B> if the <B>Index</B> was not present.
<P>
<DT><A name="JSLFA"><B>JSLFA(Rc_word, PJSLArray)</B></A> // <A href="JudySL_funcs_3.htm#JudySLFreeArray">JudySLFreeArray()</A></DT>
<DD>
Given a pointer to a JudySL array (<B>PJSLArray</B>), free the entire array (much faster
than using a <B>JSLN()</B>, <B>JSLD()</B> loop.)
<P>
Return <B>Rc_word</B> set to the number of bytes freed and <B>PJSLArray</B> set to NULL.
<P>
<DT><B>JudySL Search Functions</B></DT>
<DD>
The JudySL search functions allow you to search for indexes in the array.
You may search inclusively or exclusively,
in either forward or reverse directions.
<P>
If successful,
<B>Index</B> is returned set to the found index, and
<B>PValue</B> is returned set to a pointer to <B>Index</B>'s <B>Value</B>.
If unsuccessful,
<B>PValue</B> is returned set to <B>NULL</B>,
and <B>Index</B> contains no useful information.
<B>PValue</B> must be tested for non-<B>NULL</B> prior
to using <B>Index</B>,
since a search failure is possible.
<P>
<B>Note</B>:
To accomodate all possible returns, the <B>Index</B> buffer must be
at least as large
as the largest string stored in the array.
<P>
<DT><A name="JSLF"><B>JSLF(PValue, PJSLArray, Index)</B></A> // <A href="JudySL_funcs_3.htm#JudySLFirst">JudySLFirst()</A></DT>
<DD>
Search (inclusive) for the first index present that is equal to or greater than the
passed <B>Index</B> string.
(Start with a null string to find the first index in the array.)
<B>JSLF()</B> is typically used to <I>begin</I> a sorted-order scan of
the valid indexes in a JudySL array.
<PRE>
uint8_t Index[MAXLINELEN];
strcpy (Index, "");
JSLF(PValue, PJSLArray, Index);
</PRE>
<P>
<DT><A name="JSLN"><B>JSLN(PValue, PJSLArray, Index)</B></A> // <A href="JudySL_funcs_3.htm#JudySLNext">JudySLNext()</A></DT>
<DD>
Search (exclusive) for the next index present that is greater than the passed
<B>Index</B> string.
<B>JSLN()</B> is typically used to <I>continue</I> a sorted-order scan of
the valid indexes in a JudySL array, or to locate a "neighbor" of a given
index.
<P>
<DT><A name="JSLL"><B>JSLL(PValue, PJSLArray, Index)</B></A> // <A href="JudySL_funcs_3.htm#JudySLLast">JudySLLast()</A></DT>
<DD>
Search (inclusive) for the last index present that is equal to or less
than the passed <B>Index</B> string.
(Start with a maximum-valued string to look up the last index in the array,
such as a max-length string of 0xff bytes.)
<B>JSLL()</B> is typically used to <I>begin</I> a reverse-sorted-order
scan of the valid indexes in a JudySL array.
<P>
<DT><A name="JSLP"><B>JSLP(PValue, PJSLArray, Index)</B></A> // <A href="JudySL_funcs_3.htm#JudySLPrev">JudySLPrev()</A></DT>
<DD>
Search (exclusive) for the previous index present that is less than the
passed <B>Index</B> string.
<B>JSLP()</B> is typically used to <I>continue</I> a reverse-sorted-order
scan of the valid indexes in a JudySL array, or to locate a "neighbor" of
a given index.
<!----------------->
<P>
<DT><A name="JSLERR"><B>ERRORS:</B> See: </A><A href="Judy_3.htm#ERRORS">Judy_3.htm#ERRORS</A></DT>
<DD>
<!----------------->
<P>
<DT><B>EXAMPLE</B> of a string sort routine</DT>
<P><PRE>
#include <stdio.h>
#include <Judy.h>
#define MAXLINE 1000000 // max string (line) length
uint8_t Index[MAXLINE]; // string to insert
int // Usage: JudySort < file_to_sort
main()
{
Pvoid_t PJArray = (PWord_t)NULL; // Judy array.
PWord_t PValue; // Judy array element.
Word_t Bytes; // size of JudySL array.
while (fgets(Index, MAXLINE, stdin) != (char *)NULL)
{
JSLI(PValue, PJArray, Index); // store string into array
if (PValue == PJERR) // if out of memory?
{ // so do something
printf("Malloc failed -- get more ram\n");
exit(1);
}
++(*PValue); // count instances of string
}
Index[0] = '\0'; // start with smallest string.
JSLF(PValue, PJArray, Index); // get first string
while (PValue != NULL)
{
while ((*PValue)--) // print duplicates
printf("%s", Index);
JSLN(PValue, PJArray, Index); // get next string
}
JSLFA(Bytes, PJArray); // free array
fprintf(stderr, "The JudySL array used %lu bytes of memory\n", Bytes);
return (0);
}
</PRE>
<!----------------->
<P>
<DT><B>AUTHOR</B></DT>
<DD>
Judy was invented by Doug Baskins and implemented by Hewlett-Packard.
<!----------------->
<P>
<DT><B>SEE ALSO</B></DT>
<DD>
<A href="Judy_3.htm">Judy(3)</A>,
<A href="Judy1_3.htm">Judy1(3)</A>,
<A href="JudyL_3.htm">JudyL(3)</A>,
<A href="JudyHS_3.htm">JudyHS(3)</A>,
<BR>
<I>malloc()</I>,
<BR>
the Judy website,
<A href="http://judy.sourceforge.net">
http://judy.sourceforge.net</A>,
for further information and Application Notes.
</DL>
</BODY>
</HTML>
