cs::sfile Class Reference

A source file. More...

Public Member Functions
sfileinst	arbitrary_instance () const
	Get an (arbitrary) instance of a source file. More...
std::string	as_repr () const
	Get a representation of a sfile object that includes information useful for debugging. More...
std::string	as_string () const
	Get a simple string representation of a sfile object. More...
int	cmp (const sfile &other) const
	Comparison function for sfile. More...
std::string	handle () const
	Get a handle for this sfile. More...
cs_hash_t	hash () const
	Get a hash value for a sfile. More...
csuint64	hash64 () const
	64-bit hash function for sfile. More...
sfile_instance_iterator	instances () const
	Get an iterator over the instances (sfileinst) of a source file. More...
std::string	name () const
	Get the unnormalized absolute path name for a source file. More...
std::string	normalized_name () const
	Get the normalized absolute path name for a source file. More...
directory	parent () const
	Get the parent directory for a source file. More...
std::vector< procedure >	procedures_on_line (line_number ln, bool exact=false) const
	Get the procedures whose definition appears on the specified line in a source file. More...
std::vector< procedure >	procedures_on_line_fast (line_number ln, bool closest) const
	Get all procedures defined on the specified line of a source file. More...
std::vector< procedure >	procedures_on_line_fast (line_number ln, cs_hash_t friendly_name_hash, bool closest) const
	Get all procedures with the specified name defined on the specified line of a source file. More...
xr_intra_definition_iterator	range_definition_iterator (line_number lb, line_number ub) const
	Given a code region in a source file, get an iterator over the definitions of all source entities with occurrences in that region. More...
int	stable_cmp (const sfile &other) const
	Comparison function for sfile, with stable results across sufficiently-similar analyses. More...
csuint64	stable_hash () const
	Get a hash value for a sfile, with stable results across sufficiently-similar analyses. More...
xr_definition_iterator	token_definition_iterator (line_number line, csuint64 token_namehash, xr_def_iter_flags flags=xr_def_iter_flags::NONE) const
	Given a token occurrence in a source file, get an iterator over all definitions of the corresponding source entity. More...
xr_definition_iterator	token_definition_iterator (line_number line, const std::string &token, xr_def_iter_flags flags=xr_def_iter_flags::NONE) const
	Given a token occurrence in a source file, get an iterator over all definitions of the corresponding source entity. More...
xr_homonym_iterator	token_homonym_iterator (line_number line, csuint64 token_namehash, xr_kind kind_filter, size_t limit_per_kind_role=0, xr_occ_iter_flags flags=xr_occ_iter_flags::DROP_LIBMODEL_DEFS|xr_occ_iter_flags::DROP_LIBMODEL_OCCS) const
	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. More...
xr_homonym_iterator	token_homonym_iterator (line_number line, const std::string &token, xr_kind kind_filter, size_t limit_per_kind_role=0, xr_occ_iter_flags flags=xr_occ_iter_flags::DROP_LIBMODEL_DEFS|xr_occ_iter_flags::DROP_LIBMODEL_OCCS) const
	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. More...
xr_homonym_iterator	token_homonym_iterator (line_number line, csuint64 token_namehash, size_t limit_per_kind_role=0, xr_occ_iter_flags flags=xr_occ_iter_flags::DROP_LIBMODEL_DEFS|xr_occ_iter_flags::DROP_LIBMODEL_OCCS) const
	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). More...
xr_homonym_iterator	token_homonym_iterator (line_number line, const std::string &token, size_t limit_per_kind_role=0, xr_occ_iter_flags flags=xr_occ_iter_flags::DROP_LIBMODEL_DEFS|xr_occ_iter_flags::DROP_LIBMODEL_OCCS) const
	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. More...
xr_occurrence_iterator	token_occurrence_iterator (line_number line, csuint64 token_namehash, xr_kind_role kr_filter, size_t limit_per_kind_role=0, xr_occ_iter_flags flags=xr_occ_iter_flags::DROP_LIBMODEL_DEFS|xr_occ_iter_flags::DROP_LIBMODEL_OCCS) const
	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. More...
xr_occurrence_iterator	token_occurrence_iterator (line_number line, const std::string &token, xr_kind_role kr_filter, size_t limit_per_kind_role=0, xr_occ_iter_flags flags=xr_occ_iter_flags::DROP_LIBMODEL_DEFS|xr_occ_iter_flags::DROP_LIBMODEL_OCCS) const
	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. More...
xr_occurrence_iterator	token_occurrence_iterator (line_number line, csuint64 token_namehash, size_t limit_per_kind_role=0, xr_occ_iter_flags flags=xr_occ_iter_flags::DROP_LIBMODEL_DEFS|xr_occ_iter_flags::DROP_LIBMODEL_OCCS) const
	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. More...
xr_occurrence_iterator	token_occurrence_iterator (line_number line, const std::string &token, size_t limit_per_kind_role=0, xr_occ_iter_flags flags=xr_occ_iter_flags::DROP_LIBMODEL_DEFS|xr_occ_iter_flags::DROP_LIBMODEL_OCCS) const
	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. More...

Related Functions
(Note that these are not member functions.)
bool	operator!= (const sfile &a, const sfile &b)
	Inequality operator for sfile. More...
bool	operator< (const sfile &a, const sfile &b)
	Less-than operator for sfile. More...
std::ostream &	operator<< (std::ostream &out, const sfile &a)
	Print a representation of a sfile object to the specified stream. More...
bool	operator<= (const sfile &a, const sfile &b)
	Less-than-or-equal operator for sfile. More...
bool	operator== (const sfile &a, const sfile &b)
	Equality operator for sfile. More...
bool	operator> (const sfile &a, const sfile &b)
	Greater-than operator for sfile. More...
bool	operator>= (const sfile &a, const sfile &b)
	Greater-than-or-equal operator for sfile. More...
csuint64	xr_namehash (const std::string &s)
	Hash a token name. More...

Detailed Description

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.

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.

Member Function Documentation

arbitrary_instance()

sfileinst cs::sfile::arbitrary_instance ( ) const

inline

Get an (arbitrary) instance of a source file.

Returns

An instance (sfileinst) of the source file.

Exceptions

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 instances().

as_repr()

std::string cs::sfile::as_repr ( ) const

inline

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

Returns

The string representation.

as_string()

std::string cs::sfile::as_string ( ) const

inline

Get a simple string representation of a sfile object.

Returns

The string representation.

cmp()

cs::sfile::cmp ( const sfile &  other ) const

inline

Comparison function for sfile.

Parameters

other

The sfile object to compare against.

Returns

An integer N such that:

• N==0 if the two objects compare equal
• N<0 if this < other
• N>0 if this > other

this and other will only compare equal if they are the same sfile object.

handle()

std::string cs::sfile::handle ( ) const

inline

Get a handle for this sfile.

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 std::string consisting of letters (upper and lower case) and numbers, and could also include the following characters: "+", "=", and "_".

hash()

cs_hash_t cs::sfile::hash ( ) const

inline

Get a hash value for a sfile.

hash64()

csuint64 cs::sfile::hash64 ( ) const

inline

64-bit hash function for sfile.

Returns

A 64-bit hash value derived from the source file path and contents.

instances()

sfile_instance_iterator cs::sfile::instances ( ) const

inline

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

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 arbitrary_instance().

name()

std::string cs::sfile::name ( ) const

inline

Get the unnormalized absolute path name for a source file.

Returns

The unnormalized absolute path name.

Exceptions

result::ELEMENT_NOT_PRESENT	if the project contains no instances of the source file.
result::ERROR_CANNOT_FIND_PATH	if there is no absolute path name associated with the source file.

Use normalized_name() to get the normalized file path.

normalized_name()

std::string cs::sfile::normalized_name ( ) const

inline

Get the normalized absolute path name for a source file.

Returns

The normalized absolute path name.

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

Exceptions

result::ELEMENT_NOT_PRESENT	if the project contains no instances of the source file.
result::ERROR_CANNOT_FIND_PATH	if there is no absolute path name associated with the source file.

Use name() to get the unnormalized file path.

parent()

directory cs::sfile::parent ( ) const

inline

Get the parent directory for a source file.

Returns

The parent directory.

procedures_on_line()

std::vector<procedure> cs::sfile::procedures_on_line ( line_number  ln, bool  exact = false  ) const

inline

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

Parameters

[in]	ln	The line number in the source file.
[in]	exact	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.

Returns

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

procedures_on_line_fast() [1/2]

std::vector< procedure > cs::sfile::procedures_on_line_fast ( line_number  ln, bool  closest  ) const

inline

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

Parameters

[in]	ln	The source file line number on which the procedure definition starts.
[in]	closest	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 std::vector is empty. false : the result std::vector is empty. If there is at least one procedure definition on line ln, this parameter has no effect.

Returns

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

To restrict to procedures with a specific name, use sfile::procedures_on_line_fast(line_number,cs_hash_t,bool)

Exceptions

result::ERROR_INVALID_PHASE_FOR_OPERATION

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

procedures_on_line_fast() [2/2]

std::vector< procedure > cs::sfile::procedures_on_line_fast ( line_number  ln, cs_hash_t  friendly_name_hash, bool  closest  ) const

inline

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

Parameters

[in]	ln	The source file line number on which the procedure definition starts.
[in]	friendly_name_hash	The hash (cs::string_hash()) of the procedure friendly name (procedure::name()).
[in]	closest	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 std::vector is empty. false : the result std::vector is empty. If there is at least one procedure definition matching friendly_name_hash on line ln, this parameter has no effect.

Returns

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

To get all procedures on a line regardless of name, use sfile::procedures_on_line_fast(line_number,bool)

Exceptions

result::ERROR_INVALID_ARGUMENT	if configuration parameter COLLAPSE_PROCEDURES is set to No (because in this case there are no stored procedure name hashes for lookup).
result::ERROR_INVALID_PHASE_FOR_OPERATION	if called before the end of the depth-first analysis phase.

range_definition_iterator()

xr_intra_definition_iterator cs::sfile::range_definition_iterator ( line_number  lb, line_number  ub  ) const

inline

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

Parameters

[in]	lb	The lowest-numbered line in (the source file) that is contained in the code region.
[in]	ub	The highest-numbered line (in the source file) that is contained in the code region.

Returns

The initialized xr_intra_definition_iterator.

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.

stable_cmp()

int cs::sfile::stable_cmp ( const sfile &  other ) const

inline

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

Parameters

[in]

other

The sfile to compare against.

Returns

An integer N such that:

• N<0 if this considered less than other
• N==0 if this considered equal to other
• N>0 if this 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 cmp(): it has better performance.

stable_hash()

csuint64 cs::sfile::stable_hash ( ) const

inline

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

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 hash(): it has better performance.

token_definition_iterator() [1/2]

xr_definition_iterator cs::sfile::token_definition_iterator ( line_number  line, csuint64  token_namehash, xr_def_iter_flags  flags = xr_def_iter_flags::NONE  ) const

inline

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

Parameters

[in]	line	The line (line_number) containing the token occurrence.
[in]	token_namehash	Hash of the token name (as produced by xr_namehash()).
[in]	flags	xr_def_iter_flags for setting up the iterator.

Returns

The initialized xr_definition_iterator.

See also

token_definition_iterator(line_number, const std::string &, xr_def_iter_flags) const

token_definition_iterator() [2/2]

xr_definition_iterator cs::sfile::token_definition_iterator ( line_number  line, const std::string &  token, xr_def_iter_flags  flags = xr_def_iter_flags::NONE  ) const

inline

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

Parameters

[in]	line	The line (line_number) containing the token occurrence.
[in]	token	The token name.
[in]	flags	xr_def_iter_flags for setting up the iterator.

Returns

The initialized xr_definition_iterator.

See also

token_definition_iterator(line_number, csuint64, xr_def_iter_flags) const

token_homonym_iterator() [1/4]

xr_homonym_iterator cs::sfile::token_homonym_iterator ( line_number  line, csuint64  token_namehash, xr_kind  kind_filter, size_t  limit_per_kind_role = 0, xr_occ_iter_flags  flags = xr_occ_iter_flags::DROP_LIBMODEL_DEFS | xr_occ_iter_flags::DROP_LIBMODEL_OCCS  ) const

inline

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

[in]	line	The line (line_number) containing the focal occurrence.
[in]	token_namehash	Hash of the token name (as produced by xr_namehash()).
[in]	kind_filter	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.
[in]	limit_per_kind_role	The iteration will cover at most this many occurrences.
[in]	flags	xr_occ_iter_flags for setting up the iterator.

Returns

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

See also

• token_homonym_iterator(line_number line,const std::string &,xr_kind_role,size_t,xr_occ_iter_flags flags) const : single kind; focal occurrence specified by line, kind, and name
• token_homonym_iterator(line_number,const std::string &,size_t,xr_occ_iter_flags flags) const : all kinds; focal occurrence specified by line and name
• token_homonym_iterator(line_number,csuint64,size_t,xr_occ_iter_flags flags) const : all kinds; focal occurrence specified by line and namehash

Exceptions

result::ERROR_INVALID_ARGUMENT

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

token_homonym_iterator() [2/4]

xr_homonym_iterator cs::sfile::token_homonym_iterator ( line_number  line, const std::string &  token, xr_kind  kind_filter, size_t  limit_per_kind_role = 0, xr_occ_iter_flags  flags = xr_occ_iter_flags::DROP_LIBMODEL_DEFS | xr_occ_iter_flags::DROP_LIBMODEL_OCCS  ) const

inline

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

[in]	line	The line (line_number) 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.
[in]	token	The token name.
[in]	kind_filter	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.
[in]	limit_per_kind_role	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.
[in]	flags	xr_occ_iter_flags for setting up the iterator.

Returns

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

See also

• token_homonym_iterator(line_number line,csuint64,xr_kind,size_t,xr_occ_iter_flags flags) const : single kind; focal occurrence specified by line, kind, and namehash
• token_homonym_iterator(line_number,const std::string &,size_t,xr_occ_iter_flags flags) const : all kinds; focal occurrence specified by line and name
• token_homonym_iterator(line_number,csuint64,size_t,xr_occ_iter_flags flags) const : all kinds; focal occurrence specified by line and namehash

Exceptions

result::ERROR_INVALID_ARGUMENT

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

token_homonym_iterator() [3/4]

xr_homonym_iterator cs::sfile::token_homonym_iterator ( line_number  line, csuint64  token_namehash, size_t  limit_per_kind_role = 0, xr_occ_iter_flags  flags = xr_occ_iter_flags::DROP_LIBMODEL_DEFS | xr_occ_iter_flags::DROP_LIBMODEL_OCCS  ) const

inline

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

[in]	line	The line (line_number) containing the focal occurrence.
[in]	token_namehash	Hash of the token name (as produced by xr_namehash()).
[in]	limit_per_kind_role	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.
[in]	flags	xr_occ_iter_flags for setting up the iterator.

Returns

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

See also

• token_homonym_iterator(line_number line,const std::string &,xr_kind,size_t,xr_occ_iter_flags flags) const : single kind; focal occurrence specified by line, kind, and name
• token_homonym_iterator(line_number line,csuint64,xr_kind_role,size_t,xr_occ_iter_flags flags) const : single kind, focal occurrence specified by line and namehash
• token_homonym_iterator(line_number,const std::string &,size_t,xr_occ_iter_flags flags) const : all kinds; focal occurrence specified by line and name

token_homonym_iterator() [4/4]

xr_homonym_iterator cs::sfile::token_homonym_iterator ( line_number  line, const std::string &  token, size_t  limit_per_kind_role = 0, xr_occ_iter_flags  flags = xr_occ_iter_flags::DROP_LIBMODEL_DEFS | xr_occ_iter_flags::DROP_LIBMODEL_OCCS  ) const

inline

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

[in]	line	The line (line_number) containing the token occurrence.
[in]	token	The token name
[in]	limit_per_kind_role	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.
[in]	flags	xr_occ_iter_flags for setting up the iterator.

Returns

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

See also

• token_homonym_iterator(line_number line,const std::string &,xr_kind_role,size_t,xr_occ_iter_flags flags) const : single kind; focal occurrence specified by line and name
• token_homonym_iterator(line_number line,csuint64,xr_kind_role,size_t,xr_occ_iter_flags flags) const : single kind; focal occurrence specified by line and namehash
• token_homonym_iterator(line_number,csuint64,size_t,xr_occ_iter_flags flags) const : all kinds; focal occurrence specified by line and namehash

token_occurrence_iterator() [1/4]

xr_occurrence_iterator cs::sfile::token_occurrence_iterator ( line_number  line, csuint64  token_namehash, xr_kind_role  kr_filter, size_t  limit_per_kind_role = 0, xr_occ_iter_flags  flags = xr_occ_iter_flags::DROP_LIBMODEL_DEFS | xr_occ_iter_flags::DROP_LIBMODEL_OCCS  ) const

inline

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

[in]	line	The line (line_number) containing the token occurrence.
[in]	token_namehash	Hash of the token name (as produced by xr_namehash()).
[in]	kr_filter	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.
[in]	limit_per_kind_role	The iteration will cover at most this many occurrences.
[in]	flags	xr_occ_iter_flags for setting up the iterator.

Returns

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

See also

• token_occurrence_iterator(line_number line,const std::string &,xr_kind_role,size_t,xr_occ_iter_flags flags) const : single kind/role, specify token by name
• token_occurrence_iterator(line_number,const std::string &,size_t,xr_occ_iter_flags flags) const : all kind/roles, specify token by name
• token_occurrence_iterator(line_number,csuint64,size_t,xr_occ_iter_flags flags) const : all kind/roles, specify token by namehash

token_occurrence_iterator() [2/4]

xr_occurrence_iterator cs::sfile::token_occurrence_iterator ( line_number  line, const std::string &  token, xr_kind_role  kr_filter, size_t  limit_per_kind_role = 0, xr_occ_iter_flags  flags = xr_occ_iter_flags::DROP_LIBMODEL_DEFS | xr_occ_iter_flags::DROP_LIBMODEL_OCCS  ) const

inline

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

[in]	line	The line (line_number) containing the token occurrence.
[in]	token	The token name.
[in]	kr_filter	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.
[in]	limit_per_kind_role	The iteration will cover at most this many occurrences.
[in]	flags	xr_occ_iter_flags for setting up the iterator.

Returns

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

See also

• token_occurrence_iterator(line_number line,csuint64,xr_kind_role,size_t,xr_occ_iter_flags flags) const : single kind/role, specify token by namehash
• token_occurrence_iterator(line_number,const std::string &,size_t,xr_occ_iter_flags flags) const : all kind/roles, specify token by name
• token_occurrence_iterator(line_number,csuint64,size_t,xr_occ_iter_flags flags) const : all kind/roles, specify token by namehash

token_occurrence_iterator() [3/4]

xr_occurrence_iterator cs::sfile::token_occurrence_iterator ( line_number  line, csuint64  token_namehash, size_t  limit_per_kind_role = 0, xr_occ_iter_flags  flags = xr_occ_iter_flags::DROP_LIBMODEL_DEFS | xr_occ_iter_flags::DROP_LIBMODEL_OCCS  ) const

inline

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

[in]	line	The line (line_number) containing the token occurrence.
[in]	token_namehash	Hash of the token name (as produced by xr_namehash()).
[in]	limit_per_kind_role	The iteration will cover at most this many occurrences for each kind/role. Set to 0 if no limit is wanted.
[in]	flags	xr_occ_iter_flags for setting up the iterator.

Returns

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

See also

• token_occurrence_iterator(line_number line,const std::string &,xr_kind_role,size_t,xr_occ_iter_flags flags) const : single kind/role, specify token by name
• token_occurrence_iterator(line_number line,csuint64,xr_kind_role,size_t,xr_occ_iter_flags flags) const : single kind/role, specify token by namehash
• token_occurrence_iterator(line_number,const std::string &,size_t,xr_occ_iter_flags flags) const : all kind/roles, specify token by name

token_occurrence_iterator() [4/4]

xr_occurrence_iterator cs::sfile::token_occurrence_iterator ( line_number  line, const std::string &  token, size_t  limit_per_kind_role = 0, xr_occ_iter_flags  flags = xr_occ_iter_flags::DROP_LIBMODEL_DEFS | xr_occ_iter_flags::DROP_LIBMODEL_OCCS  ) const

inline

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

[in]	line	The line (line_number) containing the token occurrence.
[in]	token	The token name
[in]	limit_per_kind_role	The iteration will cover at most this many occurrences for each kind/role. Set to 0 if no limit is wanted.
[in]	flags	xr_occ_iter_flags for setting up the iterator.

Returns

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

See also

• token_occurrence_iterator(line_number line,const std::string &,xr_kind_role,size_t,xr_occ_iter_flags flags) const : single kind/role, specify token by name
• token_occurrence_iterator(line_number line,csuint64,xr_kind_role,size_t,xr_occ_iter_flags flags) const : single kind/role, specify token by namehash
• token_occurrence_iterator(line_number,csuint64,size_t,xr_occ_iter_flags flags) const : all kind/roles, specify token by namehash

Friends And Related Function Documentation

operator!=()

bool operator!= ( const sfile &  a, const sfile &  b  )

related

Inequality operator for sfile.

Parameters

[in]	a	The sfile to compare.
[in]	b	The sfile to compare against.

Returns

false if a and b are equal according to sfile::cmp(), true otherwise.

operator<()

bool operator< ( const sfile &  a, const sfile &  b  )

related

Less-than operator for sfile.

Parameters

[in]	a	The sfile to compare.
[in]	b	The sfile to compare against.

Returns

true if a < b according to sfile::cmp() , false otherwise.

operator<<()

std::ostream & operator<< ( std::ostream &  out, const sfile &  a  )

related

Print a representation of a sfile object to the specified stream.

Parameters

[in]	out	The stream to print to.
[in]	a	The sfile object to print.

Returns

void

operator<=()

bool operator<= ( const sfile &  a, const sfile &  b  )

related

Less-than-or-equal operator for sfile.

Parameters

[in]	a	The sfile to compare.
[in]	b	The sfile to compare against.

Returns

true if a <= b according to sfile::cmp() , false otherwise.

operator==()

bool operator== ( const sfile &  a, const sfile &  b  )

related

Equality operator for sfile.

Parameters

[in]	a	The sfile to compare.
[in]	b	The sfile to compare against.

Returns

true if a and b are equal according to sfile::cmp(), false otherwise.

operator>()

bool operator> ( const sfile &  a, const sfile &  b  )

related

Greater-than operator for sfile.

Parameters

[in]	a	The sfile to compare.
[in]	b	The sfile to compare against.

Returns

true if a > b according to sfile::cmp() , false otherwise.

operator>=()

bool operator>= ( const sfile &  a, const sfile &  b  )

related

Greater-than-or-equal operator for sfile.

Parameters

[in]	a	The sfile to compare.
[in]	b	The sfile to compare against.

Returns

true if a >= b according to sfile::cmp() , false otherwise.

xr_namehash()

csuint64 xr_namehash ( const std::string &  s )

related

Hash a token name.

Parameters

[in]

s

The token name.

Returns

A hash of s, as a csuint64

---

The documentation for this class was generated from the following files:

• cs_sfile_decl.hpp
• cs_sfile.hpp
• cs_xr_kind_role.hpp
• csonar_visitor.hpp