Supported Operations on Sequences and Sets in Python API for Polyspace

R2026b

Several properties in the Python® API for Polyspace® are collections that behave like Python sequences or sets.

  • A sequence is an ordered collection of elements that you can access by position (index). Sequences maintain the order in which you add elements and allow duplicate values. In the Python API for Polyspace, an example of a sequence is the Defines property of a polyspace.project.OwnedBuildConfiguration object (a list of macro definitions).

  • A set is an unordered collection of unique elements. Sets do not allow duplicates and do not preserve insertion order, but they provide efficient membership testing and set-theoretic operations such as union and intersection. In the Python API for Polyspace, an example of a set is the ProfilingOptions.FunToIgnore sub-property of a polyspace.project.OwnedTestConfiguration object (a set of functions to exclude from profiling).

Supported Operations on Sequences

A sequence type supports three tiers of operations depending on whether the type is immutable, assignable, or resizable.

The following tables illustrate these operations using buildConf.Defines as an example, where buildConf is an active build configuration obtained from a project:

proj = polyspace.project.Project("myProject")
buildConf = proj.ActiveBuildConfiguration
defines = buildConf.Defines

Read-Only Operations

All sequence types support the following read-only operations.

OperationExample
Iteration 
for d in defines:
    print(d)
Membership test 
if "NDEBUG" in defines:
    print("Found")
if "NDEBUG" not in defines:
    print("Not found")
Length 
n = len(defines)
Index access (integer or slice)
first = defines[0]
last = defines[-1]
subset = defines[1:3]
every_other = defines[0:4:2]

A slice uses the syntax [start:stop:step], where start is the first index (inclusive), stop is the last index (exclusive), and step is the stride between elements.

Find first occurrence
idx = defines.index("NDEBUG")
idx = defines.index("NDEBUG", 2)
idx = defines.index("NDEBUG", 2, 5)

Optional arguments restrict the search to elements between positions start (inclusive) and stop (exclusive).

Count occurrences 
n = defines.count("NDEBUG")
Copy to list 
my_list = defines.copy()
Concatenation 
combined = defines + ["EXTRA_DEFINE"]
Minimum and maximum
smallest = min(defines)
largest = max(defines)

Strings are ordered lexicographically.

Reverse 
for d in reversed(defines):
    print(d)

Assign Operations

In addition to the read-only operations, assignable sequences also support the following operations.

OperationExample
Item or slice assignment
defines[0] = "NEW_MACRO=1"
defines[1:3] = ["A=1", "B=2"]
defines[::2] = ["X=1", "Y=2"]

A slice assignment replaces the elements selected by [start:stop:step] with the values on the right-hand side.

In-place reverse 
defines.reverse()

Resize Operations

In addition to the read-only and assign operations, resizable sequences also support the following operations that change the number of elements.

OperationExample
Remove and return element 
last = defines.pop()
first = defines.pop(0)
Delete slice
del defines[0:2]
del defines[::2]

Deletes the elements selected by [start:stop:step].

Append element 
defines.append("NDEBUG")
Extend from another sequence or list 
defines.extend(["MACRO_A=1", "MACRO_B=2"])
defines += ["MACRO_A=1", "MACRO_B=2"]
Insert at index 
defines.insert(0, "FIRST_MACRO")
Remove first matching element 
defines.remove("NDEBUG")
Clear all elements 
defines.clear()

Supported Operations on Sets

Set types support two tiers of operations depending on whether they are immutable or mutable.

The following tables illustrate these operations using ignoredFuns as an example, where ignoredFuns is a set of function names to exclude from profiling:

proj = polyspace.project.Project("myProject")
testConf = proj.ActiveTestConfiguration
ignoredFuns = testConf.ProfilingOptions.FunToIgnore

Read-Only Operations

All set types support the following read-only operations.

OperationExample
Iteration 
for name in ignoredFuns:
    print(name)
Length 
n = len(ignoredFuns)
Membership test 
if "main" in ignoredFuns:
    print("main is excluded from profiling")
Disjoint test 
if ignoredFuns.isdisjoint({"calculate", "process"}):
    print("The calculate and process functions are not ignored.")
Subset test 
if ignoredFuns.issubset({"main", "init", "cleanup"}):
    print("All ignored functions are in the expected set")

if ignoredFuns <= {"main", "init", "cleanup"}:
    print("All ignored functions are in the expected set")

if ignoredFuns < {"main", "init", "cleanup"}:   # Proper subset
    print("All ignored functions are in the expected set")
    print("At least one function in the expected set is not ignored")
Superset test 
if ignoredFuns.issuperset({"main", "init"}):
    print("main and init are both excluded")

if ignoredFuns >= {"main", "init"}:
    print("main and init are both excluded")

if ignoredFuns > {"main", "init"}:   # Proper superset
    print("main and init are both excluded")
    print("Some additional functions are also excluded")
Union 
combined = ignoredFuns.union({"legacy_init", "legacy_cleanup"})
combined = ignoredFuns | {"legacy_init", "legacy_cleanup"}
Intersection 
common = ignoredFuns.intersection({"main", "init", "calculate"})
common = ignoredFuns & {"main", "init", "calculate"}
Difference 
unique = ignoredFuns.difference({"main"})
unique = ignoredFuns - {"main"}
Symmetric difference 
in_one_but_not_both = ignoredFuns.symmetric_difference({"main", "process"})
in_one_but_not_both = ignoredFuns ^ {"main", "process"}
Copy 
backup = ignoredFuns.copy()

Mutation Operations

In addition to the read-only operations, mutable sets also support the following operations that modify the set contents.

OperationExample
Update (union in place) 
ignoredFuns.update({"main", "process"})
ignoredFuns |= {"main", "process"}
Intersection in place 
ignoredFuns.intersection_update({"main", "process"})
ignoredFuns &= {"main", "process"}
Difference in place 
ignoredFuns.difference_update({"main", "process"})
ignoredFuns -= {"main", "process"}
Symmetric difference in place 
ignoredFuns.symmetric_difference_update({"main", "process"})
ignoredFuns ^= {"main", "process"}
Add element 
ignoredFuns.add("main")
Remove element (raises error if missing) 
ignoredFuns.remove("main")
Discard element (no error if missing) 
ignoredFuns.discard("main")
Clear all elements 
ignoredFuns.clear()

See Also

Topics