JudySL(3X) | JudySL(3X) |
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()
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.
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.
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.
Return PValue pointing to Index's value. Return PValue set to NULL if the Index was not present.
Return Rc_word set to the number of bytes freed and PJSLArray set to NULL.
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 buffer must be at least as large as the largest string stored in the array.
char Index[MAXLINELEN]; strcpy (Index, ""); JSLF(PValue, PJSLArray, Index);
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.
File 'YourCfile.c', line 1234: JudySLIns(), JU_ERRNO_* == 2, ID == 321This 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 definedThis 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).
// 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 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. char Index[MAXLINE]; // string to check while (fgets(Index, sizeof(Index), 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); }