Contents

• class sfileinst
  • sfileinst Members
  • sfileinst Details

class sfileinst

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.

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.

sfileinst Members

Constructors

none

Methods

__cmp__(), __eq__(), __ge__(), __gt__(), __hash__(), __le__(), __lt__(), __ne__(), __repr__(), __str__(), asts_at(), child_at(), children(), children_vector(), color_map_iterator(), count_lines(), get_compunit(), get_sfile(), handle(), 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()

sfileinst Details

class cs.sfileinst

A source file instance.

__cmp__(other)

Comparison function for sfileinst .

Parameters:other (sfileinst) – The sfileinst 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

>>> files = project.current().sfiles()
>>> sfi1 = next(files).arbitrary_instance()
>>> sfi1
<cs.sfileinst C:\alex\test\apitest.cpp>
>>> sfi2 = next(files).arbitrary_instance()
>>> sfi2
<cs.sfileinst C:\Program Files\CodeSecure\CodeSonar\csurf\csinclude\gcc_builtins.h>
>>> sfi1.__cmp__(sfi2)
-1

__eq__(b)

Equality operator for sfileinst .

Parameters:b (sfileinst) – The sfileinst to compare against. Return type:bool Returns:True if self and b compare equal, False otherwise.

>>> files = project.current().sfiles()
>>> sfi1 = next(files).arbitrary_instance()
>>> sfi1
<cs.sfileinst C:\alex\test\apitest.cpp>
>>> sfi2 = next(files).arbitrary_instance()
>>> sfi2
<cs.sfileinst C:\Program Files\CodeSecure\CodeSonar\csurf\csinclude\gcc_builtins.h>
>>> sfi1 == sfi2
False

__ge__(b)

Greater-than-or-equal operator for sfileinst .

Parameters:b (sfileinst) – The sfileinst to compare against. Return type:bool Returns:True if self >= b , False otherwise.

>>> files = project.current().sfiles()
>>> sfi1 = next(files).arbitrary_instance()
>>> sfi1
<cs.sfileinst C:\alex\test\apitest.cpp>
>>> sfi2 = next(files).arbitrary_instance()
>>> sfi2
<cs.sfileinst C:\Program Files\CodeSecure\CodeSonar\csurf\csinclude\gcc_builtins.h>
>>> sfi1 >= sfi2
False

__gt__(b)

Greater-than operator for sfileinst .

Parameters:b (sfileinst) – The sfileinst to compare against. Return type:bool Returns:True if self > b , False otherwise.

>>> files = project.current().sfiles()
>>> sfi1 = next(files).arbitrary_instance()
>>> sfi1
<cs.sfileinst C:\alex\test\apitest.cpp>
>>> sfi2 = next(files).arbitrary_instance()
>>> sfi2
<cs.sfileinst C:\Program Files\CodeSecure\CodeSonar\csurf\csinclude\gcc_builtins.h>
>>> sfi1 > sfi2
False

__hash__()

Get a hash value for a sfileinst .

Return type:int

>>> files = project.current().sfiles()
>>> sfi1 = next(files).arbitrary_instance()
>>> sfi1
<cs.sfileinst C:\alex\test\apitest.cpp>
>>> hash(sfi1)
2531392338

__le__(b)

Less-than-or-equal operator for sfileinst .

Parameters:b (sfileinst) – The sfileinst to compare against. Return type:bool Returns:True if self <= b , False otherwise.

>>> files = project.current().sfiles()
>>> sfi1 = next(files).arbitrary_instance()
>>> sfi1
<cs.sfileinst C:\alex\test\apitest.cpp>
>>> sfi2 = next(files).arbitrary_instance()
>>> sfi2
<cs.sfileinst C:\Program Files\CodeSecure\CodeSonar\csurf\csinclude\gcc_builtins.h>
>>> sfi1 <= sfi2
True

__lt__(b)

Less-than operator for sfileinst .

Parameters:b (sfileinst) – The sfileinst to compare against. Return type:bool Returns:True if self < b , False otherwise.

>>> files = project.current().sfiles()
>>> sfi1 = next(files).arbitrary_instance()
>>> sfi1
<cs.sfileinst C:\alex\test\apitest.cpp>
>>> sfi2 = next(files).arbitrary_instance()
>>> sfi2
<cs.sfileinst C:\Program Files\CodeSecure\CodeSonar\csurf\csinclude\gcc_builtins.h>
>>> sfi1 < sfi2
True

__ne__(b)

Inequality operator for sfileinst .

Parameters:b (sfileinst) – The sfileinst to compare against. Return type:bool Returns:False if self and b compare equal, True otherwise.

>>> files = project.current().sfiles()
>>> sfi1 = next(files).arbitrary_instance()
>>> sfi1
<cs.sfileinst C:\alex\test\apitest.cpp>
>>> sfi2 = next(files).arbitrary_instance()
>>> sfi2
<cs.sfileinst C:\Program Files\CodeSecure\CodeSonar\csurf\csinclude\gcc_builtins.h>
>>> sfi1 != sfi2
True

__repr__()

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

Return type:str Returns:The string representation.

>>> files = project.current().sfiles()
>>> sfi1 = next(files).arbitrary_instance()
>>> sfi1
<cs.sfileinst C:\alex\test\apitest.cpp>
>>> repr(sfi1)
'<cs.sfileinst C:\\alex\\test\\apitest.cpp>'

__str__()

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

Return type:str Returns:The unnormalized absolute path name. Raises:result.ERROR_CANNOT_FIND_PATH if there is no absolute path name associated with the source file instance.

Equivalent to sfileinst.name().

>>> files = project.current().sfiles()
>>> sfi1 = next(files).arbitrary_instance()
>>> sfi1
<cs.sfileinst C:\alex\test\apitest.cpp>
>>> str(sfi1)
'C:\\alex\\test\\apitest.cpp'

asts_at(line)

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

Parameters:line (int) – A line number (after preprocessing) in the source file instance. Return type:[ast] Returns:The ASTs ( ast ) that are located at line line of the source file instance.

v0 = project.current()
v1 = v0.sfiles()
v2 = v1.__next__()
v3 = v2.arbitrary_instance()
v3.asts_at(3)
(<cs.ast [cc:routine] mymalloc>, <cs.ast [cc:parameter] i>, <cs.ast [cc:routine-type] int *(int)>, <cs.ast [cc:integer] int>)

asts_at(line, classes)

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

Parameters:

• line (int) – A line number (after preprocessing) in the source file instance.
• classes (iterable of ast_class) – The AST-classes ( ast_class ) of interest.

Return type:

[ast]

Returns:

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

Raises:

• OverflowError
• 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.

>>> v0 = project.current()
>>> v1 = v0.sfiles()
>>> v2 = v1.next()
>>> v3 = v2.arbitrary_instance()
>>> v3.asts_at(1, [ast_class.NC_INTEGER_VALUE_32, ast_class.NC_DIVEXPR, ast_class.NC_FILE_INFO, ast_class.NC_ABSTRACT_RVALUE, ast_class.UC_ROUTINE_TYPE, ast_class.UC_POINTS_TO_STATIC, ast_class.NC_ASSUMEEXPR, ast_class.UC_INTEGER_VALUE_128, ast_class.NC_ABSTRACT_LVALUE, ast_class.NC_FLOAT_VALUE_128, ast_class.UC_PRAGMA_STDC, ast_class.NC_GREATEQUALEXPR, ast_class.NC_INTEGER_VALUE_128, ast_class.NC_COMPLEX_REAL_PART, ast_class.NC_INTEGER_VALUE_64, ast_class.UC_ABSTRACT_TYPE, ast_class.UC_REMAINDER, ast_class.UC_COMPLEX, ast_class.NC_COMPLEMENTEXPR, ast_class.UC_GENERIC_ASSIGN, ast_class.NC_ABI, ast_class.NC_CODESURFER_TYPE, ast_class.UC_LABEL, ast_class.NC_IFTHENELSEEXPR, ast_class.NC_FLOAT_VALUE_32])
(<cs.ast [cc:routine-type] void *(unsigned int) C>, <cs.ast [cc:routine-type] void *(unsigned int) C>)

child_at(ln)

Get the source file instance included at the specified line.

Parameters:

ln (int) – The line number of interest.

Return type:

sfileinst

Returns:

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

Raises:

• 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.
• OverflowError

>>> sf = next(s for s in project.current().sfiles()
...           if s.name().endswith('apitest.cpp'))
>>> sfi = sf.arbitrary_instance()
>>> for line in range(1, sfi.line_count()+1):
...    try:
...       ch = sfi.child_at(line)
...    except:
...       ch = ''
...    if ch:
...       print(line, ch)
...
2 C:\alex\test\apitest.h

children()

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

Return type:sfileinst_children_iterator 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.

>>> cu = next(c for c in project.current().compunits() if c.name().endswith('apitest.cpp'))
>>> sfi = cu.get_sfileinst()
>>> for s in sfi.children(): # iteration managed by sfileinst_children_iterator.__iter__()
...                          # and sfileinst_children_iterator.__next__()
...     if 'apitest' in s.name():
...         print(s)
...
C:\alex\test\apitest.h

children_vector()

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

Return type:[sfileinst] Returns:The include-tree children of the source file instance, as a list of sfileinst .

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

>>> cu = next(c for c in project.current().compunits() if c.name().endswith('apitest.cpp'))
>>> sfi = cu.get_sfileinst()
>>> sfi.children_vector()
(<cs.sfileinst C:\Program Files\CodeSecure\CodeSonar\csurf\csinclude\gcc_builtins.h>, <cs.sfileinst C:\alex\test\apitest.h>)
>

color_map_iterator(k[, lowerbound = 0])

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:

• k (syntax_kind) – The desired syntax_kind .
• lowerbound (int) – (optional) 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.

Return type:

sfileinst_color_map_iterator

Returns:

The initialized sfileinst_color_map_iterator .

>>> cu = next(c for c in project.current().compunits() if c.name().endswith('apitest.cpp'))
>>> sfi = cu.get_sfileinst()
>>> for (startline, startcol),(endline,endcol) in sfi.color_map_iterator(syntax_kind.KEYWORD, 40): # iteration managed by sfileinst_color_map_iterator.__iter__()
...                                                                                                # and sfileinst_color_map_iterator.__next__()
...     print(sfi.read(startline, startcol, endline, endcol))
...
int
void
catch
return
return

>>> cu = next(c for c in project.current().compunits() if c.name().endswith('apitest.cpp'))
>>> sfi = cu.get_sfileinst()
>>> sfi.children_vector()
(<cs.sfileinst C:\Program Files\CodeSecure\CodeSonar\csurf\csinclude\gcc_builtins.h>, <cs.sfileinst C:\alex\test\apitest.h>)
>>> cu = next(c for c in project.current().compunits() if c.name().endswith('apitest.cpp'))
>>> sfi = cu.get_sfileinst()
>>> for (startline, startcol),(endline,endcol) in sfi.color_map_iterator(syntax_kind.KEYWORD): # iteration managed by sfileinst_color_map_iterator.__iter__()
...                                                  # and sfileinst_color_map_iterator.__next__()
...     if startline >=40:
...         print(sfi.read(startline, startcol, endline,endcol))
...
int
void
catch
return
return

count_lines([start = 1[, end = UINT32_MAX]])

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

Parameters:

• start (int) – (optional) The first line in the set.
• end (int) – (optional) The last line in the set (inclusive). Use UINT32_MAX to denote the end of the file.

Return type:

line_counts

Returns:

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

>>> cu = next(c for c in project.current().compunits() if c.name().endswith('apitest.cpp'))
>>> sfi = cu.get_sfileinst()
>>> sfi.count_lines(5, 15)
<cs.line_counts blank: 1, comment: 0, code: 10, mixed: 0>

>>> cu = next(c for c in project.current().compunits() if c.name().endswith('apitest.cpp'))
>>> sfi = cu.get_sfileinst()
>>> sfi.count_lines(5)
<cs.line_counts blank: 2, comment: 0, code: 41, mixed: 0>

>>> cu = next(c for c in project.current().compunits() if c.name().endswith('apitest.cpp'))
>>> sfi = cu.get_sfileinst()
>>> sfi.count_lines()
<cs.line_counts blank: 2, comment: 1, code: 44, mixed: 0>

get_compunit()

Get the compilation unit to which a file instance belongs.

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

>>> sf = next(s for s in project.current().sfiles()
...           if s.name().endswith('apitest.cpp'))
>>> sfi = sf.arbitrary_instance()
>>> sfi.get_compunit()
<cs.compunit C:\alex\test\apitest.cpp>

get_sfile()

Get the source file corresponding to a source file instance.

Return type:sfile Returns:The source file ( sfile ) of which self is an instance. Raises: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.

>>> sf = next(s for s in project.current().sfiles()
...           if s.name().endswith('apitest.cpp'))
>>> sfi = sf.arbitrary_instance()
>>> sf2 = sfi.get_sfile()
>>> sf == sf2
True

handle()

Get a handle for this sfileinst .

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

>>> sf = next(s for s in project.current().sfiles()
...           if s.name().endswith('apitest.cpp'))
>>> sfi = sf.arbitrary_instance()
>>> sfi.handle()
'25LwkQ2Rref18+nXj+MB'

include_tree_path()

Get the include tree path for a source file instance.

Return type:[sfileinst] Returns:The include tree path, as a list of sfileinst . Raises:result.ERROR_CANNOT_FIND_PATH if there is no include path associated with the source file instance.

>>> sf = next(s for s in project.current().sfiles()
...           if s.name().endswith('apitest.h'))
>>> sfi = sf.arbitrary_instance()
>>> sfi.include_tree_path()
(<cs.sfileinst C:\alex\test\apitest.cpp>, <cs.sfileinst C:\alex\test\apitest.h>)

is_system_include()

Check: is a file instance an instance of a system include file?

Return type:bool Returns:True if the file path matches matches a SYSTEM_INCLUDE_PATHS rule, False otherwise

>>> sf = next(s for s in project.current().sfiles()
...           if s.name().endswith('apitest.h'))
>>> sfi = sf.arbitrary_instance()
>>> sfi.is_system_include()
False

line_count()

Get the number of lines in a source file instance.

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

>>> sf = next(s for s in project.current().sfiles()
...           if s.name().endswith('apitest.cpp'))
>>> sfi = sf.arbitrary_instance()
>>> sfi.line_count()
47

line_offset(line)

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

Parameters:

line (int) – The line for which to obtain the offset.

Return type:

int

Returns:

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

Raises:

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

>>> sf = next(s for s in project.current().sfiles()
...           if s.name().endswith('apitest.cpp'))
>>> sfi = sf.arbitrary_instance()
>>> sfi.line_offset(6)
83

line_range(line)

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

Parameters:

line (int) – The line for which to obtain the character offsets.

Return type:

(int, int)

Returns:

A pair (s, e) of int 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.

Raises:

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

>>> sf = next(s for s in project.current().sfiles()
...           if s.name().endswith('apitest.cpp'))
>>> sfi = sf.arbitrary_instance()
>>> sfi.line_range(6)
(83, 113)

name()

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

Return type:str Returns:The unnormalized absolute path name. Raises:result.ERROR_CANNOT_FIND_PATH if there is no absolute path name associated with the source file instance.

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

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

normalized_name()

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

Return type:str Returns:The normalized absolute path name.

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

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

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

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

offset_to_line(offset)

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

Parameters:

offset (int) – The offset of the point in the source file instance.

Return type:

int

Returns:

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

Raises:

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

>>> sf = next(s for s in project.current().sfiles()
...           if s.name().endswith('apitest.cpp'))
>>> sfi = sf.arbitrary_instance()
>>> sfi.offset_to_line_column(84)
(6, 1)

offset_to_line_column(offset)

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

Parameters:

offset (int) – The offset of the point in the source file instance.

Return type:

(int, int)

Returns:

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

Raises:

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

>>> sf = next(s for s in project.current().sfiles()
...           if s.name().endswith('apitest.cpp'))
>>> sfi = sf.arbitrary_instance()
>>> sfi.offset_to_line_column(84)
(6, 1)

parent()

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

Return type:sfileinst Returns:The include-tree parent sfileinst of the source file instance. Raises:result.ELEMENT_NOT_PRESENT if self 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.

>>> sf = next(s for s in project.current().sfiles()
...           if s.name().endswith('apitest.h'))
>>> sfi = sf.arbitrary_instance()
>>> sfi.parent()
<cs.sfileinst C:\alex\test\apitest.cpp>

parent_line()

Get the include location of a source file instance.

Return type:(sfileinst, int) Returns:The include-tree parent sfileinst of the source file instance and the line at which the source file instance included in the parent. Raises:result.ELEMENT_NOT_PRESENT if the source file instance represented by self is not included.

>>> sf = next(s for s in project.current().sfiles()
...           if s.name().endswith('apitest.h'))
>>> sfi = sf.arbitrary_instance()
>>> sfi.parent_line()
(<cs.sfileinst C:\ales\test\apitest.cpp>, 2)

read(line_start, col_start, line_end, col_end[, limit = SIZE_MAX])

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

Parameters:

• line_start (int) – The beginning line of the substring. One-based.
• col_start (int) – The beginning column of the substring. Zero-based.
• line_end (int) – The ending line of the substring. One-based.
• col_end (int) – The ending column of the substring, exclusive. Set to UINT32_MAX to read to the end of line_end.
• limit (int) – (optional) Upper bound on the length of the returned 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.

Return type:

str

Returns:

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

Raises:

• result.ERROR_INVALID_ARGUMENT if the specified start location is after the specified end location.
• result.ERROR_IO_SEEK if (line_start, col_start) is not a valid position within the source file instance.
• result.ERROR_IO_OPEN_FILE_TO_READ if the corresponding source file cannot be opened for reading.
• 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.

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

>>> sf = next(s for s in project.current().sfiles()
...           if s.name().endswith('apitest.cpp'))
>>> sfi = sf.arbitrary_instance()
>>> sfi.read(3, 4, 7, 100, 20)
'*mymalloc(int i)\n{\n '
>>> sfi.read(3, 4, 7, 100, 30)
'*mymalloc(int i)\n{\n    int *wh'

>>> sf = next(s for s in project.current().sfiles()
...           if s.name().endswith('apitest.cpp'))
>>> sfi = sf.arbitrary_instance()
>>> sfi.read(3, 4, 7, 100)
'*mymalloc(int i)\n{\n    int *whoknows(int);\n    return (int*)whoknows(i);\n}\n'

read_line(line[, limit = SIZE_MAX])

Read a single line from the source file.

Parameters:

• line (int) – The 1-based line number to read.
• limit (int) – (optional) Upper bound on the length of the returned 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.

Return type:

str

Returns:

A string containing the characters on the specified line.

Raises:

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

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

>>> sf = next(s for s in project.current().sfiles()
...           if s.name().endswith('apitest.cpp'))
>>> sfi = sf.arbitrary_instance()
>>> sfi.read_line(6, 15)
'    return (int'

>>> sf = next(s for s in project.current().sfiles()
...           if s.name().endswith('apitest.cpp'))
>>> sfi = sf.arbitrary_instance()
>>> sfi.read_line(6)
'    return (int*)whoknows(i);\n'

read_lines([line_start = 1[, line_end = UINT32_MAX[, limit = SIZE_MAX]]])

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

Parameters:

• line_start (int) – (optional) The beginning line of the substring. One-based.
• line_end (int) – (optional) The ending line of the substring, exclusive. One-based. Set to UINT32_MAX to read to the end of the file.
• limit (int) – (optional) Upper bound on the length of the returned 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.

Return type:

str

Returns:

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

Raises:

• result.ERROR_INVALID_ARGUMENT if the specified start location is after the specified end location.
• result.ERROR_IO_SEEK if line_start is not a valid position within the source file instance.
• result.ERROR_IO_OPEN_FILE_TO_READ if the corresponding source file cannot be opened for reading.
• result.ERROR_IO_READ if line_end is not a valid line within 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 sfileinst.read_line().
• To read a substring that does not precisely align with line boundaries, use sfileinst.read().

>>> sf = next(s for s in project.current().sfiles()
...           if s.name().endswith('apitest.cpp'))
>>> sfi = sf.arbitrary_instance()
>>> sfi.read_lines(40, 42, 30)
'        int j = bar(5, (void*)'

>>> sf = next(s for s in project.current().sfiles()
...           if s.name().endswith('apitest.cpp'))
>>> sfi = sf.arbitrary_instance()
>>> sfi.read_lines(40, 42)
'        int j = bar(5, (void*)foo, 100+5);\n        s.j = j;\n'

>>> sf = next(s for s in project.current().sfiles()
...           if s.name().endswith('apitest.cpp'))
>>> sfi = sf.arbitrary_instance()
>>> sfi.read_lines(40)
'        int j = bar(5, (void*)foo, 100+5);\n        s.j = j;\n    }catch(...)\n    {\n        return "foo";\n    }\n    return "bar";\n}\n'

>>> sf = next(s for s in project.current().sfiles()
...           if s.name().endswith('apitest.h'))
>>> sfi = sf.arbitrary_instance()
>>> sfi.read_lines()
'extern "C" void *undef_func(unsigned);\n'

stable_cmp(other)

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

Parameters:other (sfileinst) – The sfileinst to compare against. Return type:int Returns:An integer N such that:

• N<0 if self considered less than other
• N==0 if self and other are the same object
• N>0 if self 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 sfileinst.__cmp__(): it has better performance.

>>> files = project.current().sfiles()
>>> sfi1 = next(files).arbitrary_instance()
>>> sfi1
<cs.sfileinst C:\alex\test\apitest.cpp>
>>> sfi2 = next(files).arbitrary_instance()
>>> sfi2
<cs.sfileinst C:\Program Files\CodeSecure\CodeSonar\csurf\csinclude\gcc_builtins.h>
>>> sfi1.stable_cmp(sfi2)
1

stable_hash()

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

Return type:int 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 sfileinst.__hash__(): it has better performance.

>>> sf = next(s for s in project.current().sfiles()
...           if s.name().endswith('apitest.cpp'))
>>> sfi = sf.arbitrary_instance()
>>> sfi.stable_hash()
3298691897