quakeforge/include/QF/set.h

/*
	set.h

	Set manipulation.

	Copyright (C) 2012 Bill Currie <bill@taniwha.org>

	Author: Bill Currie <bill@taniwha.org>
	Date: 2012/8/4

	This program is free software; you can redistribute it and/or
	modify it under the terms of the GNU General Public License
	as published by the Free Software Foundation; either version 2
	of the License, or (at your option) any later version.

	This program is distributed in the hope that it will be useful,
	but WITHOUT ANY WARRANTY; without even the implied warranty of
	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

	See the GNU General Public License for more details.

	You should have received a copy of the GNU General Public License
	along with this program; if not, write to:

		Free Software Foundation, Inc.
		59 Temple Place - Suite 330
		Boston, MA  02111-1307, USA

*/

#ifndef __QF_set_h
#define __QF_set_h

#include "QF/qtypes.h"

/**	\defgroup set Set handling
	\ingroup utils
*/
///@{

//FIXME other archs
#ifdef __x86_64__
typedef uint64_t set_bits_t;
#else
typedef uint32_t set_bits_t;
#endif

#define SET_DEFMAP_SIZE ((32 - sizeof (struct set_s *) \
						  - sizeof (set_bits_t *) \
						  - sizeof (int) - sizeof (unsigned))\
						 / sizeof (set_bits_t))
#define SET_BITS (sizeof (set_bits_t) * 8)
//NOTE: x is the element number, so size is x + 1
#define SET_SIZE(x) (((x) + SET_BITS) & ~(SET_BITS - 1))
#define SET_WORDS(s) ((s)->size / SET_BITS)
#define SET_ZERO ((set_bits_t) 0)
#define SET_ONE ((set_bits_t) 1)
#define SET_TEST_MEMBER(s, x) \
	((s)->map[(x) / SET_BITS] & (SET_ONE << ((x) % SET_BITS)))

/** Represent a set using a bitmap.

	When \a inverted is zero, ones in the bitmap represent members, but when
	\a inverted is non-zero, zeros in the bitmap represent members. However,
	this really is all private implementation details and it is best to treat
	set_t as a black box.
*/
typedef struct set_s {
	struct set_s *next;				///< private. for ALLOC
	set_bits_t *map;				///< bitmap of set members
	int         inverted;			///< if true, 0 indicates membership
	unsigned    size;				///< number of representable members
	set_bits_t  defmap[SET_DEFMAP_SIZE];///< backing store for small sets
} set_t;

/** Represent the state of a scan through a set.

	Very useful in for-loops:
	\code
		set_t      *set;
		set_iter_t *iter;

		create_and_populate (set);
		for (iter = set_first (set); iter; iter = set_next (iter))
			do_something (iter->element);
	\endcode
*/
typedef struct set_iter_s {
	struct set_iter_s *next;	///< private. for ALLOC
	const set_t *set;			///< the set to which this iterator belongs
	/** The result of set_first() or set_next(). set_next() will start at the
		following element.

		\note	For inverted sets, indicates a non-member.
	*/
	unsigned    element;
} set_iter_t;

typedef struct set_pool_s {
	set_t      *set_freelist;
	set_iter_t *set_iter_freelist;
} set_pool_t;

void set_pool_init (set_pool_t *set_pool);

/** Delete a set iterator that is no longer needed.

	\param set_iter	The set iterator to be deleted.
*/
void set_del_iter (set_iter_t *set_iter);
void set_del_iter_r (set_pool_t *set_pool, set_iter_t *set_iter);

/** Create a new set.

	The set is initialized to be the empty set.

	\return			The newly created, empty set.
*/
set_t *set_new (void);
set_t *set_new_r (set_pool_t *set_pool);

/** Create a new set with space pre-allocated for the specified set size.

	Although sets automatically grow to accommodate new members as necessary,
	sometimes the maximum set size is known in advance and it can be more
	efficient to grow the set in advance.

	The set is initialized to be the empty set.

	\param size		The number of elements for which space is to be allocated.
	\return			The newly created, empty set.
*/
set_t *set_new_size (int size);
set_t *set_new_size_r (set_pool_t *set_pool, int size);

/** Delete a set that is no longer needed.

	\param set		The set to be deleted.
*/
void set_delete (set_t *set);
void set_delete_r (set_pool_t *set_pool, set_t *set);

/** Add an element to a set.

	It is not an error to add an element that is already a member of the set.

	\note \a set is modified.

	\param set		The set to which the element will be added.
	\param x		The element to be added.
	\return			The modified set.
*/
set_t *set_add (set_t *set, unsigned x);

/** Remove an element from a set.

	It is not an error to remove an element that is not a member of the set.

	\note \a set is modified.

	\param set		The set from which the element will be removed.
	\param x		The element to be removed.
	\return			The modified set.
*/
set_t *set_remove (set_t *set, unsigned x);

/** Compute the inverse of a set.

	The computation is done as \a set = ~\a set.

	\note \a set is modified.

	\param set		The set to be inverted.
	\return			The set modified to be ~\a src.
*/
set_t *set_invert (set_t *set);

/** Compute the union of two sets.

	The computation is done as \a dst = \a dst | \a src.

	\note \a dst is modified.

	\param dst		The destination set to be modified.
	\param src		The source set.
	\return			The destination set modified to be \a dst | \a src.
*/
set_t *set_union (set_t *dst, const set_t *src);

/** Compute the intersection of two sets.

	The computation is done as \a dst = \a dst & \a src.

	\note \a dst is modified.

	\param dst		The destination set to be modified.
	\param src		The source set.
	\return			The destination set modified to be \a dst & \a src.
*/
set_t *set_intersection (set_t *dst, const set_t *src);

/** Compute the diffedrence of two sets.

	The computation is done as \a dst = \a dst - \a src.

	\note \a dst is modified.

	\param dst		The destination set to be modified.
	\param src		The source set.
	\return			The destination set modified to be \a dst - \a src.
*/
set_t *set_difference (set_t *dst, const set_t *src);

/** Compute the diffedrence of two sets.

	The computation is done as \a dst = \a src - \a dst.

	\note \a dst is modified.

	\param dst		The destination set to be modified.
	\param src		The source set.
	\return			The destination set modified to be \a src - \a dst.
*/
set_t *set_reverse_difference (set_t *dst, const set_t *src);

/** Make a set equivalent to another.

	\note \a dst is modified.

	\param dst		The destination set to make equivalent.
	\param src		The source set to assign to \a dst.
	\return			The modified destination set.
*/
set_t *set_assign (set_t *dst, const set_t *src);

/** Make a set the empty set.

	\note \a set is modified.

	\param set		The set to make the empty set.
	\return			\a set.
*/
set_t *set_empty (set_t *set);

/** Make a set the set of everything.

	\note \a set is modified.

	\param set		The set to make the set of everything.
	\return			\a set.
*/
set_t *set_everything (set_t *set);

/** Test if a set is the empty set.

	\param set		The set to test.
	\return			1 if \a set is empty (non-inverted).
*/
int set_is_empty (const set_t *set) __attribute__((pure));

/** Test if a set is the set of everything.

	\param set		The set to test.
	\return			1 if \a set is the set of everything (empty inverted set).
*/
int set_is_everything (const set_t *set) __attribute__((pure));

/** Test if two sets are disjoint.

	\param s1		The first set to test.
	\param s2		The second set to test.
	\return			1 if \a s2 is disjoint from \a s1, 0 if not.

	\note	The emtpy set is disjoint with itself.
*/
int set_is_disjoint (const set_t *s1, const set_t *s2) __attribute__((pure));

/** Test if two sets intersect.

	\param s1		The first set to test.
	\param s2		The second set to test.
	\return			1 if \a s2 intersects \a s1, 0 if not.

	\note	Equivalent non-empty sets are treated as intersecting.
*/
int set_is_intersecting (const set_t *s1, const set_t *s2) __attribute__((pure));

/** Test if two sets are equivalent.

	\param s1		The first set to test.
	\param s2		The second set to test.
	\return			1 if \a s2 is equivalent to \a s1, 0 if not.
*/
int set_is_equivalent (const set_t *s1, const set_t *s2) __attribute__((pure));

/** Test if a set is a subset of another set.

	An equivalent set is considered to be a subset.

	\param set		The potential super-set.
	\param sub		The potential subset.
	\return			1 if \a sub is a subset of \a set, or if the sets are
					equivalent.
*/
int set_is_subset (const set_t *set, const set_t *sub) __attribute__((pure));

/** Test an element for membership in a set.

	\param set		The set to test.
	\param x		The element to test.
	\return			1 if the element is a member of the set, otherwise 0.
*/
int set_is_member (const set_t *set, unsigned x) __attribute__((pure));

/** Obtain the number of members (or non-members) of a set.

	Normal sets return the number of members, inverted sets return the number
	of non-members.

	\param set		The set from which the number of (non-)members will be
					obtained.
	\return			The number of (non-)members. Both empty sets and sets of
					evertything will return 0.
*/
unsigned set_size (const set_t *set) __attribute__((pure));

/** Find the first "member" of the set.

	\warning	For normal sets, the set iterator represents a member of the
				set, but for inverted sets, the set iterator represetns a
				<em>non</em>-member of the set.

	\param set		The set to scan.
	\return			A pointer to a set iterator indicating the first
					(non-)member of the set, or null if the set is empty or
					of everything.
*/
set_iter_t *set_first (const set_t *set);
set_iter_t *set_first_r (set_pool_t *set_pool, const set_t *set);

/** Find the next "member" of the set.

	\warning	For normal sets, the set iterator represents a member of the
				set, but for inverted sets, the set iterator represetns a
				<em>non</em>-member of the set.

	\param set_iter	The set iterator representing the state of the current
					scan.
	\return			A pointer to a set iterator indicating the next
					(non-)member of the set, or null if no mor (non-)members
					are available.

	\note	The set iterator is automatically deleted when the end of the set
			is reached.
*/
set_iter_t *set_next (set_iter_t *set_iter);
set_iter_t *set_next_r (set_pool_t *set_pool, set_iter_t *set_iter);

struct dstring_s;
/** Return a human-readable string representing the set.

	Empty sets will be represented by the string "{}". Sets of everything
	will be represented by the string "{...}". Inverted sets will have
	the first implicit member followed by "..." (eg, "256 ...").

	\param set		The set to be converted to a string.
	\return			The human readable representation of the string.

	\warning	The string is kept in a static variable, so subsequent calls
				will overwrite the results of preceeding calls.
*/
const char *set_as_string (const set_t *set);
/** Return a human-readable string representing the set.

	Empty sets will be represented by the string "{}". Sets of everything
	will be represented by the string "{...}". Inverted sets will have
	the first implicit member followed by "..." (eg, "256 ...").

	\param str		dstring to which the representation will be written
	\param set		The set to be converted to a string.
	\return			The string held in str

	\warning	The string is NOT cleared, but rather the set representation
				is appeneded to the string. This makes it more useful when
				constructing strings in a threaded environment.
*/
const char *set_as_string_r (struct dstring_s *str, const set_t *set);

///@}
#endif//__QF_set_h