Contents

class xr_homonym_iterator

Iterator over the homonyms ( xr_tuple ) of a token.

Initialize with sfile.token_homonym_iterator().

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

# set up sfile sf, then...
for e in sf.token_homonym_iterator(36, "foo"):
    print('xr_tuple: ', e)

xr_homonym_iterator Members

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

xr_homonym_iterator Details

class cs.xr_homonym_iterator

Iterator over the homonyms ( xr_tuple ) of a token.

__eq__(other)

Iterator equality.

Parameters:other (xr_homonym_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. 
>>> sf = next(s for s in project.current().sfiles()
...           if s.name().endswith('apitest.cpp'))
>>> sfi = sf.arbitrary_instance()
>>> iuse = next(i for i in range(1,sfi.line_count()+1) # find line containing 'i++'
...             if 'i++' in sfi.read_line(i))
>>> other_i_iterA = sf.token_homonym_iterator(iuse, 'i')
>>> other_i_iterB = sf.token_homonym_iterator(iuse, 'i')
>>> other_i_iterA == other_i_iterB
True
>>> for tup in other_i_iterA:
...      if tup.get_kind_role() == xr_kind_role.FIELD_DEFINITION:
...          break
...
>>> other_i_iterA == other_i_iterB
False
__iter__()

Get the iterator object.

Return type:xr_homonym_iterator
Returns:self. 
>>> sf = next(s for s in project.current().sfiles()
...           if s.name().endswith('apitest.cpp'))
>>> sfi = sf.arbitrary_instance()
>>> iuse = next(i for i in range(1,sfi.line_count()+1) # find line containing 'i++'
...             if 'i++' in sfi.read_line(i))
>>> other_i_iter = sf.token_homonym_iterator(iuse, 'i')
>>> for tup in other_i_iter:   # iteration managed by token_homonym_iterator.__iter__()
...                            # and token_homonym_iterator.__next__()
...     print(tup.get_kind_role(),
...           tup.get_file().normalized_name().split('/')[-1],
...           tup.get_line())
...
var_parameter_definition apitest.cpp 3
field_definition apitest.cpp 34
__ne__(other)

Iterator inequality.

Parameters:other (xr_homonym_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. 
>>> sf = next(s for s in project.current().sfiles()
...           if s.name().endswith('apitest.cpp'))
>>> sfi = sf.arbitrary_instance()
>>> iuse = next(i for i in range(1,sfi.line_count()+1) # find line containing 'i++'
...             if 'i++' in sfi.read_line(i))
>>> other_i_iterA = sf.token_homonym_iterator(iuse, 'i')
>>> other_i_iterB = sf.token_homonym_iterator(iuse, 'i')
>>> other_i_iterA != other_i_iterB
False
>>> for tup in other_i_iterA:
...      if tup.get_kind_role() == xr_kind_role.FIELD_DEFINITION:
...          break
...
>>> other_i_iterA != other_i_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)

>>> sf = next(s for s in project.current().sfiles()
...           if s.name().endswith('apitest.cpp'))
>>> sfi = sf.arbitrary_instance()
>>> iuse = next(i for i in range(1,sfi.line_count()+1) # find line containing 'i++'
...             if 'i++' in sfi.read_line(i))
>>> other_i_iter = sf.token_homonym_iterator(iuse, 'i')
>>> for tup in other_i_iter:   # iteration managed by token_homonym_iterator.__iter__()
...                            # and token_homonym_iterator.__next__()
...     print(tup.get_kind_role(),
...           tup.get_file().normalized_name().split('/')[-1],
...           tup.get_line())
...
var_parameter_definition apitest.cpp 3
field_definition apitest.cpp 34
__repr__()

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

Return type:str
Returns:The string representation. 
>>> sf = next(s for s in project.current().sfiles()
...           if s.name().endswith('apitest.cpp'))
>>> sfi = sf.arbitrary_instance()
>>> iuse = next(i for i in range(1,sfi.line_count()+1) # find line containing 'i++'
...             if 'i++' in sfi.read_line(i))
>>> other_i_iter = sf.token_homonym_iterator(iuse, 'i')
>>> repr(other_i_iter)
'<cs.xr_homonym_iterator begin>'
__str__()

Get a simple string representation of the iterator.

Return type:str
Returns:The string representation. 
>>> sf = next(s for s in project.current().sfiles()
...           if s.name().endswith('apitest.cpp'))
>>> sfi = sf.arbitrary_instance()
>>> iuse = next(i for i in range(1,sfi.line_count()+1) # find line containing 'i++'
...             if 'i++' in sfi.read_line(i))
>>> other_i_iter = sf.token_homonym_iterator(iuse, 'i')
>>> str(other_i_iter)
'<cs.xr_homonym_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. 
>>> sf = next(s for s in project.current().sfiles()
...           if s.name().endswith('apitest.cpp'))
>>> sfi = sf.arbitrary_instance()
>>> iuse = next(i for i in range(1,sfi.line_count()+1) # find line containing 'i++'
...             if 'i++' in sfi.read_line(i))
>>> other_i_iter = sf.token_homonym_iterator(iuse, 'i')
>>> other_i_iter.at_end()
False
>>> next(other_i_iter)
<cs.xr_tuple b40ac8c4d4562907, var_parameter_definition, <cs.sfile C:\alex\test\apitest.cpp>:3, <cs.sfile C:\alex\test\apitest.cpp>:3>
>>> next(other_i_iter)
<cs.xr_tuple b40ac8c4d4562907, field_definition, <cs.sfile C:\alex\test\apitest.cpp>:34, <cs.sfile C:\alex\test\apitest.cpp>:34>
>>> other_i_iter.at_end()
True
get_matched_count()

Get the number of tuples in the set to be iterated over by self.

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

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

>>> sf = next(s for s in project.current().sfiles()
...           if s.name().endswith('apitest.cpp'))
>>> sfi = sf.arbitrary_instance()
>>> iuse = next(i for i in range(1,sfi.line_count()+1) # find line containing 'i++'
...             if 'i++' in sfi.read_line(i))
>>> other_i_iter = sf.token_homonym_iterator(iuse, 'i', 0, xr_occ_iter_flags.POPULATE_COUNTERS)
>>> for tup in other_i_iter:   # iteration managed by token_homonym_iterator.__iter__()
...                            # and token_homonym_iterator.next()
...     print(tup.get_kind_role(),
...           tup.get_file().normalized_name().split('/')[-1],
...           tup.get_line())
...
var_parameter_definition apitest.cpp 3
field_definition apitest.cpp 34
>>> other_i_iter.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_homonym_iterator.get_matched_count(), plus all tuples examined but discarded as non-matching.
Raises:result.ERROR_INVALID_ARGUMENT If self was initialized with a sfile.token_homonym_iterator() call whose flags argument did not include xr_occ_iter_flags.POPULATE_COUNTERS, or if self was not initialized with sfile.token_homonym_iterator() at all.

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

>>> sf = next(s for s in project.current().sfiles()
...           if s.name().endswith('apitest.cpp'))
>>> sfi = sf.arbitrary_instance()
>>> iuse = next(i for i in range(1,sfi.line_count()+1) # find line containing 'i++'
...             if 'i++' in sfi.read_line(i))
>>> other_i_iter = sf.token_homonym_iterator(iuse, 'i', 0, xr_occ_iter_flags.POPULATE_COUNTERS)
>>> for tup in other_i_iter:   # iteration managed by token_homonym_iterator.__iter__()
...                            # and token_homonym_iterator.next()
...     print(tup.get_kind_role(),
...           tup.get_file().normalized_name().split('/')[-1],
...           tup.get_line())
...
var_parameter_definition apitest.cpp 3
field_definition apitest.cpp 34
>>> other_i_iter.get_scanned_count()
3
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. This can occur if the limit_per_kind_role specified for sfile.token_homonym_iterator() is reached for all xr_kind_role not excluded by the specified kr_filter.
Raises:result.ERROR_INVALID_ARGUMENT If self was initialized with a sfile.token_homonym_iterator() call whose flags argument did not include xr_occ_iter_flags.POPULATE_COUNTERS, or if self was not initialized with sfile.token_homonym_iterator() at all..

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

>>> sf = next(s for s in project.current().sfiles()
...           if s.name().endswith('apitest.cpp'))
>>> sfi = sf.arbitrary_instance()
>>> iuse = next(i for i in range(1,sfi.line_count()+1) # find line containing 'i++'
...             if 'i++' in sfi.read_line(i))
>>> other_i_iter = sf.token_homonym_iterator(iuse, 'i', 0, xr_occ_iter_flags.POPULATE_COUNTERS)
>>> for tup in other_i_iter:   # iteration managed by token_homonym_iterator.__iter__()
...                            # and token_homonym_iterator.next()
...     print(tup.get_kind_role(),
...           tup.get_file().normalized_name().split('/')[-1],
...           tup.get_line())
...
var_parameter_definition apitest.cpp 3
field_definition apitest.cpp 34
>>> other_i_iter.get_unscanned_count()
0