JudyHS(3) Library Functions Manual JudyHS(3) # [NAME](#NAME) JudyHS macros - C library for creating and accessing a dynamic array, using an array-of-bytes of **Length** as an **Index** and a word as a **Value**. # [SYNOPSIS](#SYNOPSIS) ``` cc [flags] sourcefiles -lJudy ``` ``` #include ``` ``` Word_t * PValue; // JudyHS array element int Rc_int; // return flag Word_t Rc_word; // full word return value Pvoid_t PJHSArray = (Pvoid_t) NULL; // initialize JudyHS array uint8_t * Index; // array-of-bytes pointer Word_t Length; // number of bytes in Index ``` ``` JHSI( PValue, PJHSArray, Index, Length); // JudyHSIns() JHSD( Rc_int, PJHSArray, Index, Length); // JudyHSDel() JHSG( PValue, PJHSArray, Index, Length); // JudyHSGet() JHSFA(Rc_word, PJHSArray); // JudyHSFreeArray() ``` # [DESCRIPTION](#DESCRIPTION) A JudyHS array is the equivalent of an array of word-sized value/pointers. An **Index** is a pointer to an array-of-bytes of specified length: **Length**. Rather than using a null terminated string, this difference from [*JudySL*(3)](/man/os/libjudy/JudySL.3) allows strings to contain all bits (specifically the null character). This new addition (May 2004) to Judy arrays is a hybird using the best capabilities of hashing and Judy methods. **JudyHS** does not have a poor performance case where knowledge of the hash algorithm can be used to degrade the performance. Since JudyHS is based on a hash method, **Indexes** are not stored in any particular order. Therefore the JudyHSFirst(), JudyHSNext(), JudyHSPrev() and JudyHSLast() neighbor search functions are not practical. The **Length** of each array-of-bytes can be from 0 to the limits of *malloc()* (about 2GB). The hallmark of **JudyHS** is speed with scalability, but memory efficiency is excellent. The speed is very competitive with the best hashing methods. The memory efficiency is similar to a linked list of the same **Indexes** and **Values**. **JudyHS** is designed to scale from 0 to billions of **Indexes**. A JudyHS array is allocated with a **NULL** pointer ``` Pvoid_t PJHSArray = (Pvoid_t) NULL; ``` Because the macro forms of the API have a simpler error handling interface than the equivalent *functions*, they are the preferred way to use JudyHS. # **JHSI(PValue,** **PJHSArray,** **Index,** **Length)** // **JudyHSIns()** Given a pointer to a JudyHS array (**PJHSArray**), insert an **Index** string of length: **Length** and a **Value** into the JudyHS array: **PJHSArray**. 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 **Value**. Your program should use this pointer to read or modify the **Value**, for example: ``` Value = *PValue; *PValue = 1234; ``` **Note**: **JHSI()** and **JHSD** can reorganize the JudyHS array. Therefore, pointers returned from previous **JudyHS** calls become invalid and must be re-acquired (using **JHSG()**). # **JHSD(Rc\_int,** **PJHSArray,** **Index,** **Length)** // **JudyHSDel()** Given a pointer to a JudyHS array (**PJHSArray**), delete the specified **Index** along with the **Value** from the JudyHS array. Return **Rc\_int** set to 1 if successfully removed from the array. Return **Rc\_int** set to 0 if **Index** was not present. # **JHSG(PValue,** **PJHSArray,** **Index,** **Length)** // **JudyHSGet()** Given a pointer to a JudyHS array (**PJHSArray**), find **Value** associated with **Index**. Return **PValue** pointing to **Index**'s **Value**. Return **PValue** set to **NULL** if the **Index** was not present. # **JHSFA(Rc\_word,** **PJHSArray)** // **JudyHSFreeArray()** Given a pointer to a JudyHS array (**PJHSArray**), free the entire array. Return **Rc\_word** set to the number of bytes freed and **PJHSArray** set to NULL. # **ERRORS:** See: *Judy\_3.htm#ERRORS* # [EXAMPLES](#EXAMPLES) Show how to program with the JudyHS macros. This program will print duplicate lines and their line number from *stdin*. ``` #include #include #include #include ``` ``` // Compiled: // cc -O PrintDupLines.c -lJudy -o PrintDupLines ``` ``` #define MAXLINE 1000000 /* max fgets length of line */ uint8_t Index[MAXLINE]; // string to check ``` ``` int // Usage: PrintDupLines < file main() { Pvoid_t PJArray = (PWord_t)NULL; // Judy array. PWord_t PValue; // Judy array element pointer. Word_t Bytes; // size of JudyHS array. Word_t LineNumb = 0; // current line number Word_t Dups = 0; // number of duplicate lines ``` ``` while (fgets(Index, MAXLINE, stdin) != (char *)NULL) { LineNumb++; // line number ``` ``` // store string into array JHSI(PValue, PJArray, Index, strlen(Index)); if (PValue == PJERR) // See ERRORS section { fprintf(stderr, "Out of memory -- exit\n"); exit(1); } if (*PValue == 0) // check if duplicate { Dups++; printf("Duplicate lines %lu:%lu:%s", *PValue, LineNumb, Index); } else { *PValue = LineNumb; // store Line number } } printf("%lu Duplicates, free JudyHS array of %lu Lines\n", Dups, LineNumb - Dups); JHSFA(Bytes, PJArray); // free JudyHS array printf("JudyHSFreeArray() free'ed %lu bytes of memory\n", Bytes); return (0); } ``` # [AUTHOR](#AUTHOR) JudyHS was invented and implemented by Doug Baskins after retiring from Hewlett-Packard. # [SEE ALSO](#SEE_ALSO) [*Judy*(3)](/man/os/libjudy/Judy.3), [*Judy1*(3)](/man/os/libjudy/Judy1.3), [*JudyL*(3)](/man/os/libjudy/JudyL.3), [*JudySL*(3)](/man/os/libjudy/JudySL.3), *malloc()*, the Judy website, *http://judy.sourceforge.net*, for further information and Application Notes. --- Document: JHSFA(3) from libjudy 1.0.5-r5 (Chainguard OS) Source: https://sourceforge.net/projects/judy/files/judy/Judy-1.0.5/Judy-1.0.5.tar.gz