Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
JudyHS_funcs(3)		   Library Functions Manual	       JudyHS_funcs(3)

NAME
       JudyHS  functions  - C library for creating and accessing a dynamic ar-
       ray, using an array-of-bytes of a length: Length	as an Index and	a word
       as a Value.

SYNOPSIS
       PPvoid_t	JudyHSIns(PPvoid_t PPJHS, void *Index, Word_t Length, PJError_t	PJError);
       int	JudyHSDel(PPvoid_t PPJHS, void *Index, Word_t Length, PJError_t	PJError);
       PPvoid_t	JudyHSGet(Pcvoid_t  PJHS, void *Index, Word_t Length, PJError_t	PJError);
       Word_t	JudyHSFreeArray(PPvoid_t PPJHS,	PJError_t PJError);

DESCRIPTION
       A macro equivalent exists for each function call.   Because  the	 macro
       forms  are sometimes faster and have a simpler error handling interface
       than the	equivalent functions, they are the preferred  way  of  calling
       the  JudyHS  functions.	See JudyHS(3) for more information.  The func-
       tion call definitions are included here for completeness.

       One of the difficulties in using	the JudyHS function calls lies in  de-
       termining whether to pass a pointer or the address of a pointer.	 Since
       the functions that modify the JudyHS array must also modify the pointer
       to  the	JudyHS	array, you must	pass the address of the	pointer	rather
       than the	pointer	itself.	 This often leads  to  hard-to-debug  program-
       matic errors.  In practice, the macros allow the	compiler to catch pro-
       gramming	 errors	 when  pointers	 instead  of addresses of pointers are
       passed.

       The JudyHS function calls have an  additional  parameter	 beyond	 those
       specified in the	macro calls.  This parameter is	either a pointer to an
       error  structure,  or  NULL (in which case the error information	is not
       returned	-- only	PJERR in the return parameter).

       In the following	descriptions, the functions are	described in terms  of
       how the macros use them.	 This is the suggested use of the macros after
       your  program has been fully debugged.  When the	JUDYERROR_NOTEST macro
       is not specified, an error structure is declared	to store error	infor-
       mation returned from the	JudyHS functions when an error occurs.

       Notice the placement of the & in	the different functions.

	JudyHSIns(&PJHS, Index,	Length,	&JError)

		      #define JHSI(PValue, PJHS, Index)	\
			 PValue	= JudyLIns(&PJHS, Index, PJE0)

	JudyHSDel(&PJHS, Index,	Length,	&JError)

		      #define JHSD(Rc_int, PJHS, Index,	Length)	\
			 Rc_int	= JudyHSDel(&PJHS, Index, Length, PJE0)

	JudyHSGet(PJHS,	Index, Length)

		      #define JHSG(PValue, PJHS, Index,	Length)	\
			 PValue	= JudyHSIns(PJHS, Index, Length)

	JudyHSFreeArray(&PJHS, &JError)

		      #define JHSFA(Rc_word, PJHS) \
			 Rc_word = JudyHSFreeArray(&PJHS, PJE0)

       Definitions  for	 all  the Judy functions, the types Pvoid_t, Pcvoid_t,
       PPvoid_t, Word_t	, JError_t, and	PJError_t, the constants NULL,	JU_ER-
       RNO_*,  JERR,  PPJERR,  and PJE0	are provided in	the Judy.h header file
       (/usr/include/Judy.h).  Note:  Callers should define JudyHS  arrays  as
       type  Pvoid_t,  which  can  be  passed  by value	to functions that take
       Pcvoid_t	(constant Pvoid_t), and	also by	address	to functions that take
       PPvoid_t.

       The return type from most JudyHS	functions is PPvoid_t so that the val-
       ues stored in the array can be pointers to other	objects,  which	 is  a
       typical	usage,	or cast	to a Word_t * when a pointer to	a value	is re-
       quired instead of a pointer to a	pointer.

AUTHOR
       JudyHS was invented and implemented by Doug Baskins after retiring from
       Hewlett-Packard.

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

							       JudyHS_funcs(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=JudyHSFreeArray&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>

home | help