Contents

class sfile

A source file.

A project is a combination of compilation units ( compunit ). Each compilation unit has:

  • a top-level file instance,
  • a collection of include-file instances, and
  • command-line flags used for the compilation.

We distinguish between “files” ( sfile ) and “file instances” ( sfileinst ) because a given file may be used multiple times in a project.

For example, suppose we build a project by observing the compilation of m.c.

gcc -c m.c

Where the project source files are as follows.

/* mainfile.c */
#include "a.h"
#include "b.h"
#define ONE
#include "b.h"
#undef ONE
/* ... */

/* a.h */
/* (no #include statements) */

/* b.h */
#ifdef ONE
#include "a.h"
#else
#include "c.h"
#endif
/* ... */

/* c.h */
/* (no #include statements) */

The project has:

  • One compilation unit ( compunit ), representing this observed compilation. The compilation unit’s top level file is m.c.
  • Four source files ( sfile ): m.c, a.h, b.h, c.h.
  • Six source file instances ( sfileinst ):
    • One instance of m.c, corresponding to its role as the top level file in the compilation unit.
    • Two instances of a.h: one for its inclusion in m.c and one for its inclusion in b.h.
    • Two instances of b.h, corresponding to its two inclusions in m.c.
    • One instance of c.h, corresponding to its inclusion in b.h.

The following image illustrates the relationships between compilation unit, source files, and source file instances in this project.


diagram of example project

For more information, see the Source Files manual page.

The following are useful for retrieving source files.

Class Methods
directory directory.files()
project project.sfiles()
sfileinst sfileinst.get_sfile()

Note that line numbers in source file instances are with respect to the unpreprocessed file.

sfile Members

Constructors none
Methods __cmp__(), __eq__(), __ge__(), __gt__(), __hash__(), __le__(), __lt__(), __ne__(), __repr__(), __str__(), arbitrary_instance(), handle(), hash64(), instances(), name(), normalized_name(), parent(), procedures_on_line(), procedures_on_line_fast(), range_definition_iterator(), stable_cmp(), stable_hash(), token_definition_iterator(), token_homonym_iterator(), token_occurrence_iterator()

sfile Details

class cs.sfile

A source file.

__cmp__(other)

Comparison function for sfile .

Parameters:other (sfile) – The sfile object to compare against.
Return type:int
Returns:An integer N such that:
  • N==0 if the two objects compare equal
  • N<0 if self < other
  • N>0 if self > other
 
>>> sfs = project.current().sfiles()
>>> sf1 = next(sfs)
>>> sf2 = next(sfs)
>>> sf1.__cmp__(sf2)
1
__eq__(b)

Equality operator for sfile .

Parameters:b (sfile) – The sfile to compare against.
Return type:bool
Returns:True if self and b compare equal, False otherwise. 
>>> sfs = project.current().sfiles()
>>> sf1 = next(sfs)
>>> sf2 = next(sfs)
>>> sf1 == sf2
False
__ge__(b)

Greater-than-or-equal operator for sfile .

Parameters:b (sfile) – The sfile to compare against.
Return type:bool
Returns:True if self >= b , False otherwise. 
>>> sfs = project.current().sfiles()
>>> sf1 = next(sfs)
>>> sf2 = next(sfs)
>>> sf1 >= sf2
True
__gt__(b)

Greater-than operator for sfile .

Parameters:b (sfile) – The sfile to compare against.
Return type:bool
Returns:True if self > b , False otherwise. 
>>> sfs = project.current().sfiles()
>>> sf1 = next(sfs)
>>> sf2 = next(sfs)
>>> sf1 > sf2
True
__hash__()

Get a hash value for a sfile .

Return type:int 
>>> sfs = project.current().sfiles()
>>> sf1 = next(sfs)
>>> hash(sf1)
479447928
__le__(b)

Less-than-or-equal operator for sfile .

Parameters:b (sfile) – The sfile to compare against.
Return type:bool
Returns:True if self <= b , False otherwise. 
>>> sfs = project.current().sfiles()
>>> sf1 = next(sfs)
>>> sf2 = next(sfs)
>>> sf1 <= sf2
False
__lt__(b)

Less-than operator for sfile .

Parameters:b (sfile) – The sfile to compare against.
Return type:bool
Returns:True if self < b , False otherwise. 
>>> sfs = project.current().sfiles()
>>> sf1 = next(sfs)
>>> sf2 = next(sfs)
>>> sf1 < sf2
False
__ne__(b)

Inequality operator for sfile .

Parameters:b (sfile) – The sfile to compare against.
Return type:bool
Returns:False if self and b compare equal, True otherwise. 
>>> sfs = project.current().sfiles()
>>> sf1 = next(sfs)
>>> sf2 = next(sfs)
>>> sf1 != sf2
True
__repr__()

Get a representation of a sfile object that includes information useful for debugging.

Return type:str
Returns:The string representation. 
>>> sfs = project.current().sfiles()
>>> sf1 = next(sfs)
>>> repr(sf1)
'<cs.sfile C:\\alex\\test\\apitest.cpp>'
__str__()

Get a simple string representation of a sfile object.

Return type:str
Returns:The string representation. 
>>> sfs = project.current().sfiles()
>>> sf1 = next(sfs)
>>> str(sf1)
'C:\\alex\\test\\apitest.cpp'
arbitrary_instance()

Get an (arbitrary) instance of a source file.

Return type:sfileinst
Returns:An instance ( sfileinst ) of the source file.
Raises:result.ELEMENT_NOT_PRESENT if the project contains no instances of the source file.

For every source file F in the project there are one or more instances.

  • One instance for each compilation unit ( compunit ) in which F is the top-level file.
  • One instance for each occurrence of F in the include tree of any compilation unit (note that a single compilation unit could include multiple instances of the same file.

This method returns one of the instances of this source file. For all instances, use sfile.instances().

>>> sfs = project.current().sfiles()
>>> sf1 = next(sfs)
>>> sf1.arbitrary_instance()
<cs.sfileinst C:\alex\test\apitest.cpp>
handle()

Get a handle for this sfile .

Return type:str
Returns:The sfile’s handle.

Use this function to retrieve a handle to the sfile which can be stored externally and used with project.lookup_sfile_handle() to retrieve the sfile when needed. This handle is valid only for the analysis it was generated from. If you rebuild the project, the handle will no longer be valid.

A handle is a string consisting of letters (upper and lower case) and numbers, and could also include the following characters: “+”, “=”, and “_”.

>>> sfs = project.current().sfiles()
>>> sf1 = next(sfs)
>>> sf1.handle()
'ka3n9fPp14_jAQ=='
hash64()

64-bit hash function for sfile .

Return type:int
Returns:A 64-bit hash value derived from the source file path and contents. 
>>> sfs = project.current().sfiles()
>>> sf1 = next(sfs)
>>> sf1.hash64()
10263791891286004919
instances()

Get an iterator over the instances ( sfileinst ) of a source file.

Return type:sfile_instance_iterator
Returns:The initialized sfile_instance_iterator .

For every source file F in the project there are one or more instances.

  • One instance for each compilation unit ( compunit ) in which F is the top-level file.
  • One instance for each occurrence of F in the include tree of any compilation unit (note that a single compilation unit could include multiple instances of the same file.

This method returns an iterator over all the instances of this source file. For a single, arbitrary instance, use sfile.arbitrary_instance().

>>> sf = next(s for s in project.current().sfiles() if s.name().endswith('apitest.h'))
>>> for sfi in sf.instances():  # iteration managed by sfile_instance_iterator.__iter__()
...                              # and sfile_instance_iterator.__next__()
...     print('compunit=', sfi.get_compunit())
...     print('path=', ' | '.join([str(s) for s in sfi.include_tree_path()]))
...     print('---')
...
compunit= C:\alex\test\apitest.cpp
path= C:\alex\test\apitest.cpp | C:\alex\test\apitest.h
---
name()

Get the unnormalized absolute path name for a source file.

Return type:

str
Returns:

The unnormalized absolute path name.
Raises:

Use sfile.normalized_name() to get the normalized file path.

>>> sf = next(s for s in project.current().sfiles() if s.name().endswith('apitest.h'))
>>> sf.name()
'C:\\alex\\test\\apitest.h'
normalized_name()

Get the normalized absolute path name for a source file.

Return type:

str
Returns:

The normalized absolute path name.

  • Windows: this path is the downcased version of the one returned by sfile.name(), with backslash directory separators replaced by forward slashes.
  • Mac: this path is the downcased version of the one returned by sfile.name().
  • Otherwise: this path is the same as the one returned by sfile.name().
Raises:

Use sfile.name() to get the unnormalized file path.

>>> sf = next(s for s in project.current().sfiles() if s.name().endswith('apitest.h'))
>>> sf.normalized_name()
'c:/alex/test/apitest.h'
parent()

Get the parent directory for a source file.

Return type:directory
Returns:The parent directory . 
>>> sf = next(s for s in project.current().sfiles() if s.name().endswith('apitest.h'))
>>> sf.parent()
<cs.directory C:\alex\test>
procedures_on_line(ln[, exact = false])

Get the procedures whose definition appears on the specified line in a source file.

Parameters:
  • ln (int) – The line number in the source file.
  • exact (bool) – (optional) If true, this function only returns procedures that are considered to be “defined on” the given line. Otherwise, it returns procedures for which at least part of the definition appears on the given line. The concept of “defined on” is not necessarily a well-defined one; when in doubt, it is better to set this to False.
Return type:

[procedure]
Returns:

A list of the procedures ( procedure ) found at ln in the source file.

 
>>> apitest_cpp_sf = next(s for s in project.current().sfiles() if s.name().endswith('apitest.cpp'))
>>> apitest_cpp_sf.procedures_on_line(14,False)
(<cs.procedure bar>,)

>>> apitest_cpp_sf = next(s for s in project.current().sfiles() if s.name().endswith('apitest.cpp'))
>>> apitest_cpp_sf.procedures_on_line(17)
(<cs.procedure bar>,)
procedures_on_line_fast(ln, closest)

Get all procedures defined on the specified line of a source file.

Parameters:
  • ln (int) – The source file line number on which the procedure definition starts.
  • closest (bool) –

    Specifies how the function should behave if there are no procedures defined on line ln of the file.

    • true: finds the highest line L<=ln in the file such that the definition of at least one procedure begins on L, and gets the matches from that line. If there is no such line L, the result list is empty.
    • False : the result list is empty.
    • If there is at least one procedure definition on line ln, this parameter has no effect.
Return type:

[procedure]
Returns:

A list of the procedures ( procedure ) whose definitions occur on the line determined by ln and closest.
Raises:

result.ERROR_INVALID_PHASE_FOR_OPERATION if called before the end of the serial depth-first analysis phase.

To restrict to procedures with a specific name, use the three-argument form of procedures_on_line_fast().

>>> v0 = project.current()
>>> v1 = xr_query()
>>> v2 = v0.token_search(v1)
>>> v3 = v2.next()
>>> v4 = v3.get_def_file()
>>> v4.procedures_on_line_fast(52, True)
(<cs.procedure foo>,)
procedures_on_line_fast(ln, friendly_name_hash, closest)

Get all procedures with the specified name defined on the specified line of a source file.

Parameters:
  • ln (int) – The source file line number on which the procedure definition starts.
  • friendly_name_hash (int) – The hash (string_hash()) of the procedure friendly name (procedure.name()).
  • closest (bool) –

    Specifies how the function should behave if there are no procedures matching friendly_name_hash defined on line ln of the file.

    • true: finds the highest line L<=ln in the file such that the definition of at least one procedure matching friendly_name_hash begins on L, and gets the matches from that line. If there is no such line L, the result list is empty.
    • False : the result list is empty.
    • If there is at least one procedure definition matching friendly_name_hash on line ln, this parameter has no effect.
Return type:

[procedure]
Returns:

A list of the procedures ( procedure ) matching friendly_name_hash whose definitions occur on the line determined by ln and closest.
Raises:

To get all procedures on a line regardless of name, use the three-argument form of procedures_on_line_fast().

>>> v0 = project.current()
>>> v1 = xr_query()
>>> v2 = v0.token_search(v1)
>>> v3 = v2.next()
>>> v4 = v3.get_def_file()
>>> v4.procedures_on_line_fast(14, 90, True)
(<cs.procedure bar>,)
range_definition_iterator(lb, ub)

Given a code region in a source file, get an iterator over the definitions of all source entities with occurrences in that region.

Parameters:
  • lb (int) – The lowest-numbered line in (the source file) that is contained in the code region.
  • ub (int) – The highest-numbered line (in the source file) that is contained in the code region.
Return type:

xr_intra_definition_iterator
Returns:

The initialized xr_intra_definition_iterator .
Raises:

OverflowError

A source file can have multiple instances ( sfileinst ) across multiple compilation units. It is therefore possible for a single source file entity to correspond to multiple definitions. For example, the compilation units might each have a different include file responsible for providing the definitions, or use the same include file but with different preprocessor settings. In this case, the iterator will include one tuple for each definition of each entity in the region.

>>> sf = next(s for s in project.current().sfiles()
...             if s.name().endswith('apitest.cpp'))
>>> for tup in sf.range_definition_iterator(16,24):  # iteration managed by xr_intra_definition_iterator.__iter__()
...                                                  # and xr_intra_definition_iterator.__next__()
...     print(tup.get_name(), tup.get_line(), tup.get_kind_role())
...
i 16 var_parameter_read
i 19 var_parameter_write
i 21 var_parameter_write
i 23 var_parameter_write
stable_cmp(other)

Comparison function for sfile , with stable results across sufficiently-similar analyses.

Parameters:other (sfile) – The sfile to compare against.
Return type:int
Returns:An integer N such that:
  • N<0 if self considered less than other
  • N==0 if self considered equal to other
  • N>0 if self considered greater than other

This function is provided so sfile objects can be stored in ordered containers that provide stable iteration order.

The comparison is stable in the following sense. Suppose there are two analyses A1 and A2 generated with exactly the same inputs (including identical analyzed code, underlying build commands and ordering, command line and configuration settings, increment order and contents). Let a1 and b1 be two sfile objects in A1, and a2 and b2 be the sfile objects objects in A2 that correspond to a1 and b1 respectively. Then a1.stable_cmp(b1)==a2.stable_cmp(b2)

If you do not need comparison results to be stable across different analyses, use sfile.__cmp__(): it has better performance.

>>> sfs = project.current().sfiles()
>>> sf1 = next(sfs)
>>> sf2 = next(sfs)
>>> sf1.stable_cmp(sf2)
1
stable_hash()

Get a hash value for a sfile , with stable results across sufficiently-similar analyses.

Return type:int
Returns:A hash derived from the source file.

This hash value is stable in the following sense. Suppose there are two analyses A1 and A2 generated with exactly the same inputs (including identical analyzed code, underlying build commands and ordering, command line and configuration settings, increment order and contents). Let b1 be a sfile object in A1, and b2 be the sfile object in A2 that corresponds to b1. Then b1.stable_hash()==b1.stable_hash().

If you do not need hash values to be stable across analyses, use sfile.__hash__(): it has better performance.

>>> sfs = project.current().sfiles()
>>> sf1 = next(sfs)
>>> sf1.stable_hash()
1757620860
token_definition_iterator(line, token[, flags =  xr_def_iter_flags.NONE])

Given a token occurrence in a source file, get an iterator over all definitions of the corresponding source entity.

Parameters:
  • line (int) – The line (int) containing the token occurrence.
  • token (str) – The token name.
  • flags (xr_def_iter_flags) – (optional) xr_def_iter_flags for setting up the iterator.
Return type:

xr_definition_iterator
Returns:

The initialized xr_definition_iterator .

 
>>> 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))
>>> defiter = sf.token_definition_iterator(iuse, 'i', xr_def_iter_flags.NONE)
>>> for tup in defiter :
...     print(tup.get_file(), tup.get_line())
...
C:\cygwin\home\alex\apitest\apitest.cpp 9

>>> 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))
>>> defiter = sf.token_definition_iterator(iuse, 'i')
>>> for tup in defiter :
...     print(tup.get_file(), tup.get_line())
...
C:\cygwin\home\alex\apitest\apitest.cpp 9
token_definition_iterator(line, token_namehash[, flags =  xr_def_iter_flags.NONE])

Given a token occurrence in a source file, get an iterator over all definitions of the corresponding source entity.

Parameters:
Return type:

xr_definition_iterator
Returns:

The initialized xr_definition_iterator .

 
>>> 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))
>>> ihash = xr_namehash('i')
>>> ihash
12973402424295696647
>>> defiter = sf.token_definition_iterator(iuse, ihash, xr_def_iter_flags.DROP_LIBMODEL_DEFS)
>>> for tup in defiter :
...     print(tup.get_file(), tup.get_line())
...
C:\cygwin\home\alex\apitest\apitest.cpp 9

>>> 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))
>>> ihash = xr_namehash('i')
>>> ihash
12973402424295696647
>>> defiter = sf.token_definition_iterator(iuse, ihash)
>>> for tup in defiter :
...     print(tup.get_file(), tup.get_line())
...
C:\cygwin\home\alex\apitest\apitest.cpp 9
token_homonym_iterator(line, token[, limit_per_kind_role = 0[, flags =  xr_occ_iter_flags.DROP_LIBMODEL_DEFS | xr_occ_iter_flags.DROP_LIBMODEL_OCCS]])

Given a token occurrence in a source file, where the token is specified by name, get an iterator over the definitions of all other entities with the same name.

Parameters:
  • line (int) – The line (int) containing the token occurrence.
  • token (str) – The token name
  • limit_per_kind_role (int) – (optional) At most this many homonyms of each xr_kind_role will have their definitions included in the iteration. Set to 0 if no limit is wanted.
  • flags (xr_occ_iter_flags) – (optional) xr_occ_iter_flags for setting up the iterator.
Return type:

xr_homonym_iterator
Returns:

The initialized xr_homonym_iterator , which will be subject to the restrictions imposed by limit_per_kind_role and flags.

 
>>> sf = next(s for s in project.current().sfiles()
...           if s.name().endswith('apitest.cpp'))
>>> sfi = sf.arbitrary_instance()
>>> iparam = next(i for i in range(1,sfi.line_count()+1) # find line containing '(int i)'
...               if '(int i)' in sfi.read_line(i))
>>> # Only one homonym occurrence per kind is included in the iteration.
>>> other_i_iter = sf.token_homonym_iterator(iparam, 'i', 1, xr_occ_iter_flags.DONTCARE_COMPLETE)
>>> for tup in other_i_iter:
...       print(tup.get_kind_role(),
...             tup.get_file().normalized_name().split('/')[-1],
...             tup.get_line())
...
var_parameter_definition apitest.cpp 9
field_definition apitest.cpp 34

>>> sf = next(s for s in project.current().sfiles()
...           if s.name().endswith('apitest.cpp'))
>>> sfi = sf.arbitrary_instance()
>>> # apitest.cpp has multiple distinct VAR_PARAMETER entities called 'i'.
>>> # There are no occurrences of any 'i' at line 1, so all entities
>>> # called 'i' are eligible homonyms.
>>> # Only one entity of each kind will have its definition included in
>>> # the iteration. In particular, only one of the VAR_PARAMETER entities
>>> # will be included.
>>> other_i_iter = sf.token_homonym_iterator(1, 'i', 1)
>>> for tup in other_i_iter:
...      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
>>> # No limit per line (equivalent to sf.token_homonym_iterator(1, 'i'))
>>> other_i_iter = sf.token_homonym_iterator(1, 'i', 0)
>>> for tup in other_i_iter:
...      print(tup.get_kind_role(),
...            tup.get_file().normalized_name().split('/')[-1],
...            tup.get_line())
...
var_parameter_definition apitest.cpp 3
var_parameter_definition apitest.cpp 9
field_definition apitest.cpp 34

>>> sf = next(s for s in project.current().sfiles()
...           if s.name().endswith('apitest.cpp'))
>>> sfi = sf.arbitrary_instance()
>>> iparam = next(i for i in range(1,sfi.line_count()+1) # find line containing '(int i)'
...               if '(int i)' in sfi.read_line(i))
>>> other_i_iter = sf.token_homonym_iterator(iparam, 'i')
>>> for tup in other_i_iter:
...     print(tup.get_kind_role(),
...           tup.get_file().normalized_name().split('/')[-1],
...           tup.get_line())
...
var_parameter_definition apitest.cpp 9
field_definition apitest.cpp 34
>>> # results don't include the use as a parameter in mymalloc(int i)
token_homonym_iterator(line, token, kind_filter[, limit_per_kind_role = 0[, flags =  xr_occ_iter_flags.DROP_LIBMODEL_DEFS | xr_occ_iter_flags.DROP_LIBMODEL_OCCS]])

Given a token occurrence (the “focal occurrence”) in a source file, where the token is specified by name and xr_kind , get an iterator over the definitions of all other entities with the same name (the “homonyms” of the focal occurrence) and the same xr_kind .

Parameters:
  • line (int) – The line (int) containing the focal occurrence. If there are no occurrences of token on that line, all entities named token will be considered homonyms for the purpose of setting up the iterator.
  • token (str) – The token name.
  • kind_filter (xr_kind) – The xr_kind of the focal occurrence and homonyms. If there is no occurrence on line with this xr_kind , all entities named token will be considered homonyms for the purpose of setting up the iterator. If there are multiple occurrences on line with this xr_kind , they will all be considered focal occurrences.
  • limit_per_kind_role (int) – (optional) At most this many homonyms of each xr_kind_role will have their definitions included in the iteration. Set to 0 if no limit is wanted.
  • flags (xr_occ_iter_flags) – (optional) xr_occ_iter_flags for setting up the iterator.
Return type:

xr_homonym_iterator
Returns:

The initialized xr_homonym_iterator , which will be subject to the restrictions imposed by kind_filter, limit_per_kind_role, and flags.
Raises:

result.ERROR_INVALID_ARGUMENT if kind_filter is xr_kind.BUILTIN (tokens of this kind have no definition).

 
>>> sf = next(s for s in project.current().sfiles()
...           if s.name().endswith('apitest.cpp'))
>>> sfi = sf.arbitrary_instance()
>>> iparam = next(i for i in range(1,sfi.line_count()+1) # find line containing '(int i)'
...               if '(int i)' in sfi.read_line(i))
>>> # No occurrence of 'i' on this line has kind FIELD, so all entities with
>>> # name 'i' are homonyms, but only one per kind of those entities is
>>> # included in the iteration.
>>> other_i_iter = sf.token_homonym_iterator(iparam, 'i', xr_kind.FIELD, 1, xr_occ_iter_flags.DONTCARE_COMPLETE)
>>> for tup in other_i_iter:
...      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

>>> sf = next(s for s in project.current().sfiles()
...            if s.name().endswith('apitest.cpp'))
>>> sfi = sf.arbitrary_instance()
>>> iparam = next(i for i in range(1,sfi.line_count()+1) # find line containing '(int i)'
...                if '(int i)' in sfi.read_line(i))
>>> # No occurrence of 'i' on this line has kind FIELD, so all entities with
>>> # name 'i' are homonyms, but only one per kind of those entities is
>>> # included in the iteration.
>>> other_i_iter = sf.token_homonym_iterator(iparam, 'i', xr_kind.FIELD, 1)
>>> for tup in other_i_iter:
...       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
>>> # No occurrence of 'i' at line 3 has kind FIELD, so all entities with
>>> # name 'i' are homonyms, and all are included in the iteration. This is
>>> # equivalent to sf.token_homonym_iterator(iparam, 'i', xr_kind.FIELD).
>>> other_i_iter = sf.token_homonym_iterator(iparam, 'i', xr_kind.FIELD, 0)
>>> for tup in other_i_iter:
...      print(tup.get_kind_role(),
...            tup.get_file().normalized_name().split('/')[-1],
...            tup.get_line())
...
var_parameter_definition apitest.cpp 3
var_parameter_definition apitest.cpp 9
field_definition apitest.cpp 34

>>> sf = next(s for s in project.current().sfiles()
...           if s.name().endswith('apitest.cpp'))
>>> sfi = sf.arbitrary_instance()
>>> iparam = next(i for i in range(1,sfi.line_count()+1) # find line containing '(int i)'
...                if '(int i)' in sfi.read_line(i))
>>> # There is one occurrence of 'i' on this line, with kind VAR_PARAMETER.
>>> # This kind matches the one specified in the token_homonym_iterator()
>>> # call, so becomes the focal occurrence (and therefore its definition
>>> # is not in the iteration).
>>> other_i_iter = sf.token_homonym_iterator(iparam, 'i', xr_kind.VAR_PARAMETER)
>>> for tup in other_i_iter:
...      print(tup.get_kind_role(),
...            tup.get_file().normalized_name().split('/')[-1],
...            tup.get_line())
...
var_parameter_definition apitest.cpp 9
field_definition apitest.cpp 34
>>> # This time the occurrence's kind does NOT match the one specified in
>>> # the token_homonym_iterator() call, so all entities with name 'i' are
>>> # homonyms and included in the iteration.
>>> other_i_iter = sf.token_homonym_iterator(iparam, 'i', xr_kind.FIELD)
>>> for tup in other_i_iter:
...      print(tup.get_kind_role(),
...            tup.get_file().normalized_name().split('/')[-1],
...            tup.get_line())
...
var_parameter_definition apitest.cpp 3
var_parameter_definition apitest.cpp 9
field_definition apitest.cpp 34
token_homonym_iterator(line, token_namehash[, limit_per_kind_role = 0[, flags =  xr_occ_iter_flags.DROP_LIBMODEL_DEFS | xr_occ_iter_flags.DROP_LIBMODEL_OCCS]])

Given a token occurrence (the “focal occurrence”) in a source file, where the token is specified by namehash, get an iterator over the definitions of all other entities with the same name (the “homonyms” of the focal occurrence).

Parameters:
  • line (int) – The line (int) containing the focal occurrence.
  • token_namehash (int) – Hash of the token name (as produced by xr_namehash()).
  • limit_per_kind_role (int) – (optional) At most this many homonyms of each xr_kind_role will have their definitions included in the iteration. Set to 0 if no limit is wanted.
  • flags (xr_occ_iter_flags) – (optional) xr_occ_iter_flags for setting up the iterator.
Return type:

xr_homonym_iterator
Returns:

The initialized xr_homonym_iterator , which will be subject to the restrictions imposed by limit_per_kind_role and flags.

 
>>> sf = next(s for s in project.current().sfiles()
...           if s.name().endswith('apitest.cpp'))
>>> sfi = sf.arbitrary_instance()
>>> iparam = next(i for i in range(1,sfi.line_count()+1) # find line containing '(int i)'
...               if '(int i)' in sfi.read_line(i))
>>> ihash = xr_namehash('i')
>>> ihash
12973402424295696647
>>> # Only one homonym occurrence per kind is included in the iteration.
>>> other_i_iter = sf.token_homonym_iterator(iparam, ihash,1, xr_occ_iter_flags.DONTCARE_COMPLETE)
>>> for tup in other_i_iter:
...      print(tup.get_kind_role(),
...            tup.get_file().normalized_name().split('/')[-1],
...            tup.get_line())
...
var_parameter_definition apitest.cpp 9
field_definition apitest.cpp 34

>>> sf = next(s for s in project.current().sfiles()
...            if s.name().endswith('apitest.cpp'))
>>> sfi = sf.arbitrary_instance()
>>> iparam = next(i for i in range(1,sfi.line_count()+1) # find line containing '(int i)'
...                if '(int i)' in sfi.read_line(i))
>>> ihash = xr_namehash('i')
>>> ihash
12973402424295696647
>>> # apitest.cpp has multiple distinct VAR_PARAMETER entities called 'i'.
>>> # There are no occurrences of any 'i' at line 1, so all entities
>>> # called 'i' are eligible homonyms.
>>> # Only one entity of each kind will have its definition included in
>>> # the iteration. In particular, only one of the VAR_PARAMETER entities
>>> # will be included.
>>> other_i_iter = sf.token_homonym_iterator(1, ihash, 1)
>>> for tup in other_i_iter:
...      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
>>> # No limit per line (equivalent to sf.token_homonym_iterator(iparam, 'i'))
>>> other_i_iter = sf.token_homonym_iterator(1, ihash, 0)
>>> for tup in other_i_iter:
...      print(tup.get_kind_role(),
...            tup.get_file().normalized_name().split('/')[-1],
...            tup.get_line())
...
var_parameter_definition apitest.cpp 3
var_parameter_definition apitest.cpp 9
field_definition apitest.cpp 34

>>> sf = next(s for s in project.current().sfiles()
...           if s.name().endswith('apitest.cpp'))
>>> sfi = sf.arbitrary_instance()
>>> iparam = next(i for i in range(1,sfi.line_count()+1) # find line containing '(int i)'
...               if '(int i)' in sfi.read_line(i))
>>> ihash = xr_namehash('i')
>>> ihash
12973402424295696647
>>> other_i_iter = sf.token_homonym_iterator(iparam, ihash)
>>> for tup in other_i_iter:
...      print(tup.get_kind_role(),
...            tup.get_file().normalized_name().split('/')[-1],
...            tup.get_line())
...
var_parameter_definition apitest.cpp 9
field_definition apitest.cpp 34
>>> # results don't include the use as a parameter in mymalloc(int i)
token_homonym_iterator(line, token_namehash, kind_filter[, limit_per_kind_role = 0[, flags =  xr_occ_iter_flags.DROP_LIBMODEL_DEFS | xr_occ_iter_flags.DROP_LIBMODEL_OCCS]])

Given a token occurrence (the “focal occurrence”) in a source file, where the token is specified by namehash and xr_kind , get an iterator over the definitions of all other entities with the same name (the “homonyms” of the focal occurrence) and the same xr_kind .

Parameters:
  • line (int) – The line (int) containing the focal occurrence.
  • token_namehash (int) – Hash of the token name (as produced by xr_namehash()).
  • kind_filter (xr_kind) – The xr_kind of the focal occurrence and homonyms. If there is no occurrence on line with this xr_kind , all entities whose names correspond to token_namehash will be considered homonyms for the purpose of setting up the iterator. If there are multiple occurrences on line with this xr_kind , they will all be considered focal occurrences.
  • limit_per_kind_role (int) – (optional) The iteration will cover at most this many occurrences.
  • flags (xr_occ_iter_flags) – (optional) xr_occ_iter_flags for setting up the iterator.
Return type:

xr_homonym_iterator
Returns:

The initialized xr_homonym_iterator , which will be subject to the restrictions imposed by kr_filter, limit_per_kind, and flags.
Raises:

result.ERROR_INVALID_ARGUMENT if kind_filter is xr_kind.BUILTIN (tokens of this kind have no definition).

 
>>> sf = next(s for s in project.current().sfiles()
...           if s.name().endswith('apitest.cpp'))
>>> sfi = sf.arbitrary_instance()
>>> iparam = next(i for i in range(1,sfi.line_count()+1) # find line containing '(int i)'
...               if '(int i)' in sfi.read_line(i))
>>> ihash = xr_namehash('i')
>>> ihash
12973402424295696647
>>> # No occurrence of 'i' on this line has kind FIELD, so all entities with
>>> # name 'i' are homonyms, but only one per kind of those entities is
>>> # included in the iteration.
>>> other_i_iter = sf.token_homonym_iterator(iparam, ihash, xr_kind.FIELD, 1, xr_occ_iter_flags.DONTCARE_COMPLETE)
>>> for tup in other_i_iter:
...      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

>>> sf = next(s for s in project.current().sfiles()
...           if s.name().endswith('apitest.cpp'))
>>> sfi = sf.arbitrary_instance()
>>> iparam = next(i for i in range(1,sfi.line_count()+1) # find line containing '(int i)'
...               if '(int i)' in sfi.read_line(i))
>>> ihash = xr_namehash('i')
>>> ihash
12973402424295696647
>>> # No occurrence of 'i' on this line has kind FIELD, so all entities with
>>> # name 'i' are homonyms, but only one per kind of those entities is
>>> # included in the iteration.
>>> other_i_iter = sf.token_homonym_iterator(iparam, ihash, xr_kind.FIELD, 1)
>>> for tup in other_i_iter:
...      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
>>> # No occurrence of 'i' at line 3 has kind FIELD, so all entities with
>>> # name 'i' are homonyms, and all are included in the iteration. This is
>>> # equivalent to sf.token_homonym_iterator(iparam, ihash, xr_kind.FIELD).
>>> other_i_iter = sf.token_homonym_iterator(iparam, ihash, xr_kind.FIELD, 0)
>>> for tup in other_i_iter:
...     print(tup.get_kind_role(),
...           tup.get_file().normalized_name().split('/')[-1],
...           tup.get_line())
...
var_parameter_definition apitest.cpp 3
var_parameter_definition apitest.cpp 9
field_definition apitest.cpp 34

>>> sf = next(s for s in project.current().sfiles()
...           if s.name().endswith('apitest.cpp'))
>>> sfi = sf.arbitrary_instance()
>>> iparam = next(i for i in range(1,sfi.line_count()+1) # find line containing '(int i)'
...               if '(int i)' in sfi.read_line(i))
>>> ihash = xr_namehash('i')
>>> ihash
12973402424295696647
>>> # There is one occurrence of 'i' on this line, with kind VAR_PARAMETER.
>>> # This kind matches the one specified in the token_homonym_iterator()
>>> # call, so becomes the focal occurrence (and therefore its definition
>>> # is not in the iteration).
>>> other_i_iter = sf.token_homonym_iterator(iparam, ihash, xr_kind.VAR_PARAMETER)
>>> for tup in other_i_iter:
...       print(tup.get_kind_role(),
...             tup.get_file().normalized_name().split('/')[-1],
...             tup.get_line())
...
var_parameter_definition apitest.cpp 9
field_definition apitest.cpp 34
>>> # This time the occurrence's kind does NOT match the one specified in
>>> # the token_homonym_iterator() call, so all entities with name 'i' are
>>> # homonyms and included in the iteration.
>>> other_i_iter = sf.token_homonym_iterator(iparam, ihash, xr_kind.FIELD)
>>> for tup in other_i_iter:
...      print(tup.get_kind_role(),
...            tup.get_file().normalized_name().split('/')[-1],
...            tup.get_line())
...
var_parameter_definition apitest.cpp 3
var_parameter_definition apitest.cpp 9
field_definition apitest.cpp 34
token_occurrence_iterator(line, token[, limit_per_kind_role = 0[, flags =  xr_occ_iter_flags.DROP_LIBMODEL_DEFS | xr_occ_iter_flags.DROP_LIBMODEL_OCCS]])

Given a token occurrence in a source file, where the token is specified by name, get an iterator over all occurrences of the corresponding source entity in all kind/roles.

Parameters:
  • line (int) – The line (int) containing the token occurrence.
  • token (str) – The token name
  • limit_per_kind_role (int) – (optional) The iteration will cover at most this many occurrences for each kind/role. Set to 0 if no limit is wanted.
  • flags (xr_occ_iter_flags) – (optional) xr_occ_iter_flags for setting up the iterator.
Return type:

xr_occurrence_iterator
Returns:

The initialized xr_occurrence_iterator , which will be subject to the restrictions imposed by kr_filter, limit_per_kind_role, and flags.

 
>>> sf = next(s for s in project.current().sfiles()
...           if s.name().endswith('apitest.cpp'))
>>> sfi = sf.arbitrary_instance()
>>> mmdef = next(i for i in range(1,sfi.line_count()+1)
...               if 'mymalloc(int i)' in sfi.read_line(i))
>>> occ_iter = sf.token_occurrence_iterator(mmdef, 'mymalloc', 1, xr_occ_iter_flags.NONE)
>>> for tup in occ_iter:
...     print(tup.get_kind_role(), tup.get_file(), tup.get_line())
...
func_definition C:\alex\test\apitest.cpp 3
func_call C:\alex\test\apitest.cpp 15

>>> sf = next(s for s in project.current().sfiles()
...           if s.name().endswith('apitest.cpp'))
>>> sfi = sf.arbitrary_instance()
>>> mmdef = next(i for i in range(1,sfi.line_count()+1)
...               if 'mymalloc(int i)' in sfi.read_line(i))
>>> occ_iter = sf.token_occurrence_iterator(mmdef, 'mymalloc', 1)
>>> for tup in occ_iter:
...     print(tup.get_kind_role(), tup.get_file(), tup.get_line())
...
func_definition C:\alex\test\apitest.cpp 3
func_call C:\alex\test\apitest.cpp 15

>>> sf = next(s for s in project.current().sfiles()
...           if s.name().endswith('apitest.cpp'))
>>> sfi = sf.arbitrary_instance()
>>> mmdef = next(i for i in range(1,sfi.line_count()+1)
...              if 'mymalloc(int i)' in sfi.read_line(i))
>>> occ_iter = sf.token_occurrence_iterator(mmdef, 'mymalloc')
>>> for tup in occ_iter:
...     print(tup.get_kind_role(), tup.get_file(), tup.get_line())
...
func_definition C:\alex\test\apitest.cpp 3
func_call C:\alex\test\apitest.cpp 15
func_call C:\alex\test\apitest.cpp 37
token_occurrence_iterator(line, token, kr_filter[, limit_per_kind_role = 0[, flags =  xr_occ_iter_flags.DROP_LIBMODEL_DEFS | xr_occ_iter_flags.DROP_LIBMODEL_OCCS]])

Given a token occurrence in a source file, where the token is specified by name, get an iterator over all occurrences of the corresponding source entity in a specific kind/role.

Parameters:
  • line (int) – The line (int) containing the token occurrence.
  • token (str) – The token name.
  • kr_filter (xr_kind_role) – The iteration will be restricted to occurrences in this kind/role. Use one of the forms without a kr_filter parameter to cover all kind/roles.
  • limit_per_kind_role (int) – (optional) The iteration will cover at most this many occurrences.
  • flags (xr_occ_iter_flags) – (optional) xr_occ_iter_flags for setting up the iterator.
Return type:

xr_occurrence_iterator
Returns:

The initialized xr_occurrence_iterator , which will be subject to the restrictions imposed by kr_filter, limit_per_kind_role, and flags.

 
>>> sf = next(s for s in project.current().sfiles()
...           if s.name().endswith('apitest.cpp'))
>>> sfi = sf.arbitrary_instance()
>>> mmdef = next(i for i in range(1,sfi.line_count()+1)
...              if 'mymalloc(int i)' in sfi.read_line(i))
>>> occ_iter = sf.token_occurrence_iterator(mmdef, 'mymalloc', xr_kind_role.FUNC_CALL, 1, xr_occ_iter_flags.NONE)
>>> for tup in occ_iter:
...     print(tup.get_kind_role(), tup.get_file(), tup.get_line())
...
func_call C:\alex\test\apitest.cpp 15

>>> sf = next(s for s in project.current().sfiles()
...           if s.name().endswith('apitest.cpp'))
>>> sfi = sf.arbitrary_instance()
>>> mmdef = next(i for i in range(1,sfi.line_count()+1)
...               if 'mymalloc(int i)' in sfi.read_line(i))
>>> occ_iter = sf.token_occurrence_iterator(mmdef, 'mymalloc', xr_kind_role.FUNC_CALL, 1)
>>> for tup in occ_iter:
...     print(tup.get_kind_role(), tup.get_file(), tup.get_line())
...
func_call C:\alex\test\apitest.cpp 15

>>> sf = next(s for s in project.current().sfiles()
...           if s.name().endswith('apitest.cpp'))
>>> sfi = sf.arbitrary_instance()
>>> mmdef = next(i for i in range(1,sfi.line_count()+1)
...              if 'mymalloc(int i)' in sfi.read_line(i))
>>> occ_iter = sf.token_occurrence_iterator(mmdef, 'mymalloc', xr_kind_role.FUNC_CALL)
>>> for tup in occ_iter:
...     print(tup.get_kind_role(), tup.get_file(), tup.get_line())
...
func_call C:\alex\test\apitest.cpp 15
func_call C:\alex\test\apitest.cpp 37
token_occurrence_iterator(line, token_namehash[, limit_per_kind_role = 0[, flags =  xr_occ_iter_flags.DROP_LIBMODEL_DEFS | xr_occ_iter_flags.DROP_LIBMODEL_OCCS]])

Given a token occurrence in a source file, where the token is specified by namehash, get an iterator over all occurrences of the corresponding source entity in all kind/roles.

Parameters:
  • line (int) – The line (int) containing the token occurrence.
  • token_namehash (int) – Hash of the token name (as produced by xr_namehash()).
  • limit_per_kind_role (int) – (optional) The iteration will cover at most this many occurrences for each kind/role. Set to 0 if no limit is wanted.
  • flags (xr_occ_iter_flags) – (optional) xr_occ_iter_flags for setting up the iterator.
Return type:

xr_occurrence_iterator
Returns:

The initialized xr_occurrence_iterator , which will be subject to the restrictions imposed by kr_filter, limit_per_kind_role, and flags.

 
>>> sf = next(s for s in project.current().sfiles()
...           if s.name().endswith('apitest.cpp'))
>>> sfi = sf.arbitrary_instance()
>>> mmdef = next(i for i in range(1,sfi.line_count()+1)
...               if 'mymalloc(int i)' in sfi.read_line(i))
>>> mmhash = xr_namehash('mymalloc')
>>> mmhash
3855052149039316776
>>> occ_iter = sf.token_occurrence_iterator(mmdef, mmhash, 1, xr_occ_iter_flags.NONE)
>>> for tup in occ_iter:
...     print(tup.get_kind_role(), tup.get_file(), tup.get_line())
...
func_definition C:\alex\test\apitest.cpp 3
func_call C:\alex\test\apitest.cpp 15

>>> sf = next(s for s in project.current().sfiles()
...           if s.name().endswith('apitest.cpp'))
>>> sfi = sf.arbitrary_instance()
>>> mmdef = next(i for i in range(1,sfi.line_count()+1)
...               if 'mymalloc(int i)' in sfi.read_line(i))
>>> mmhash = xr_namehash('mymalloc')
>>> mmhash
3855052149039316776
>>> occ_iter = sf.token_occurrence_iterator(mmdef, mmhash, 1)
>>> for tup in occ_iter:
...     print(tup.get_kind_role(), tup.get_file(), tup.get_line())
...
func_definition C:\alex\test\apitest.cpp 3
func_call C:\alex\test\apitest.cpp 15

>>> sf = next(s for s in project.current().sfiles()
...           if s.name().endswith('apitest.cpp'))
>>> sfi = sf.arbitrary_instance()
>>> mmdef = next(i for i in range(1,sfi.line_count()+1)
...               if 'mymalloc(int i)' in sfi.read_line(i))
>>> mmhash = xr_namehash('mymalloc')
>>> mmhash
3855052149039316776
>>> occ_iter = sf.token_occurrence_iterator(mmdef, mmhash)
>>> for tup in occ_iter:
...     print(tup.get_kind_role(), tup.get_file(), tup.get_line())
...
func_definition C:\alex\test\apitest.cpp 3
func_call C:\alex\test\apitest.cpp 15
func_call C:\alex\test\apitest.cpp 37
token_occurrence_iterator(line, token_namehash, kr_filter[, limit_per_kind_role = 0[, flags =  xr_occ_iter_flags.DROP_LIBMODEL_DEFS | xr_occ_iter_flags.DROP_LIBMODEL_OCCS]])

Given a token occurrence in a source file, where the token is specified by namehash, get an iterator over all occurrences of the corresponding source entity in a specific kind/role.

Parameters:
  • line (int) – The line (int) containing the token occurrence.
  • token_namehash (int) – Hash of the token name (as produced by xr_namehash()).
  • kr_filter (xr_kind_role) – The iteration will be restricted to occurrences in this kind/role. Use one of the forms without a kr_filter parameter to cover all kind/roles.
  • limit_per_kind_role (int) – (optional) The iteration will cover at most this many occurrences.
  • flags (xr_occ_iter_flags) – (optional) xr_occ_iter_flags for setting up the iterator.
Return type:

xr_occurrence_iterator
Returns:

The initialized xr_occurrence_iterator , which will be subject to the restrictions imposed by kr_filter, limit_per_kind_role, and flags.

 
>>> sf = next(s for s in project.current().sfiles()
...           if s.name().endswith('apitest.cpp'))
>>> sfi = sf.arbitrary_instance()
>>> mmdef = next(i for i in range(1,sfi.line_count()+1)
...               if 'mymalloc(int i)' in sfi.read_line(i))
>>> mmhash = xr_namehash('mymalloc')
>>> mmhash
3855052149039316776
>>> occ_iter = sf.token_occurrence_iterator(mmdef, mmhash, xr_kind_role.FUNC_CALL, 1, xr_occ_iter_flags.NONE)
>>> for tup in occ_iter:
...     print(tup.get_kind_role(), tup.get_file(), tup.get_line())
...
func_call C:\alex\test\apitest.cpp 15

>>> sf = next(s for s in project.current().sfiles()
...           if s.name().endswith('apitest.cpp'))
>>> sfi = sf.arbitrary_instance()
>>> mmdef = next(i for i in range(1,sfi.line_count()+1)
...               if 'mymalloc(int i)' in sfi.read_line(i))
>>> mmhash = xr_namehash('mymalloc')
>>> mmhash
3855052149039316776
>>> occ_iter = sf.token_occurrence_iterator(mmdef, mmhash, xr_kind_role.FUNC_CALL, 1)
>>> for tup in occ_iter:
...     print(tup.get_kind_role(), tup.get_file(), tup.get_line())
...
func_call C:\alex\test\apitest.cpp 15

>>> sf = next(s for s in project.current().sfiles()
...           if s.name().endswith('apitest.cpp'))
>>> sfi = sf.arbitrary_instance()
>>> mmdef = next(i for i in range(1,sfi.line_count()+1)
...               if 'mymalloc(int i)' in sfi.read_line(i))
>>> mmhash = xr_namehash('mymalloc')
>>> mmhash
3855052149039316776
>>> occ_iter = sf.token_occurrence_iterator(mmdef, mmhash, xr_kind_role.FUNC_CALL)
>>> for tup in occ_iter:
...     print(tup.get_kind_role(), tup.get_file(), tup.get_line())
...
func_call C:\alex\test\apitest.cpp 15
func_call C:\alex\test\apitest.cpp 37