Contents

class xr_query_iterator

Iterator over the results ( xr_tuple ) of an xr_query .

Initialize with project.token_search().

Use as you would any other Python iterator. For example:

# set up project proj and xr_query q, then...
for e in proj.token_search(q):
    print('xr_tuple: ', e)

xr_query_iterator Members

Constructors none
Methods __eq__(), __iter__(), __ne__(), __next__(), __repr__(), __str__(), at_end(), get_matched_count(), get_scanned_count(), get_unscanned_count()

xr_query_iterator Details

class cs.xr_query_iterator

Iterator over the results ( xr_tuple ) of an xr_query .

__eq__(other)

Iterator equality.

Parameters:other (xr_query_iterator) –
Return type:bool
Returns:True if and only if self and other are at the same position. Behavior is undefined if self and other are not iterating over the same collection. 
>>> q = xr_query()
>>> q.add_term_filter('whoknows')
>>> token_iterA = project.current().token_search(q)
>>> token_iterB = project.current().token_search(q)
>>> token_iterA == token_iterB
True
>>> for t in token_iterA:
...     if t.get_kind_role() == xr_kind_role.FUNC_CALL:
...         break
...
>>> token_iterA == token_iterB
False
__iter__()

Get the iterator object.

Return type:xr_query_iterator
Returns:self. 
>>> q = xr_query()
>>> q.add_term_filter('whoknows')
>>> for t in project.current().token_search(q):  # iteration managed by xr_query_iterator.__iter__()
...                                              # and xr_query_iterator.__next__()
...    print(t.get_file().normalized_name().split('/')[-1],
...          t.get_line(),
...  t.get_kind_role())
...
apitest.cpp 5 func_definition
apitest.cpp 6 func_call
__ne__(other)

Iterator inequality.

Parameters:other (xr_query_iterator) – The iterator to compare against.
Return type:bool
Returns:False if and only if self and other are at the same position. Behavior is undefined if self and other are not iterating over the same collection. 
>>> q = xr_query()
>>> q.add_term_filter('whoknows')
>>> token_iterA = project.current().token_search(q)
>>> token_iterB = project.current().token_search(q)
>>> token_iterA != token_iterB
False
>>> for t in token_iterA:
...     if t.get_kind_role() == xr_kind_role.FUNC_CALL:
...         break
...
>>> token_iterA != token_iterB
True
__next__()

Iterator dereference operator.

Return type:xr_tuple
Returns:The element at the current iterator position.
Raises:StopIteration
  • Side effects: Modifies self.

The typical use is implicit:

>>> for item in myiter:
...   (do something to item)

>>> q = xr_query()
>>> q.add_term_filter('whoknows')
>>> for t in project.current().token_search(q):  # iteration managed by xr_query_iterator.__iter__()
...                                              # and xr_query_iterator.__next__()
...    print(t.get_file().normalized_name().split('/')[-1],
...          t.get_line(),
...  t.get_kind_role())
...
apitest.cpp 5 func_definition
apitest.cpp 6 func_call
__repr__()

Get a representation of the iterator that includes information useful for debugging.

Return type:str
Returns:The string representation. 
>>> q = xr_query()
>>> q.add_term_filter('whoknows')
>>> q.set_flags(xr_query_flags.POPULATE_COUNTERS)
>>> queryiter = project.current().token_search(q)
>>> repr(queryiter)
'<cs.xr_query_iterator begin>'
__str__()

Get a simple string representation of the iterator.

Return type:str
Returns:The string representation. 
>>> q = xr_query()
>>> q.add_term_filter('whoknows')
>>> q.set_flags(xr_query_flags.POPULATE_COUNTERS)
>>> queryiter = project.current().token_search(q)
>>> str(queryiter)
'<cs.xr_query_iterator begin>'
at_end()

Check: is the iterator at the end of the structure?

Return type:bool
Returns:True if the iterator is at the end of the structure (there are no more elements to iterate over), False otherwise. 
>>> q = xr_query()
>>> q.add_term_filter('whoknows')
>>> q.set_flags(xr_query_flags.POPULATE_COUNTERS)
>>> queryiter = project.current().token_search(q)
>>> queryiter.at_end()
False
>>> for tup in queryiter:
...    print(tup.get_kind_role(),
...          tup.get_file().normalized_name().split('/')[-1],
...          tup.get_line())
...
func_definition apitest.cpp 5
func_call apitest.cpp 6
>>> queryiter.at_end()
True
get_matched_count()

Get the number of tuples ( xr_tuple ) in the query result set for self.

Return type:int
Returns:The number of tuples in the query result set.
Raises:result.ERROR_INVALID_ARGUMENT if self was initialized with a project.token_search() call whose argument was an xr_query whose flags did not include xr_query_flags.POPULATE_COUNTERS, or if self was not initialized with project.token_search() at all.

Note that the return value may grow as iteration progresses. For the final value, call after at_end() returns True.

>>> q = xr_query()
>>> q.add_term_filter('whoknows')
>>> q.set_flags(xr_query_flags.POPULATE_COUNTERS)
>>> queryiter = project.current().token_search(q)
>>> queryiter.at_end()
False
>>> for tup in queryiter:
...    print(tup.get_kind_role(),
...          tup.get_file().normalized_name().split('/')[-1],
...          tup.get_line())
...
func_definition apitest.cpp 5
func_call apitest.cpp 6
>>> queryiter.get_matched_count()
2
get_scanned_count()

Get the total number of tuples ( xr_tuple ) examined while retrieving the set to be iterated over by self.

Return type:int
Returns:The total number of tuples examined: the tuples enumerated by xr_query_iterator.get_matched_count(), plus all tuples examined but discarded as non-matching.
Raises:result.ERROR_INVALID_ARGUMENT if self was initialized with a project.token_search() call whose argument was an xr_query whose flags did not include xr_query_flags.POPULATE_COUNTERS, or if self was not initialized with project.token_search() at all.

Note that the return value may grow as iteration progresses. For the final value, call after at_end() returns True.

>>> q = xr_query()
>>> q.add_term_filter('whoknows')
>>> q.set_flags(xr_query_flags.POPULATE_COUNTERS)
>>> queryiter = project.current().token_search(q)
>>> queryiter.at_end()
False
>>> for tup in queryiter:
...    print(tup.get_kind_role(),
...          tup.get_file().normalized_name().split('/')[-1],
...          tup.get_line())
...
func_definition apitest.cpp 5
func_call apitest.cpp 6
>>> queryiter.get_scanned_count()
2
get_unscanned_count()

Get the number of tuples ( xr_tuple ) that were indexed for examination but ultimately not examined while retrieving the set to be iterated over by self.

Return type:int
Returns:The number of tuples ( xr_tuple ) that were indexed for examination but ultimately not examined.
Raises:result.ERROR_INVALID_ARGUMENT if self was initialized with a project.token_search() call whose argument was an xr_query whose flags did not include xr_query_flags.POPULATE_COUNTERS, or if self was not initialized with project.token_search() at all.

Note that the return value may grow as iteration progresses. For the final value, call after at_end() returns True.

>>> q = xr_query()
>>> q.add_term_filter('whoknows')
>>> q.set_flags(xr_query_flags.POPULATE_COUNTERS)
>>> queryiter = project.current().token_search(q)
>>> queryiter.at_end()
False
>>> for tup in queryiter:
...    print(tup.get_kind_role(),
...          tup.get_file().normalized_name().split('/')[-1],
...          tup.get_line())
...
func_definition apitest.cpp 5
func_call apitest.cpp 6
>>> queryiter.get_unscanned_count()
0