A source file instance. More...

Public Member Functions
std::string	as_repr () const
	Get a representation of a sfileinst object that includes information useful for debugging. More...

std::string	as_string () const
	Get the unnormalized absolute path name for a source file instance. More...

std::vector< ast >	asts_at (line_number line) const
	Get the ASTs at the specified location in a source file instance. More...

std::vector< ast >	asts_at (line_number line, const std::vector< ast_class > &classes) const
	Get the ASTs at the specified location in a source file instance. More...

sfileinst	child_at (line_number ln) const
	Get the source file instance included at the specified line. More...

sfileinst_children_iterator	children () const
	Get an iterator over the include-tree children of a source file instance. More...

std::vector< sfileinst >	children_vector () const
	Get the include-tree children of a source file instance. More...

int	cmp (const sfileinst &other) const
	Comparison function for sfileinst. More...

sfileinst_color_map_iterator	color_map_iterator (syntax_kind k, line_number lowerbound=0) const
	Get an iterator over the spans of the specified syntax_kind at or after the specified line in a source file instance, in order of appearance. More...

line_counts	count_lines (line_number start=1, line_number end=UINT32_MAX) const
	For a set of adjacent lines in a source file instance, retrieve statistics about the classifications of the lines in the set. More...

compunit	get_compunit () const
	Get the compilation unit to which a file instance belongs. More...

sfile	get_sfile () const
	Get the source file corresponding to a source file instance. More...

std::string	handle () const
	Get a handle for this sfileinst. More...

cs_hash_t	hash () const
	Get a hash value for a sfileinst. More...

std::vector< sfileinst >	include_tree_path () const
	Get the include tree path for a source file instance. More...

bool	is_system_include () const
	Check: is a file instance (sfileinst) an instance of a system include file? More...

line_number	line_count () const
	Get the number of lines in a source file instance. More...

file_offset	line_offset (line_number line) const
	Get the source file character offset corresponding to the first character of a line within an the source file instance. More...

std::pair< file_offset, file_offset >	line_range (line_number line) const
	Get the character offsets for the beginning and the end of a line within a source file. More...

std::string	name () const
	Get the unnormalized absolute path name for a source file instance. More...

std::string	normalized_name () const
	Get the normalized absolute path name for a source file instance. More...

line_number	offset_to_line (file_offset offset) const
	Get the line number associated with a point identified by an offset in a source file instance (sfileinst). More...

std::pair< line_number, column_number >	offset_to_line_column (file_offset offset) const
	Get the line number and column number associated with a point identified by an offset in a source file instance (sfileinst). More...

sfileinst	parent () const
	Get the include-tree parent of a source file instance. More...

sfileinst_line_pair	parent_line () const
	Get the include location of a source file instance. More...

std::string	read (line_number line_start, column_number col_start, line_number line_end, column_number col_end, size_t limit=SIZE_MAX) const
	Get a substring from a source file instance, using (line, column) pairs to specify the beginning and end of the substring. More...

std::string	read_line (line_number line, size_t limit=SIZE_MAX) const
	Read a single line from the source file. More...

std::string	read_lines (line_number line_start=1, line_number line_end=UINT32_MAX, size_t limit=SIZE_MAX) const
	Get a substring from a source file instance, using line numbers to specify the beginning and end of the substring. More...

int	stable_cmp (const sfileinst &other) const
	Comparison function for sfileinst, with stable results across sufficiently-similar analyses. More...

csuint64	stable_hash () const
	Get a hash value for a sfileinst, with stable results across sufficiently-similar analyses. More...

Related Functions
(Note that these are not member functions.)
bool	operator!= (const sfileinst &a, const sfileinst &b)
	Inequality operator for sfileinst. More...

bool	operator< (const sfileinst &a, const sfileinst &b)
	Less-than operator for sfileinst. More...

std::ostream &	operator<< (std::ostream &out, const sfileinst &a)
	Print a representation of a sfileinst object to the specified stream. More...

bool	operator<= (const sfileinst &a, const sfileinst &b)
	Less-than-or-equal operator for sfileinst. More...

bool	operator== (const sfileinst &a, const sfileinst &b)
	Equality operator for sfileinst. More...

bool	operator> (const sfileinst &a, const sfileinst &b)
	Greater-than operator for sfileinst. More...

bool	operator>= (const sfileinst &a, const sfileinst &b)
	Greater-than-or-equal operator for sfileinst. More...

Detailed Description

A source file instance.

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 details, see the Source Files manual page.

The following are useful for retrieving source file instances.

Class	Methods
point	point::file_line
procedure	procedure::file_line()
sfile	sfile::arbitrary_instance(), sfile::instances()

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

Member Function Documentation

◆ as_repr()

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

inline

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

Returns: The string representation.

◆ as_string()

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

inline

Get the unnormalized absolute path name for a source file instance.

Returns: The unnormalized absolute path name.

Exceptions

result::ERROR_CANNOT_FIND_PATH if there is no absolute path name associated with the source file instance.

Equivalent to name().

◆ asts_at() [1/2]

std::vector<ast> cs::sfileinst::asts_at ( line_number line ) const

inline

Get the ASTs at the specified location in a source file instance.

Parameters

[in] line A line number (after preprocessing) in the source file instance.

Returns: The ASTs (ast) that are located at line line of the source file instance.

Exceptions

result::NOT_IMPLEMENTED	if the retrieval function is not implemented for the language module being used. (Retrieval IS implemented for the C/C++ language module.)
result::ELEMENT_NOT_PRESENT	if the information is not available for the compilation.

◆ asts_at() [2/2]

std::vector<ast> cs::sfileinst::asts_at	(	line_number	line,
		const std::vector< ast_class > &	classes
	)		const

inline

Get the ASTs at the specified location in a source file instance.

Parameters

[in]	line	A line number (after preprocessing) in the source file instance.
[in]	classes	The AST-classes (ast_class) of interest.

Returns: The ASTs (ast) that are located at line line of the source file instance and are of the specified classes.

Exceptions

result::NOT_IMPLEMENTED	if the retrieval function is not implemented for the language module being used. (Retrieval IS implemented for the C/C++ language module.)
result::ELEMENT_NOT_PRESENT	if the information is not available for the compilation.

◆ child_at()

sfileinst cs::sfileinst::child_at ( line_number ln ) const

inline

Get the source file instance included at the specified line.

Parameters

[in] ln The line number of interest.

Returns: The include-tree child sfileinst included at line ln of the source file instance.

Exceptions

result::ELEMENT_NOT_PRESENT if no file is included at the given location. For example, this will occur for a C source file if the line does not contain a #include directive.

◆ children()

sfileinst_children_iterator cs::sfileinst::children ( ) const

inline

Get an iterator over the include-tree children of a source file instance.

Returns: The initialized sfileinst_children_iterator.

The children of a source file instance are the source file instances (sfileinst) that it #includes.

The ordering of #included children used by the iterator is not necessarily based on the ordering of #include statements in the file instance.

◆ children_vector()

std::vector<sfileinst> cs::sfileinst::children_vector ( ) const

inline

Get the include-tree children of a source file instance.

Returns: The include-tree children of the source file instance, as a std::vector of sfileinst.

The children of a source file instance are the source file instances that it #includes.

◆ cmp()

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

inline

Comparison function for sfileinst.

Parameters

other The sfileinst 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 sfileinst object.

◆ color_map_iterator()

sfileinst_color_map_iterator cs::sfileinst::color_map_iterator	(	syntax_kind	k,
		line_number	lowerbound = `0`
	)		const

inline

Get an iterator over the spans of the specified syntax_kind at or after the specified line in a source file instance, in order of appearance.

Parameters

[in]	k	The desired syntax_kind.
[in]	lowerbound	Specifies the line in the source file instance from which the search for spans should begin. Spans starting on earlier lines will be ignored. If `lowerbound` is 1 or lower, the entire file instance will be searched.

Returns: The initialized sfileinst_color_map_iterator.

◆ count_lines()

line_counts cs::sfileinst::count_lines	(	line_number	start = `1`,
		line_number	end = `UINT32_MAX`
	)		const

inline

For a set of adjacent lines in a source file instance, retrieve statistics about the classifications of the lines in the set.

Parameters

[in]	start	The first line in the set.
[in]	end	The last line in the set (inclusive). Use `UINT32_MAX` to denote the end of the file.

Returns: A line_counts object encoding line count statistics about the lines in the set. Use line_counts methods to recover individual statistics.

◆ get_compunit()

compunit cs::sfileinst::get_compunit ( ) const

inline

Get the compilation unit to which a file instance belongs.

Returns: The compilation unit (compunit) containing the file instance.

◆ get_sfile()

sfile cs::sfileinst::get_sfile ( ) const

inline

Get the source file corresponding to a source file instance.

Returns: The source file (sfile) of which this is an instance.

Exceptions

result::ERROR_INVALID_SFID if there is no corresponding source file.

The sfile :sfileinst relation is 1:many. For a given source source file F in the project the corresponding file instances are as follows.

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.

◆ handle()

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

inline

Get a handle for this sfileinst.

Returns: The sfileinst's handle.

Use this function to retrieve a handle to the sfileinst which can be stored externally and used with project::lookup_sfileinst_handle() to retrieve the sfileinst 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::sfileinst::hash ( ) const

inline

Get a hash value for a sfileinst.

◆ include_tree_path()

std::vector<sfileinst> cs::sfileinst::include_tree_path ( ) const

inline

Get the include tree path for a source file instance.

Returns: The include tree path, as a std::vector of sfileinst.

Exceptions

result::ERROR_CANNOT_FIND_PATH if there is no include path associated with the source file instance.

◆ is_system_include()

bool cs::sfileinst::is_system_include ( ) const

inline

Check: is a file instance (sfileinst) an instance of a system include file?

Returns: true if the file path matches matches a SYSTEM_INCLUDE_PATHS rule, false otherwise

◆ line_count()

line_number cs::sfileinst::line_count ( ) const

inline

Get the number of lines in a source file instance.

Returns: The number of lines in the source file instance.

◆ line_offset()

file_offset cs::sfileinst::line_offset ( line_number line ) const

inline

Get the source file character offset corresponding to the first character of a line within an the source file instance.

Parameters

[in] line The line for which to obtain the offset.

Returns: The character offset, from the start of the source file instance, of the first character of line.

Exceptions

result::ERROR_INVALID_SFID_OR_LINE if line is outside the boundaries of the source file instance.

◆ line_range()

std::pair<file_offset, file_offset> cs::sfileinst::line_range ( line_number line ) const

inline

Get the character offsets for the beginning and the end of a line within a source file.

Parameters

[in] line The line for which to obtain the character offsets.

Returns: A pair (s, e) of file_offset objects, where s is the offset of the start of line and e the offset of the end of line in the source file. If line is out of range, (s,e) will be the offsets of the beginning and end of the last line in the source file.

Exceptions

result::ERROR_INVALID_SFID_OR_LINE if the source file instance has no line corresponding to ln.

◆ name()

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

inline

Get the unnormalized absolute path name for a source file instance.

Returns: The unnormalized absolute path name.

Exceptions

result::ERROR_CANNOT_FIND_PATH if there is no absolute path name associated with the source file instance.

Use normalized_name() to get the normalized file path.

◆ normalized_name()

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

inline

Get the normalized absolute path name for a source file instance.

Returns

The normalized absolute path name.

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

Exceptions

result::ERROR_CANNOT_FIND_PATH if there is no absolute path name associated with the source file instance.

Use name() to get the unnormalized file path.

◆ offset_to_line()

line_number cs::sfileinst::offset_to_line ( file_offset offset ) const

inline

Get the line number associated with a point identified by an offset in a source file instance (sfileinst).

Parameters

[in] offset The offset of the point in the source file instance.

Returns: The line_number within the source file instance on which the point appears.

Exceptions

result::ELEMENT_NOT_PRESENT if offset is not within the bounds of the source file instance.

◆ offset_to_line_column()

std::pair<line_number, column_number> cs::sfileinst::offset_to_line_column ( file_offset offset ) const

inline

Get the line number and column number associated with a point identified by an offset in a source file instance (sfileinst).

Parameters

[in] offset The offset of the point in the source file instance.

Returns: The line_number and column_number within the source file instance on which the point appears.

Exceptions

result::ELEMENT_NOT_PRESENT if the source file instance has no line corresponding to ln.

◆ parent()

sfileinst cs::sfileinst::parent ( ) const

inline

Get the include-tree parent of a source file instance.

Returns: The include-tree parent sfileinst of the source file instance.

Exceptions

result::ELEMENT_NOT_PRESENT if this has no parent instance (i.e. is the top-level file instance of a compilation unit).

The include-tree parent of a source file instance is the source file instance that directly #includes it.

◆ parent_line()

sfileinst_line_pair cs::sfileinst::parent_line ( ) const

inline

Get the include location of a source file instance.

Returns: The include-tree parent sfileinst of the source file instance and the line at which the source file instance included in the parent.

Exceptions

result::ELEMENT_NOT_PRESENT if the source file instance represented by this is not included.

◆ read()

std::string cs::sfileinst::read	(	line_number	line_start,
		column_number	col_start,
		line_number	line_end,
		column_number	col_end,
		size_t	limit = `SIZE_MAX`
	)		const

inline

Get a substring from a source file instance, using (line, column) pairs to specify the beginning and end of the substring.

Parameters

[in]	line_start	The beginning line of the substring. One-based.
[in]	col_start	The beginning column of the substring. Zero-based.
[in]	line_end	The ending line of the substring. One-based.
[in]	col_end	The ending column of the substring, exclusive. Set to `UINT32_MAX` to read to the end of `line_end`.
[in]	limit	Upper bound on the length of the returned std::string. If the substring is longer than this, it will be truncated. Set to `SIZE_MAX` to return the entire substring, regardless of its length.

Returns: A string containing the characters from (line_start, col_start) to (line_end, col_end) of the source file instance.

To read a single line from a source file instance, use read_line().
To read a range of lines from a source file instance, use read_lines().

Exceptions

result::ERROR_IO_OPEN_FILE_TO_READ	if the corresponding source file cannot be opened for reading.
result::ERROR_IO_SEEK	if (`line_start`, `col_start`) is not a valid position within the source file instance.
result::ERROR_IO_READ	if `line_end` is not a valid line within the source file instance.
result::DISCRETIONARY_ERROR_IO_PARTIAL_READ	if `col_end` is not a valid column within `line_end`.
result::ERROR_INVALID_ARGUMENT	if the specified start location is after the specified end location.

◆ read_line()

std::string cs::sfileinst::read_line	(	line_number	line,
		size_t	limit = `SIZE_MAX`
	)		const

inline

Read a single line from the source file.

Parameters

[in]	line	The 1-based line number to read.
[in]	limit	Upper bound on the length of the returned std::string. If the substring is longer than this, it will be truncated. Set to `SIZE_MAX` to return the entire substring, regardless of its length.

Returns: A string containing the characters on the specified line.

To read a range of lines from a source file instance, use read_lines().
To read a substring that does not precisely align with line boundaries, use read().

Exceptions

result::ERROR_IO_OPEN_FILE_TO_READ	if the corresponding source file cannot be opened for reading.
result::ERROR_IO_SEEK	if `line` is not a valid position within the source file instance.

◆ read_lines()

std::string cs::sfileinst::read_lines	(	line_number	line_start = `1`,
		line_number	line_end = `UINT32_MAX`,
		size_t	limit = `SIZE_MAX`
	)		const

inline

Get a substring from a source file instance, using line numbers to specify the beginning and end of the substring.

Parameters

[in]	line_start	The beginning line of the substring. One-based.
[in]	line_end	The ending line of the substring, exclusive. One-based. Set to `UINT32_MAX` to read to the end of the file.
[in]	limit	Upper bound on the length of the returned std::string. If the substring is longer than this, it will be truncated. Set to `SIZE_MAX` to return the entire substring, regardless of its length.

Returns: A string containing the characters from line_start to line_end of the source file instance.

To read the entire contents of the source file instance represented by sfileinst S, use:

S.read_lines()

To read a single line from a source file instance, use read_line().
To read a substring that does not precisely align with line boundaries, use read().

Exceptions

result::ERROR_IO_OPEN_FILE_TO_READ	if the corresponding source file cannot be opened for reading.
result::ERROR_IO_SEEK	if `line_start` is not a valid position within the source file instance.
result::ERROR_IO_READ	if `line_end` is not a valid line within the source file instance.
result::ERROR_INVALID_ARGUMENT	if the specified start location is after the specified end location.

◆ stable_cmp()

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

inline

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

Parameters

[in] other The sfileinst to compare against.

Returns

An integer N such that:

N<0 if this considered less than other
N==0 if this and other are the same object
N>0 if this considered greater than other

This function is provided so sfileinst 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 sfileinst objects in A1, and a2 and b2 be the sfileinst 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::sfileinst::stable_hash ( ) const

inline

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

Returns: A hash derived from the source file instance.

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 sfileinst in A1, and b2 be the sfileinst 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.

Friends And Related Function Documentation

◆ operator!=()

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

Parameters

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

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

◆ operator<()

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

Parameters

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

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

◆ operator<<()

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

Parameters

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

Returns: void

◆ operator<=()

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

Parameters

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

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

◆ operator==()

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

Parameters

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

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

◆ operator>()

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

Parameters

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

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

◆ operator>=()

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

Parameters

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

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

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

Public Member Functions

Related Functions

Detailed Description

Member Function Documentation

◆ as_repr()

◆ as_string()

◆ asts_at() [1/2]

◆ asts_at() [2/2]

◆ child_at()

◆ children()

◆ children_vector()

◆ cmp()

◆ color_map_iterator()

◆ count_lines()

◆ get_compunit()

◆ get_sfile()

◆ handle()

◆ hash()

◆ include_tree_path()

◆ is_system_include()

◆ line_count()

◆ line_offset()

◆ line_range()

◆ name()

◆ normalized_name()

◆ offset_to_line()

◆ offset_to_line_column()

◆ parent()

◆ parent_line()

◆ read()

◆ read_line()

◆ read_lines()

◆ stable_cmp()

◆ stable_hash()

Friends And Related Function Documentation

◆ operator!=()

◆ operator<()

◆ operator<<()

◆ operator<=()

◆ operator==()

◆ operator>()

◆ operator>=()