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

FreeBSD Manual Pages

  
 
  

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

NAME
       Judy1  functions	- C library for	creating and accessing a dynamic array
       of bits,	using any value	of a word as an	index

SYNOPSIS
       int    Judy1Set(	      PPvoid_t PPJ1Array, Word_t   Index,  PJError_t PJError);
       int    Judy1Unset(     PPvoid_t PPJ1Array, Word_t   Index,  PJError_t PJError);
       int    Judy1Test(      Pcvoid_t	PJ1Array, Word_t   Index,  PJError_t PJError);
       Word_t Judy1Count(     Pcvoid_t	PJ1Array, Word_t   Index1, Word_t    Index2, PJError_t PJError);
       int    Judy1ByCount(   Pcvoid_t	PJ1Array, Word_t   Nth,	   Word_t * PIndex,  PJError_t PJError);
       Word_t Judy1FreeArray( PPvoid_t PPJ1Array, PJError_t PJError);
       Word_t Judy1MemUsed(   Pcvoid_t	PJ1Array);
       int    Judy1First(     Pcvoid_t	PJ1Array, Word_t * PIndex, PJError_t PJError);
       int    Judy1Next(      Pcvoid_t	PJ1Array, Word_t * PIndex, PJError_t PJError);
       int    Judy1Last(      Pcvoid_t	PJ1Array, Word_t * PIndex, PJError_t PJError);
       int    Judy1Prev(      Pcvoid_t	PJ1Array, Word_t * PIndex, PJError_t PJError);
       int    Judy1FirstEmpty(Pcvoid_t	PJ1Array, Word_t * PIndex, PJError_t PJError);
       int    Judy1NextEmpty( Pcvoid_t	PJ1Array, Word_t * PIndex, PJError_t PJError);
       int    Judy1LastEmpty( Pcvoid_t	PJ1Array, Word_t * PIndex, PJError_t PJError);
       int    Judy1PrevEmpty( Pcvoid_t	PJ1Array, Word_t * PIndex, 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  Judy1 functions.  See Judy1(3) for more information.  The function
       call definitions	are included here for completeness.

       One of the difficulties in using	the Judy1 function calls lies  in  de-
       termining whether to pass a pointer or the address of a pointer.	 Since
       the functions that modify the Judy1 array must also modify the  pointer
       to  the	Judy1  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  Judy1  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 detailed error information
       is not returned).

       In the following	descriptions, the functions are	described in terms  of
       how  the	 macros	use them (only in the case of #define JUDYERROR_NOTEST
       1).  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 information returned from
       the Judy1 functions when	an error occurs.

       Notice the placement of the & in	the different functions.

	Judy1Set(&PJ1Array, Index, &JError)

		      #define J1S(Rc_int, PJ1Array, Index) \
			 Rc_int	= Judy1Set(&PJ1Array, Index, PJE0)

	Judy1Unset(&PJ1Array, Index, &JError)

		      #define J1U(Rc_int, PJ1Array, Index) \
			 Rc_int	= Judy1Unset(&PJ1Array,	Index, PJE0)

	Judy1Test(PJ1Array, Index, &JError)

		      #define J1T(Rc_int, PJ1Array, Index) \
			 Rc_int	= Judy1Test(PJ1Array, Index, PJE0)

	Judy1Count(PJ1Array, Index1, Index2, &JError)

		      #define J1C(Rc_word, PJ1Array, Index1, Index2) \
			 Rc_word = Judy1Count(PJ1Array,	Index1,	Index2,	PJE0)

		      A	 return	 value of 0 can	be an error, valid as a	count,
		      or it can	indicate a special case	for a  fully-populated
		      array (32-bit machines only).  If	necessary, the follow-
		      ing code can be used to disambiguate this	return:

		      JError_t JError;

		      Rc_word =	Judy1Count(PJ1Array, Index1, Index2, &JError);
		      if (Rc_word == 0)
		      {
			  if (JU_ERRNO(&JError)	== JU_ERRNO_NONE)
			      printf("Judy1 array population ==	0\n");
			  if (JU_ERRNO(&JError)	== JU_ERRNO_FULL)
			      printf("Judy1 array population ==	2^32\n");
			  if (JU_ERRNO(&JError)	== JU_ERRNO_NULLPPARRAY)
			      goto NullArray;
			  if (JU_ERRNO(&JError)	>  JU_ERRNO_NFMAX)
			      goto Null_or_CorruptArray;
		      }

	Judy1ByCount(PJ1Array, Nth, &Index, &JError)

		      #define J1BC(Rc_int, PJ1Array, Nth, Index) \
			 Rc_int	= Judy1ByCount(PJ1Array, Nth, &Index, PJE0)

	Judy1FreeArray(&PJ1Array, &JError)

		      #define J1FA(Rc_word, PJ1Array) \
			 Rc_word = Judy1FreeArray(&PJ1Array, PJE0)

	Judy1MemUsed(PJ1Array)

		      #define J1MU(Rc_word, PJ1Array) \
			 Rc_word = Judy1MemUsed(PJ1Array)

	Judy1First(PJ1Array, &Index, &JError)

		      #define J1F(Rc_int, PJ1Array, Index) \
			 Rc_int	= Judy1First(PJ1Array, &Index, PJE0)

	Judy1Next(PJ1Array, &Index, &JError)

		      #define J1N(Rc_int, PJ1Array, Index) \
			 Rc_int	= Judy1Next(PJ1Array, &Index, PJE0)

	Judy1Last(PJ1Array, &Index, &JError)

		      #define J1L(Rc_int, PJ1Array, Index) \
			 Rc_int	= Judy1Last(PJ1Array, &Index, PJE0)

	Judy1Prev(PJ1Array, &Index, &JError)

		      #define J1P(Rc_int, PJ1Array, Index) \
			 Rc_int	= Judy1Prev(PJ1Array, &Index, PJE0)

	Judy1FirstEmpty(PJ1Array, &Index, &JError)

		      #define J1FE(Rc_int, PJ1Array, Index) \
			 Rc_int	= Judy1FirstEmpty(PJ1Array, &Index, PJE0)

	Judy1NextEmpty(PJ1Array, &Index, &JError)

		      #define J1NE(Rc_int, PJ1Array, Index) \
			 Rc_int	= Judy1NextEmpty(PJ1Array, &Index, PJE0)

	Judy1LastEmpty(PJ1Array, &Index, &JError)

		      #define J1LE(Rc_int, PJ1Array, Index) \
			 Rc_int	= Judy1LastEmpty(PJ1Array, &Index, PJE0)

	Judy1PrevEmpty(PJ1Array, &Index, &JError)

		      #define J1PE(Rc_int, PJ1Array, Index) \
			 Rc_int	= Judy1PrevEmpty(PJ1Array, &Index, PJE0)

       Definitions for all of 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, and	PJE0, are provided in the Judy.h header	file (/usr/in-
       clude/Judy.h).	Note:	Callers	 should	 define	 Judy1	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.

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

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

								Judy1_funcs(3)

NAME | SYNOPSIS | DESCRIPTION | AUTHOR | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Judy1FreeArray&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help