JudySL(3X)JudySL(3X)NAME
JudySL macros - C library for creating and accessing a dynamic array,
using a null-terminated string as an index (associative array)
SYNOPSIS
cc [flags] sourcefiles -lJudy
#include <Judy.h>
#define MAXLINELEN 65536 // define maximum string length
Word_t * PValue; // JudySL array element
char 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
JSLI( PValue, PJSLArray, Index); // JudySLIns()
JSLD( Rc_int, PJSLArray, Index); // JudySLDel()
JSLG( PValue, PJSLArray, Index); // JudySLGet()
JSLFA(Rc_word, PJSLArray); // JudySLFreeArray()
JSLF( PValue, PJSLArray, Index); // JudySLFirst()
JSLN( PValue, PJSLArray, Index); // JudySLNext()
JSLL( PValue, PJSLArray, Index); // JudySLLast()
JSLP( PValue, PJSLArray, Index); // JudySLPrev()DESCRIPTION
A JudySL array is the equivalent of a sorted set of strings, each asso‐
ciated with a value (word). A value is addressed by an Index (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 associa‐
tive array, where array elements are also sorted lexicographically
(case-sensitive) by indexes. This could be thought of as
void * JudySLArray["Toto, I don't think we're in Kansas any more"];
A JudySL array is allocated with a NULL pointer
Pvoid_t PJSLArray = (Pvoid_t) NULL;
As with an ordinary array, there are no duplicate indexes (strings) in
a JudySL array.
Using the macros described here, rather than the JudySL function calls,
the default error handling sends a message to the standard error and
terminates the program with exit(1). For other error handling methods,
see the ERRORS section.
Because the macro forms are faster and have a simpler error handling
interface than the equivalent functions, they are the preferred way to
call the JudySL functions.
Insert an Index string and value in the JudySL array PJSLArray.
If the Index is successfully inserted, the value is ini‐
tialized to 0. If the Index was already present, the
value is not modified.
Return PValue pointing to Index's value. Your program
must use this pointer to modify the value, for example:
*PValue = 1234;
Note: JSLI() and JSLD reorganize the JudySL array.
Therefore, pointers returned from previous JudySL calls
become invalid and must be reacquired.
Delete the specified Index/value pair (array element) from the
JudySL array.
Return Rc_int set to 1 if successful. array and it was
previously inserted. Return Rc_int set to 0 if Index
was not present.
Get the pointer to Index's value.
Return PValue pointing to Index's value. Return PValue
set to NULL if the Index was not present.
Given a pointer to a JudySL array (PJSLArray), free the entire array
(much faster
than using a JSLN(), JSLD() loop.)
Return Rc_word set to the number of bytes freed and PJS‐
LArray set to NULL.
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.
If successful, Index is returned set to the found index,
and PValue is returned set to a pointer to Index's
value. If unsuccessful, PValue is returned set to NULL,
and Index contains no useful information. PValue must
be tested for non-NULL prior to using Index, since a
search failure is possible.
Note: To accomodate all possible returns, the Index buf‐
fer must be at least as large as the largest string
stored in the array.
Search (inclusive) for the first index present that is equal to or
greater than the
passed Index string. (Start with a null string to find
the first index in the array.) JSLF() is typically used
to begin a sorted-order scan of the valid indexes in a
JudySL array.
char Index[MAXLINELEN];
strcpy (Index, "");
JSLF(PValue, PJSLArray, Index);
Search (exclusive) for the next index present that is greater than the
passed
Index string. JSLN() is typically used to continue a
sorted-order scan of the valid indexes in a JudySL
array, or to locate a "neighbor" of a given index.
Search (inclusive) for the last index present that is equal to or less
than the passed Index 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.) JSLL() is
typically used to begin a reverse-sorted-order scan of
the valid indexes in a JudySL array.
Search (exclusive) for the previous index present that is less than the
passed Index string. JSLP() is typically used to con‐
tinue a reverse-sorted-order scan of the valid indexes
in a JudySL array, or to locate a "neighbor" of a given
index.
ERRORS
There are two categories of Judy error returns:
1) User programming errors (bugs) such as memory corruption or invalid
pointers.
2) Out-of-memory (malloc() failure) when modifying a JudySL array with
JSLI() or JSLD().
There are three methods of handling errors when using the macros:
1) Default error handling.
2) User-specified JUDYERROR() macro.
3) Disable macro error handling.
The default is to print error messages to stderr, for example:
File 'YourCfile.c', line 1234: JudySLIns(), JU_ERRNO_* == 2, ID == 321
This indicates that an error occurred in a JSLI() call
at line 1234 in 'YourCfile.c'. JU_ERRNO_* == 2 is
JU_ERRNO_NOMEM (as defined in the Judy.h file). The ID
number indicates the Judy source line number where the
error was detected.
Your program then terminates with an exit(1).
The JUDYERROR() macro provides flexibility for
handling error returns
as needed to suit your program while still accessing
JudySL arrays using macros instead of function calls.
You can modify JUDYERROR() to distinguish between the
two types of errors (described above), and explicitly
test for the remaining JU_ERRNO_NOMEM errors possible in
your program.
// This is an example of JudySL macro API to continue when out of memory.
#ifndef JUDYERROR_NOTEST
#include <stdio.h>
// This is the macro that the Judy macro APIs use for return codes of -1:
#define JUDYERROR(CallerFile, CallerLine, JudyFunc, JudyErrno, JudyErrID) \
{ \
if ((JudyErrno) != JU_ERRNO_NOMEM) /* ! a malloc() failure */ \
{ \
(void) fprintf(stderr, "File '%s', line %d: %s(), " \
"JU_ERRNO_* == %d, ID == %d\n", \
CallerFile, CallerLine, \
JudyFunc, JudyErrno, JudyErrID); \
exit(1); \
} \
}
#endif // JUDYERROR_NOTEST not defined
This error handling macro must be included before the
#include <Judy.h> statement in your program.
When your program is "bug free",
the only errors occurring should be malloc(3) errors.
You can turn off error handling included in the JudySL
macros by using
#define JUDYERROR_NOTEST 1
(in your program code), or
cc -DJUDYERROR_NOTEST sourcefile -lJudy
(on your command line).
EXAMPLES
// This is an example of Judy macro API to continue when out of memory
// Put this before the #include <Judy.h>
// #define JUDYERROR_NOTEST // or defined with cc -DJUDYERROR_NOTEST ...
#ifndef JUDYERROR_NOTEST
#include <stdio.h>
// This is the macro the Judy macro APIs use for return codes of -1
#define JUDYERROR(CallerFile, CallerLine, JudyFunc, JudyErrno, JudyErrID) \
{ \
if ((JudyErrno) != JU_ERRNO_NOMEM) /* ! malloc() failure */ \
{ \
(void) fprintf(stderr, "File '%s', line %d: %s(), " \
"JU_ERRNO_* == %d, ID == %d\n", \
CallerFile, CallerLine, \
JudyFunc, JudyErrno, JudyErrID); \
exit(1); \
} \
}
#endif // JUDYERROR_NOTEST
#include <Judy.h>
#define MAXLINE 65536 // max string (line) len
// Count duplicate strings (lines) from stdin
int main()
{
Word_t * PValue; // Judy array element.
char Index[MAXLINE]; // string to check
Word_t Dups = 0; // duplicate strings counter
Pvoid_t PJSLArray = (Pvoid_t) NULL; // initialize JudySL
while (fgets(Index, MAXLINE, stdin)) // get string
{
JSLI(PValue, PJSLArray, Index); // store string
if (PValue == PJERR) // if out of memory?
{ // so do something
printf("Malloc failed -- get more ram\n");
exit(1);
}
if (++(*PValue) != 1) Dups++; // count dup strings
}
printf("%lu duplicate lines\n\n", Dups);
return (0);
}
AUTHOR
Judy was invented and implemented by Hewlett-Packard.
SEE ALSOJudy(3X), Judy1(3X), Judy1_funcs(3X), JudyL(3X), JudyL_funcs(3X),
JudySL_funcs(3X),
malloc(3),
the Judy website, http://www.hp.com/go/judy/, for further information
and Application Notes.
JudySL(3X)