Provided by: libjudy-dev_1.0.5-1ubuntu1_amd64 bug

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 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

       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 associated 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 associative
       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).

JSLI(PValue, PJSLArray, Index) // JudySLIns()

       Insert an Index string and  Value  in  the  JudySL  array  PJSLArray.   If  the  Index  is
       successfully  inserted,  the  Value is initialized 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.

JSLD(Rc_int, PJSLArray, Index) // JudySLDel()

       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.

JSLG(PValue, PJSLArray, Index) // JudySLGet()

       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.

JSLFA(Rc_word, PJSLArray) // JudySLFreeArray()

       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 PJSLArray set to NULL.

JudySL Search Functions

       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 buffer must be at least as large as
       the largest string stored in the array.

JSLF(PValue, PJSLArray, Index) // JudySLFirst()

       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.

       uint8_t Index[MAXLINELEN];
       strcpy (Index, "");
       JSLF(PValue, PJSLArray, Index);

JSLN(PValue, PJSLArray, Index) // JudySLNext()

       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.

JSLL(PValue, PJSLArray, Index) // JudySLLast()

       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.

JSLP(PValue, PJSLArray, Index) // JudySLPrev()

       Search  (exclusive)  for  the  previous  index  present that is less than the passed Index
       string.  JSLP() is typically used to continue a reverse-sorted-order  scan  of  the  valid
       indexes in a JudySL array, or to locate a "neighbor" of a given index.

ERRORS: See: Judy_3.htm#ERRORS

EXAMPLE of a string sort routine

       #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);
       }

AUTHOR

       Judy was invented by Doug Baskins and implemented by Hewlett-Packard.

SEE ALSO

       Judy(3), Judy1(3), JudyL(3), JudyHS(3),
       malloc(),
       the  Judy  website,  http://judy.sourceforge.net,  for further information and Application
       Notes.

                                                                                        JudySL(3)