JSLP man page on HP-UX

Man page or keyword search:  
man Server   10987 pages
apropos Keyword Search (all sections)
Output format
HP-UX logo
[printable version]

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 ALSO
       Judy(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)
[top]

List of man pages available for HP-UX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net