view release on metacpan or  search on metacpan

src/judy-1.0.5/doc/ext/JudyL_3.htm  view on Meta::CPAN

<B>JLF()</B> is typically used to <I>begin</I> a sorted-order scan of
the indexes present in a JudyL array.
<P>
<DT><A name="JLN"><B>JLN(PValue, PJLArray, Index)</B></A> // <A href="JudyL_funcs_3.htm#JudyLNext">JudyLNext()</A></DT>
<DD>
Search (exclusive) for the next index present that is greater than the passed
<B>Index</B>.
<B>JLN()</B> is typically used to <I>continue</I> a sorted-order scan of
the indexes present in a JudyL array, or to locate a "neighbor" of a given index.
<P>
<DT><A name="JLL"><B>JLL(PValue, PJLArray, Index)</B></A> // <A href="JudyL_funcs_3.htm#JudyLLast">JudyLLast()</A></DT>
<DD>
Search (inclusive) for the last index present that is equal to or less than the passed <B>Index</B>.
(Start with <B>Index</B> = -1, that is, all ones, to find the last index in the array.)
<B>JLL()</B> is typically used to <I>begin</I> a reverse-sorted-order
scan of the indexes present in a JudyL array.
<P>
<DT><A name="JLP"><B>JLP(PValue, PJLArray, Index)</B></A> // <A href="JudyL_funcs_3.htm#JudyLPrev">JudyLPrev()</A></DT>
<DD>
Search (exclusive) for the previous index present that is less than the
passed <B>Index</B>.
<B>JLP()</B> is typically used to <I>continue</I> a reverse-sorted-order
scan of the indexes present in a JudyL array, or to locate a "neighbor" of
a given index.
<P>
<DT><A name="JLFE"><B>JLFE(Rc_int, PJLArray, Index)</B></A> // <A href="JudyL_funcs_3.htm#JudyLFirstEmpty">JudyLFirstEmpty()</A></DT>
<DD>
Search (inclusive) for the first index absent that is equal to or greater than the passed
<B>Index</B>.
(Start with <B>Index</B> = 0 to find the first index absent in the array.)
<P>
<DT><A name="JLNE"><B>JLNE(Rc_int, PJLArray, Index)</B></A> // <A href="JudyL_funcs_3.htm#JudyLNextEmpty">JudyLNextEmpty()</A></DT>
<DD>
Search (exclusive) for the next index absent that is greater than the passed <B>Index</B>.
<P>
<DT><A name="JLLE"><B>JLLE(Rc_int, PJLArray, Index)</B></A> // <A href="JudyL_funcs_3.htm#JudyLLastEmpty">JudyLLastEmpty()</A></DT>
<DD>
Search (inclusive) for the last index absent that is equal to or less than the passed <B>Index</B>.
(Start with <B>Index</B> = -1, that is, all ones, to find the last index absent
in the array.)
<P>
<DT><A name="JLPE"><B>JLPE(Rc_int, PJLArray, Index)</B></A> // <A href="JudyL_funcs_3.htm#JudyLPrevEmpty">JudyLPrevEmpty()</A></DT>
<DD>
Search (exclusive) for the previous index absent that is less than the passed
<B>Index</B>.
</DL>
<!----------------->
<P>
<DT><B>Multi-dimensional JudyL Arrays</B></DT>
<DD>
Storing a pointer to another JudyL array in a JudyL array's <B>Value</B>
is a simple way to support dynamic multi-dimensional arrays.  
These arrays (or trees) built using JudyL arrays are very fast and 
memory efficient. (In fact, that is how JudySL and JudyHS are implemented).
An arbitrary number of dimensions can be realized this way.
To terminate the number of dimensions (or tree), the <B>Value</B> pointer is 
marked to <B>NOT</B> point to another Judy array. A <B>JLAP_INVALID</B> flag is 
used in the least significant bit(s) of the pointer.  
After the flag <B>JLAP_INVALID</B> is removed, it is used as a pointer to the users data.
The <B>Judy.h</B> header file defines <B>JLAP_INVALID</B>.
See code fragment below.
<P>
Note: The current version of <B>Judy.h</B> changed this flag from 0x4 to 0x1 
to allow for a <I>malloc()</I> that does not deliver memory on an 8 byte 
aligned boundry (such as old versions of valgrind).
<P>
The following example code segment can be used to determine whether or
not a pointer points to another JudyL:
<P>
<PRE>
PValue = (PWord_t)PMultiDimArray;

for (Dim = 0; ;Dim++)
{
   if (PValue == (PWord_t)NULL) goto IndexNotFound;

   /* Advance to next dimension in array */
   JLG(PValue, (Pvoid_t)*PValue, Index[Dim]);

   /* Check if pointer to user buffer: */
   if (*PValue &amp; JLAP_INVALID)) break;
}
UPointer = (UPointer_t) (*PValue &amp; ~JLAP_INVALID);  // mask and cast.
printf("User object pointer is 0x%lx\n", (Word_t) UPointer);
       ...
</PRE>
<P>
Note:  This works because <I>malloc()</I> guarantees to return a pointer
with the least bit(s) == 0x0.
You must remove <B>JLAP_INVALID</B> before using the pointer.
</DL>
<!----------------->
<P>
<DT><A name="JLERR"><B>ERRORS:</B> See: </A><A href="Judy_3.htm#ERRORS">Judy_3.htm#ERRORS</A></DT>
<DD>
<!----------------->
<P>
<DT><B>EXAMPLE</B></DT>
<DD>
Read a series of index/value pairs from the standard input, store
in a JudyL array, and then print out in sorted order.
<P>
<PRE>
#include &lt;stdio.h&gt;
#include &lt;Judy.h&gt;

Word_t   Index;                     // array index
Word_t   Value;                     // array element value
Word_t * PValue;                    // pointer to array element value
int      Rc_int;                    // return code

Pvoid_t  PJLArray = (Pvoid_t) NULL; // initialize JudyL array

while (scanf("%lu %lu", &amp;Index, &amp;Value))
{
    JLI(PValue, PJLArray, Index);
    If (PValue == PJERR) goto process_malloc_failure;
    *PValue = Value;                 // store new value
}
// Next, visit all the stored indexes in sorted order, first ascending,
// then descending, and delete each index during the descending pass.