stinger-iterator.h File Reference

#include "stinger.h"

Data Structures
struct	stinger_iterator

Typedefs
typedef struct stinger_iterator	stinger_iterator_t

Functions
stinger_iterator_t *	stinger_iterator_new (struct stinger *s)
	Allocate and initialize a new stinger_iterator_t.
stinger_iterator_t *	stinger_iterator_renew (stinger_iterator_t *iter, struct stinger *s)
	Clears filters from and resets an existing iterator.
void	stinger_iterator_free (stinger_iterator_t *iter)
	Frees an iterator and its internal data.
int64_t	stinger_iterator_consistency_check (stinger_iterator_t *iter, uint64_t nv)
	Tests to see if an iterator is in a valid state.
int	stinger_iterator_is_active (stinger_iterator_t *iter)
	Is the iterator in the middle of an iteration.
void	stinger_iterator_deactivate (stinger_iterator_t *iter)
	Deactivate an iterator.
stinger_iterator_t *	stinger_iterator_vertex_filter (int64_t *vertices, int64_t count, stinger_iterator_t *iter)
	Filter an iterator's traversal to only include a set of vertices and their neighbors.
stinger_iterator_t *	stinger_iterator_vertex_type_filter (int64_t *types, int64_t count, int both, stinger_iterator_t *iter)
	Filter an iterator's traversal to only include vertices of a certain type and optionally their neighbors.
stinger_iterator_t *	stinger_iterator_edge_type_filter (int64_t *types, int64_t count, stinger_iterator_t *iter)
	Filter an iterator's traversal to only include edges of a certain type.
stinger_iterator_t *	stinger_iterator_vertex_filter_no_copy (int64_t *vertices, int64_t count, stinger_iterator_t *iter)
	Filter an iterator's traversal to only include a set of vertices and their neighbors.
stinger_iterator_t *	stinger_iterator_vertex_type_filter_no_copy (int64_t *types, int64_t count, int both, stinger_iterator_t *iter)
	Filter an iterator's traversal to only include vertices of a certain type and optionally their neighbors.
stinger_iterator_t *	stinger_iterator_edge_type_filter_no_copy (int64_t *types, int64_t count, stinger_iterator_t *iter)
	Filter an iterator's traversal to only include edges of a certain type.
stinger_iterator_t *	stinger_iterator_created_before (int64_t time, stinger_iterator_t *iter)
	Filter an iterator's traversal to only include edges with a first time before the specified time.
stinger_iterator_t *	stinger_iterator_created_after (int64_t time, stinger_iterator_t *iter)
	Filter an iterator's traversal to only include edges with a first time after the specified time.
stinger_iterator_t *	stinger_iterator_modified_before (int64_t time, stinger_iterator_t *iter)
	Filter an iterator's traversal to only include edges with a recent time before the specified time.
stinger_iterator_t *	stinger_iterator_modified_after (int64_t time, stinger_iterator_t *iter)
	Filter an iterator's traversal to only include edges with a recent time after the specified time.
stinger_iterator_t *	stinger_iterator_custom_filter (int(*predicate)(stinger_iterator_t *), stinger_iterator_t *iter)
	Filter an iterator's traversal to only include edges that pass the user-specified predicate function.
int	stinger_iterator_next (stinger_iterator_t *iter)
	Advance an iterator to the next edge that matches the internal filter.
int64_t	stinger_iterator_loop_end (stinger_iterator_t *iter)
int	stinger_iterator_loop_jump (stinger_iterator_t *iter, int64_t i)
int	stinger_iterator_loop_next (stinger_iterator_t *iter)

Typedef Documentation

typedef struct stinger_iterator stinger_iterator_t

Function Documentation

int64_t stinger_iterator_consistency_check	(	stinger_iterator_t *	iter,
		uint64_t	nv
	)

Tests to see if an iterator is in a valid state.

Should return 0 for a valid iterator.

Parameters

iter	The iterator
nv	Maximum number of vertices

Returns

A bitfield of flags that each indicate an error

References stinger_etype_array::blocks, stinger_iterator_internal::created_after, stinger_iterator_internal::created_before, stinger_iterator_internal::cur_eb, stinger_iterator_internal::cur_edge, ebpool, stinger_iterator_internal::edge_type_filter, stinger_iterator_internal::edge_type_filter_count, stinger_iterator_internal::edge_type_index, stinger::ETA, stinger_eb::etype, stinger_iterator_internal::flags, stinger_eb::high, stinger_etype_array::high, stinger_iterator::i, stinger_iterator_internal::modified_after, stinger_iterator_internal::modified_before, stinger_iterator_internal::predicate, stinger_iterator_internal::s, STINGER_NUMETYPES, stinger_iterator_internal::vtx_filter, stinger_iterator_internal::vtx_filter_count, stinger_iterator_internal::vtx_index, and stinger_iterator_internal::vtx_type_filter.

stinger_iterator_t* stinger_iterator_created_after	(	int64_t	time,
		stinger_iterator_t *	iter
	)

Filter an iterator's traversal to only include edges with a first time after the specified time.

Parameters

time	The timestamp
iter	The iterator to be filtered

Returns

A pointer to the same iterator to allow function chaining

References stinger_iterator_internal::created_after, stinger_iterator_internal::flags, and stinger_iterator::i.

stinger_iterator_t* stinger_iterator_created_before	(	int64_t	time,
		stinger_iterator_t *	iter
	)

Filter an iterator's traversal to only include edges with a first time before the specified time.

Parameters

time	The timestamp
iter	The iterator to be filtered

Returns

A pointer to the same iterator to allow function chaining

References stinger_iterator_internal::created_before, stinger_iterator_internal::flags, and stinger_iterator::i.

stinger_iterator_t* stinger_iterator_custom_filter	(	int(*)(stinger_iterator_t *)	predicate,
		stinger_iterator_t *	iter
	)

Filter an iterator's traversal to only include edges that pass the user-specified predicate function.

The function pointer will be passed an iterator with an edge assigned to it to be tested.

Parameters

predicate	A function pointer that returns non-zero if the edge should be visited
iter	The iterator to be filtered

Returns

A pointer to the same iterator to allow function chaining

References stinger_iterator_internal::flags, stinger_iterator::i, and stinger_iterator_internal::predicate.

void stinger_iterator_deactivate

(

stinger_iterator_t *

iter

)

Deactivate an iterator.

Effectively resets an iterator to the beginning of its iteration without clearing any existing filters on the iterator. Useful if you want to restart the iteration, break from a current iteration, or change a filter.

NOTE: May not work for parallel iterators.

Parameters

iter	The iterator to be deactivated

References stinger_iterator_internal::active, and stinger_iterator::i.

stinger_iterator_t* stinger_iterator_edge_type_filter	(	int64_t *	types,
		int64_t	count,
		stinger_iterator_t *	iter
	)

Filter an iterator's traversal to only include edges of a certain type.

Should only be applied to an inactive iterator. Copies the array of edge types internally.

Parameters

types	An array of edge types
count	The number of edge types in the array
iter	The iterator to be filtered

Returns

A pointer to the same iterator to allow function chaining

References stinger_iterator_internal::edge_type_filter, stinger_iterator_internal::edge_type_filter_copy, stinger_iterator_internal::edge_type_filter_count, stinger_iterator_internal::flags, stinger_iterator::i, xelemcpy(), and xmalloc().

stinger_iterator_t* stinger_iterator_edge_type_filter_no_copy	(	int64_t *	types,
		int64_t	count,
		stinger_iterator_t *	iter
	)

Filter an iterator's traversal to only include edges of a certain type.

Should only be applied to an inactive iterator. Does not copy the array of edge types internally. The input array must remain constant while this iterator is in use.

Parameters

types	An array of edge types
count	The number of edge types in the array
iter	The iterator to be filtered

Returns

A pointer to the same iterator to allow function chaining

References stinger_iterator_internal::edge_type_filter, stinger_iterator_internal::edge_type_filter_copy, stinger_iterator_internal::edge_type_filter_count, stinger_iterator_internal::flags, and stinger_iterator::i.

void stinger_iterator_free

(

stinger_iterator_t *

iter

)

Frees an iterator and its internal data.

Parameters

iter	Pointer to the iterator

References stinger_iterator::i, stinger_iterator_internal::vtx_filter, stinger_iterator_internal::vtx_filter_copy, stinger_iterator_internal::vtx_type_filter, and stinger_iterator_internal::vtx_type_filter_copy.

int stinger_iterator_is_active

(

stinger_iterator_t *

iter

)

Is the iterator in the middle of an iteration.

Parameters

iter	The iterator in quesiton

Returns

A boolean int (active is 1)

References stinger_iterator_internal::active, and stinger_iterator::i.

int64_t stinger_iterator_loop_end

(

stinger_iterator_t *

iter

)

int stinger_iterator_loop_jump	(	stinger_iterator_t *	iter,
		int64_t	i
	)

int stinger_iterator_loop_next

(

stinger_iterator_t *

iter

)

stinger_iterator_t* stinger_iterator_modified_after	(	int64_t	time,
		stinger_iterator_t *	iter
	)

Filter an iterator's traversal to only include edges with a recent time after the specified time.

Parameters

time	The timestamp
iter	The iterator to be filtered

Returns

A pointer to the same iterator to allow function chaining

References stinger_iterator_internal::flags, stinger_iterator::i, and stinger_iterator_internal::modified_after.

stinger_iterator_t* stinger_iterator_modified_before	(	int64_t	time,
		stinger_iterator_t *	iter
	)

Filter an iterator's traversal to only include edges with a recent time before the specified time.

Parameters

time	The timestamp
iter	The iterator to be filtered

Returns

A pointer to the same iterator to allow function chaining

References stinger_iterator_internal::flags, stinger_iterator::i, and stinger_iterator_internal::modified_before.

stinger_iterator_t* stinger_iterator_new

(

struct stinger *

s

)

Allocate and initialize a new stinger_iterator_t.

Allocates and initializes a new iterator. Apply one or more filters to the iterator, then use stinger_iterator_next() in a while loop to advance through each edge in the graph that passes the filter. You are responsible for freeing this iterator via stinger_iterator_free().

Parameters

s	A valid STINGER structure to traverse

Returns

A pointer to a new stinger_iterator_t

References stinger_iterator_internal::edge_type_filter_copy, stinger_iterator::i, stinger_iterator_renew(), stinger_iterator_internal::vtx_filter_copy, stinger_iterator_internal::vtx_type_filter_copy, and xmalloc().

int stinger_iterator_next

(

stinger_iterator_t *

iter

)

Advance an iterator to the next edge that matches the internal filter.

This function will advance the iterator through the STINGER data in the most efficient manner possible based on the filters. It is intended to be used in a serial context. No particular ordering is guaranteed, but the iterator will visit all edges that pass the filter exactly one.

while(stinger_iterator_nex(iter)) {
    // do something with the current edge
}

Parameters

iter	The iterator to be advanced

Returns

A boolean int indicating more edges to be visited.

References stinger_iterator_internal::active, stinger_iterator_internal::cur_eb, stinger_iterator_internal::cur_edge, stinger_iterator_internal::edge_block_index, stinger_iterator_internal::edge_type_index, stinger_iterator_internal::flags, stinger_eb::high, stinger_iterator::i, stinger_eb_is_blank(), stinger_iterator_check_etype(), stinger_iterator_check_predicate(), stinger_iterator_check_time(), stinger_iterator_check_vtype(), stinger_iterator_get_edge(), stinger_iterator_next_block_all_types(), stinger_iterator_next_block_by_type(), stinger_iterator_next_block_by_vtx(), and stinger_iterator_internal::vtx_index.

stinger_iterator_t* stinger_iterator_renew	(	stinger_iterator_t *	iter,
		struct stinger *	s
	)

Clears filters from and resets an existing iterator.

Parameters

iter	The iterator to reset
s	A valid STINGER structure to traverse

Returns

A pointer to the same iterator to allow function chaining

References stinger_iterator_internal::active, stinger_iterator_internal::created_after, stinger_iterator_internal::created_before, stinger_iterator_internal::edge_type_filter_copy, stinger_iterator_internal::flags, stinger_iterator::i, stinger_iterator_internal::modified_after, stinger_iterator_internal::modified_before, stinger_iterator_internal::s, stinger_iterator_internal::vtx_filter, stinger_iterator_internal::vtx_filter_copy, stinger_iterator_internal::vtx_type_filter, and stinger_iterator_internal::vtx_type_filter_copy.

Referenced by stinger_iterator_new().

stinger_iterator_t* stinger_iterator_vertex_filter	(	int64_t *	vertices,
		int64_t	count,
		stinger_iterator_t *	iter
	)

Filter an iterator's traversal to only include a set of vertices and their neighbors.

Should only be applied to an inactive iterator. Copies the array of vertexIDs internally.

Parameters

vertices	An array of vertices
count	The number of vertices in the array
iter	The iterator to be filtered

Returns

A pointer to the same iterator to allow function chaining

References stinger_iterator_internal::flags, stinger_iterator::i, stinger_iterator_internal::vtx_filter, stinger_iterator_internal::vtx_filter_copy, stinger_iterator_internal::vtx_filter_count, xelemcpy(), and xmalloc().

stinger_iterator_t* stinger_iterator_vertex_filter_no_copy	(	int64_t *	vertices,
		int64_t	count,
		stinger_iterator_t *	iter
	)

Filter an iterator's traversal to only include a set of vertices and their neighbors.

Should only be applied to an inactive iterator. Does not copy the array of vertexIDs internally. The input array must remain constant while this iterator is in use.

Parameters

vertices	An array of vertices
count	The number of vertices in the array
iter	The iterator to be filtered

Returns

A pointer to the same iterator to allow function chaining

References stinger_iterator_internal::flags, stinger_iterator::i, stinger_iterator_internal::vtx_filter, stinger_iterator_internal::vtx_filter_copy, and stinger_iterator_internal::vtx_filter_count.

stinger_iterator_t* stinger_iterator_vertex_type_filter	(	int64_t *	types,
		int64_t	count,
		int	both,
		stinger_iterator_t *	iter
	)

Filter an iterator's traversal to only include vertices of a certain type and optionally their neighbors.

Should only be applied to an inactive iterator. Copies the array of vertex types internally.

Parameters

types	An array of vertex types
count	The number of vertex types in the array
both	Boolean indicating if both vertices must match the filter (1) or at least one (0).
iter	The iterator to be filtered

Returns

A pointer to the same iterator to allow function chaining

References stinger_iterator_internal::flags, stinger_iterator::i, stinger_iterator_internal::vtx_type_filter, stinger_iterator_internal::vtx_type_filter_both, stinger_iterator_internal::vtx_type_filter_copy, stinger_iterator_internal::vtx_type_filter_count, xelemcpy(), and xmalloc().

stinger_iterator_t* stinger_iterator_vertex_type_filter_no_copy	(	int64_t *	types,
		int64_t	count,
		int	both,
		stinger_iterator_t *	iter
	)

Filter an iterator's traversal to only include vertices of a certain type and optionally their neighbors.

Should only be applied to an inactive iterator. Does not copy the array of vertex types internally. The input array must remain constant while this iterator is in use.

Parameters

types	An array of vertex types
count	The number of vertex types in the array
both	Boolean indicating if both vertices must match the filter (1) or at least one (0).
iter	The iterator to be filtered

Returns

A pointer to the same iterator to allow function chaining

References stinger_iterator_internal::flags, stinger_iterator::i, stinger_iterator_internal::vtx_type_filter, stinger_iterator_internal::vtx_type_filter_both, stinger_iterator_internal::vtx_type_filter_copy, and stinger_iterator_internal::vtx_type_filter_count.