Contents

class point_set

A set of points ( point ).

Use a point_set_iterator to iterate over a point_set . For example:

for e in my_point_set:
    print('point: ', e)

point_set Members

Constructor __init__()
Methods __contains__(), __eq__(), __hash__(), __iter__(), __len__(), __ne__(), __repr__(), __str__(), add(), categorize(), categorize_by_file(), clear(), difference(), discard(), empty(), intersect(), intersect_size(), intersects_procedure(), kind(), procedures(), remove(), sort(), to_int_pair_set_in_sfileinst(), to_vector(), union(), union_p()

point_set Details

class cs.point_set

A set of points ( point ).

__init__()

Construct an empty set.

>>> point_set()
<cs.point_set {}>
__init__(other)

Copy constructor.

Parameters:other (point_set) – 
>>> barfn = next(p for p in project.current().procedures() if p.name()=='bar')
>>> barins = barfn.formal_ins()
>>> point_set(barins)
<cs.point_set {<cs.point [formal-in] >, <cs.point [formal-in] >, <cs.point [formal-in] >}>
__init__(v)

Construct a set from a list of elements.

Parameters:v (iterable of point) – The set elements. 
>>> barfn = next(p for p in project.current().procedures() if p.name()=='bar')
>>> mypoints = point_set([barfn.entry_point(), barfn.exit_point()])
>>> mypoints
<cs.point_set {<cs.point [entry] bar(int, void *, int)>, <cs.point [exit] bar(int, void *, int)>}>
__init__(k)

Construct an empty set of the specified kind.

Parameters:k (set_kind) – The set kind.
Raises:result.ERROR_CODESURFER_ONLY if k is set_kind.TRIE, which is only available in CodeSurfer. 
>>> point_set(set_kind.FAST_VECTOR)
<cs.point_set {}>
__contains__(elt)

Check: does the set contain the specified element?

Parameters:elt (point) – The element to check.
Return type:bool
Returns:True if elt is present in the set, False otherwise. 
>>> barfn = next(p for p in project.current().procedures() if p.name()=='bar')
>>> mypoints = point_set([barfn.entry_point(), barfn.exit_point()])
>>> mypoints
<cs.point_set {<cs.point [entry] bar(int, void *, int)>, <cs.point [exit] bar(int, void *, int)>}>
>>> barfn.entry_point() in mypoints
True
>>> barfn.entry_point().solitary_cfg_target() in mypoints
False
__eq__(__y)

Equality operator for point_set .

Parameters:__y (point_set) – The set to compare against.
Return type:bool
Returns:True if self equal to __y, False otherwise. 
>>> barfn = next(p for p in project.current().procedures() if p.name()=='bar')
>>> entryset = point_set([barfn.entry_point()])
>>> entryexitset = point_set([barfn.entry_point(), barfn.exit_point()])
>>> entryset == entryexitset
False
>>> entryset == entryset
True
__hash__()

Get a hash of the set.

Return type:int
Returns:The hash value for the set. 
>>> barfn = next(p for p in project.current().procedures() if p.name()=='bar')
>>> myset = point_set([barfn.entry_point(), barfn.exit_point()])
>>> hash(myset)
1755625185
__iter__()

Get an iterator over the set elements.

Return type:point_set_iterator
Returns:An iterator over the set elements. 
>>> proc =  project.current().find_procedure('mymalloc(int)')
>>> for pt in proc.callers():  # implicit use of point_set.__iter__(); point_set_iterator.__next__()
...       fl = pt.file_line()
...       print(fl[0].normalized_name().split('/')[-1], fl[1])
...
apitest.cpp 37
apitest.cpp 15
__len__()

Get the set cardinality.

Return type:int
Returns:The number of elements in the set. 
>>> barfn = next(p for p in project.current().procedures() if p.name()=='bar')
>>> myset = point_set([barfn.entry_point(), barfn.exit_point()])
>>> len(myset)
2
__ne__(__y)

Inequality operator for point_set .

Parameters:__y (point_set) – The set to compare against.
Return type:bool
Returns:False if self equal to __y according to point_set.__eq__(), True otherwise. 
>>> barfn = next(p for p in project.current().procedures() if p.name()=='bar')
>>> entryset = point_set([barfn.entry_point()])
>>> entryexitset = point_set([barfn.entry_point(), barfn.exit_point()])
>>> entryset != entryexitset
True
>>> entryset != entryset
False
__repr__()

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

Return type:str 
>>> barfn = next(p for p in project.current().procedures() if p.name()=='bar')
>>> myset = point_set([barfn.entry_point(), barfn.exit_point()])
>>> repr(myset)
'<cs.point_set {<cs.point [entry] bar(int, void *, int)>, <cs.point [exit] bar(int, void *, int)>}>'
__str__()

Get a simple string representation of a set object.

Return type:str 
>>> barfn = next(p for p in project.current().procedures() if p.name()=='bar')
>>> myset = point_set([barfn.entry_point(), barfn.exit_point()])
>>> str(myset)
'{<cs.point [entry] bar(int, void *, int)>, <cs.point [exit] bar(int, void *, int)>}'
add(v)

Add an element to the set.

Parameters:v (point) – The element to add.
Return type:bool
Returns:True if v was not already present in the set, False if it was already present.
  • Side effects: Modifies self.
>>> barfn = next(p for p in project.current().procedures() if p.name()=='bar')
>>> p = point_set()
>>> p
<cs.point_set {}>
>>> p.add(barfn.entry_point())
True
>>> p
<cs.point_set {<cs.point [entry] bar(int, void *, int)>}>
>>> p.add(barfn.entry_point())
False
categorize()

Categorize the points in a point_set by the compilation unit and procedure in which they are found.

Return type:[(compunit, [(procedure, point_set)])]
Returns:A list in which the points ( point ) in the set are categorized by compilation unit ( compunit ) and, within each compilation unit, by procedure .
Raises:result.ERROR_SDG_NOT_PRESENT if no project is loaded. 
>>> barfn = next(p for p in project.current().procedures() if p.name()=='bar')
>>> myset = point_set([barfn.entry_point(), barfn.exit_point()])
>>> myset.categorize()
((<cs.compunit C:\alex\test\apitest.cpp>, ((<cs.procedure bar>, <cs.point_set {<cs.point [entry] bar(int, void *, int)>, <cs.point [exit] bar(int, void *, int)>}>),)),)
categorize_by_file()

Categorize the points in a point_set by the compilation unit in which they are found.

Return type:[(compunit, point_set)]
Returns:A list in which the points ( point ) in the set are categorized by compilation unit ( compunit ).
Raises:result.ERROR_SDG_NOT_PRESENT if no project is loaded. 
>>> barfn = next(p for p in project.current().procedures() if p.name()=='bar')
>>> myset = point_set([barfn.entry_point(), barfn.exit_point()])
>>> myset.categorize_by_file()
((<cs.compunit C:\alex\test\apitest.cpp>, <cs.point_set {<cs.point [entry] bar(int, void *, int)>, <cs.point [exit] bar(int, void *, int)>}>),)
clear()

Remove all elements from the set (that is, make it empty).

Return type:NoneType
  • Side effects: Modifies self.
>>> barfn = next(p for p in project.current().procedures() if p.name()=='bar')
>>> myset = point_set([barfn.entry_point(), barfn.exit_point()])
>>> myset
<cs.point_set {<cs.point [entry] bar(int, void *, int)>, <cs.point [exit] bar(int, void *, int)>}>
>>> myset.clear()
>>> myset
<cs.point_set {}>
difference(b)

Set difference.

Parameters:b (point_set) – The set to subtract from self.
Return type:point_set
Returns:A set containing self - b.

The returned set contains the elements in self that are not in b.

>>> cu = next(c for c in project.current().compunits() if c.name().endswith('apitest.cpp'))
>>> proc = next(p for p in cu.procedures() if p.name()=='bar')
>>> pfis = proc.formal_ins()
>>> len(pfis)
3
>>> ppts = proc.points()
>>> len(ppts)
40
>>> ppts.intersect_size(pfis)
3
>>> no_pfis = ppts.difference(pfis)
>>> len(no_pfis)
37
>>> no_pfis.intersect_size(pfis)
0
discard(v)

Remove an element from the set.

Parameters:v (point) – The element to remove.
Return type:NoneType
Returns:The number of elements deleted:
  • 1 if v was present in the set.
  • 0 if v was not present in the set.
  • Side effects: Modifies self.
>>> barfn = next(p for p in project.current().procedures() if p.name()=='bar')
>>> myset = point_set([barfn.entry_point(), barfn.exit_point()])
>>> myset
<cs.point_set {<cs.point [entry] bar(int, void *, int)>, <cs.point [exit] bar(int, void *, int)>}>
>>> myset.discard(barfn.entry_point())
>>> myset
<cs.point_set {<cs.point [exit] bar(int, void *, int)>}>
empty()

Check: is the set empty?

Return type:bool
Returns:True if the set is empty, False otherwise. 
>>> barfn = next(p for p in project.current().procedures() if p.name()=='bar')
>>> p = point_set()
>>> p.empty()
True
>>> p.add(barfn.entry_point())
True
>>> p.empty()
False
intersect(b)

Set intersection.

Parameters:b (point_set) – The other operand for the intersection operation.
Return type:point_set
Returns:A set containing self INTERSECT b.

The returned set contains the elements that are in both self and b.

>>> barfn = next(p for p in project.current().procedures() if p.name()=='bar')
>>> myset = point_set([barfn.entry_point(), barfn.exit_point()])
>>> copyset = point_set(myset)
>>> copyset.discard(barfn.exit_point())
>>> myset
<cs.point_set {<cs.point [entry] bar(int, void *, int)>, <cs.point [exit] bar(int, void *, int)>}>
>>> copyset
<cs.point_set {<cs.point [entry] bar(int, void *, int)>}>
>>> myset.intersect(copyset)
<cs.point_set {<cs.point [entry] bar(int, void *, int)>}>
intersect_size(other)

Get the number of elements in the intersection of two point_set sets.

Parameters:other (point_set) – The point_set to intersect with.
Return type:int
Returns:The number of elements in the intersection with other. 
>>> cu = next(c for c in project.current().compunits() if c.name().endswith('apitest.cpp'))
>>> proc = next(p for p in cu.procedures() if p.name()=='bar')
>>> pfis = proc.formal_ins()
>>> len(pfis)
3
>>> ppts = proc.points()
>>> len(ppts)
40
>>> ppts.intersect_size(pfis)
3
intersects_procedure(p)

Check: does a point_set contain any points from the specified procedure ?

Parameters:p (procedure) – The procedure of interest.
Return type:bool
Returns:True if the point_set contains any points from p, False otherwise.
Raises:result.ERROR_SDG_NOT_PRESENT if no project is loaded. 
>>> barfn = next(p for p in project.current().procedures() if p.name()=='bar')
>>> entryset = point_set([barfn.entry_point()])
>>> entryset.intersects_procedure(barfn)
True
>>> foofn = next(p for p in project.current().procedures() if p.name()=='foo')
>>> entryset.intersects_procedure(foofn)
False
kind()

Get the kind of a set.

Return type:set_kind
Returns:The set kind ( set_kind ).
Raises:result.ELEMENT_NOT_PRESENT if the set was constructed with the default constructor and no elements have been added yet. 
>>> v0 = point_set(set_kind.TREE)
>>> v0.kind()
<cs.set_kind tree>
procedures()

Get the procedures that contain one or more points in a point_set .

Return type:[procedure]
Returns:A list containing all procedures ( procedure ) that contain one or more of the points ( point ) in the point_set .
Raises:result.ERROR_SDG_NOT_PRESENT if no project is loaded. 
>>> barfn = next(p for p in project.current().procedures() if p.name()=='bar')
>>> myset = point_set([barfn.entry_point(), barfn.exit_point()])
>>> myset.procedures()
(<cs.procedure bar>,)
remove(v)

Remove an element from the set.

Parameters:v (point) – The element to remove.
Return type:NoneType
Raises:KeyError
  • Side effects: Modifies self.
>>> barfn = next(p for p in project.current().procedures() if p.name()=='bar')
>>> myset = point_set([barfn.entry_point(), barfn.exit_point()])
>>> myset
<cs.point_set {<cs.point [entry] bar(int, void *, int)>, <cs.point [exit] bar(int, void *, int)>}>
>>> myset.remove(barfn.entry_point())
>>> myset
<cs.point_set {<cs.point [exit] bar(int, void *, int)>}>
>>> myset.remove(barfn.entry_point())
Traceback (most recent call last):
File "<console>", line 1, in <module>
File "C:\Program Files\CodeSecure\CodeSonar/codesonar/src/api/python\cs.py", line 6790, in remove
raise KeyError(v)
KeyError: <cs.point [entry] bar(int, void *, int)>
sort()

Get a sorted list of the points in a point_set .

Return type:[point]
Returns:A list containing all points ( point ) in the point_set , sorted first by the alphabetical order of the file in which they occur, secondly by the position of the text they represent in the source file, and thirdly by the vertex kind.
Raises:result.ERROR_SDG_NOT_PRESENT if no project is loaded. 
>>> barfn = next(p for p in project.current().procedures() if p.name()=='bar')
>>> myset = point_set([barfn.entry_point(), barfn.exit_point()])
>>> myset
<cs.point_set {<cs.point [entry] bar(int, void *, int)>, <cs.point [exit] bar(int, void *, int)>}>
>>> myset.sort()
(<cs.point [entry] bar(int, void *, int)>, <cs.point [exit] bar(int, void *, int)>)
sort(file_name)

Get a sorted list of the points in a point_set , listing points from the specified file first.

Parameters:file_name (str) – The name of a file. Points from this file will appear before any other points in the sorted list. If file_name is an empty string, behavior is the same as for point_set.sort().
Return type:[point]
Returns:A list containing all points ( point ) in the point_set , sorted first by file - with points in the file named file_name first, and thereafter by file name in alphabetical order, secondly by the position of the text they represent in the source file, and thirdly by the vertex kind.
Raises:result.ERROR_SDG_NOT_PRESENT if no project is loaded. 
>>> barfn = next(p for p in project.current().procedures() if p.name()=='bar')
>>> myset = point_set([barfn.entry_point(), barfn.exit_point()])
>>> myset
<cs.point_set {<cs.point [entry] bar(int, void *, int)>, <cs.point [exit] bar(int, void *, int)>}>
>>> myset.sort('apitest.cpp')
(<cs.point [entry] bar(int, void *, int)>, <cs.point [exit] bar(int, void *, int)>)
to_int_pair_set_in_sfileinst(u)

Get the character positions in a specified source file instance of all points in a point_set .

Parameters:u (sfileinst) – The source file instance ( sfileinst ) of interest.
Return type:int_pair_set
Returns:A new int_pair_set representing the character positions in source file instance u of the points in the point_set . 
>>> sf = next(s for s in project.current().sfiles() if s.name().endswith('apitest.cpp'))
>>> sfi = sf.arbitrary_instance()
>>> barfn = next(p for p in project.current().procedures() if p.name()=='bar')
>>> barouts = barfn.formal_outs()
>>> barouts.to_int_pair_set_in_sfileinst(sfi)
<cs.int_pair_set {(120, 3), (145, 0)}>
to_vector()

Get a list of all the elements in the set.

Return type:[point]
Returns:A list containing all the elements in the set. 
>>> barfn = next(p for p in project.current().procedures() if p.name()=='bar')
>>> myset = point_set([barfn.entry_point(), barfn.exit_point()])
>>> myset.to_vector()
(<cs.point [entry] bar(int, void *, int)>, <cs.point [exit] bar(int, void *, int)>)
union(b)

Set union.

Parameters:b (point_set) – The other operand for the union operation.
Return type:point_set
Returns:A set containing self UNION b.

The returned set contains the elements that are in self, b, or both.

>>> barfn = next(p for p in project.current().procedures() if p.name()=='bar')
>>> entryset = point_set([barfn.entry_point()])
>>> entryset
<cs.point_set {<cs.point [entry] bar(int, void *, int)>}>
>>> exitset = point_set([barfn.exit_point()])
>>> exitset
<cs.point_set {<cs.point [exit] bar(int, void *, int)>}>
>>> entryset.union(exitset)
<cs.point_set {<cs.point [entry] bar(int, void *, int)>, <cs.point [exit] bar(int, void *, int)>}>
union_p(b)

Update a set to the union of itself and another set.

Parameters:b (point_set) – The set whose elements are to be added.
Return type:NoneType
  • Side effects: Modifies self.

self is updated to contain self UNION b.

>>> barfn = next(p for p in project.current().procedures() if p.name()=='bar')
>>> entryset = point_set([barfn.entry_point()])
>>> entryset
<cs.point_set {<cs.point [entry] bar(int, void *, int)>}>
>>> entryset.union_p(point_set([barfn.exit_point()]))
>>> entryset
<cs.point_set {<cs.point [entry] bar(int, void *, int)>, <cs.point [exit] bar(int, void *, int)>}>