Contents

• class compunit_metricclass
  • compunit_metricclass Members
  • compunit_metricclass Details

class compunit_metricclass

A compunit granularity metric class.

The compunit granularity metric classes are managed by compunit_metricclass_manager .

• For a manually computed metric, your plug-in should:

• Create a new metric class with compunit_metricclass_manager.create().
• Compute values for the metric.
• As values are computed, report them to the hub with compunit_metricclass.report().
• If necessary, retract metric values with with compunit_metricclass.retract().

• If you want CodeSonar to compute and report metric values automatically, use a metric function decorator.

You can retrieve metric values with compunit_metricclass.value(), and examine metric properties with compunit_metricclass.description(), compunit_metricclass.tag(), and compunit_metricclass.flags().

For more information about metrics in CodeSonar, see the Metrics manual page.

compunit_metricclass Members

Constructors	none
Methods	__cmp__(), __eq__(), __ge__(), __gt__(), __hash__(), __le__(), __lt__(), __ne__(), __repr__(), __str__(), allowed(), always_discarded(), description(), flags(), report(), retract(), tag(), value()

compunit_metricclass Details

class cs.compunit_metricclass

A compunit granularity metric class.

__cmp__(other)

Comparison function for compunit_metricclass , with respect to a stable overall ordering.

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

• N<0 if self < other
• N==0 if self == other
• N>0 if self > other

self and other will only compare equal if they are the same compunit_metricclass object.

>>> v0 = compunit_metricclass_manager.metricclasses()
>>> v1 = next(v0) # will only succeed if you have created one or more such classes
>>> v1.__cmp__(v1)
0

__eq__(b)

Equality operator for compunit_metricclass .

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

>>> v0 = compunit_metricclass_manager.create('foo', 'foo')
>>> v1 = compunit_metricclass_manager.metricclasses()
>>> v2 = next(v1)
>>> v2 == v0
False

__ge__(b)

Greater-than-or-equal operator for compunit_metricclass .

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

>>> v0 = compunit_metricclass_manager.metricclasses()
>>> v1 = next(v0)
>>> v1 >= v1
True

__gt__(b)

Greater-than operator for compunit_metricclass .

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

>>> v0 = compunit_metricclass_manager.metricclasses()
>>> v1 = next(v0)
>>> v1 > v1
False

__hash__()

Get a hash value for this compunit_metricclass .

Return type:int

>>> v0 = compunit_metricclass_manager.metricclasses()
>>> v1 = next(v0)
>>> hash(v1)
3972540216

__le__(b)

Less-than-or-equal operator for compunit_metricclass .

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

>>> v0 = compunit_metricclass_manager.create('foo', 'foo')
>>> v1 = compunit_metricclass_manager.metricclasses()
>>> v2 = next(v1)
>>> v0 <= v2
False

__lt__(b)

Less-than operator for compunit_metricclass .

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

>>> v0 = compunit_metricclass_manager.create('foo', 'foo')
>>> v1 = compunit_metricclass_manager.metricclasses()
>>> v2 = next(v1)
>>> v0 < v2
False

__ne__(b)

Inequality operator for compunit_metricclass .

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

>>> v0 = compunit_metricclass_manager.create('foo', 'foo')
>>> v1 = compunit_metricclass_manager.metricclasses()
>>> v2 = next(v1)
>>> v2 != v0
True

__repr__()

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

Return type:str Returns:The string representation.

>>> v0 = compunit_metricclass_manager.metricclasses()
>>> v1 = next(v0)
>>> repr(v1)
'<cs.metricclass fnlen_func>'

__str__()

Get a simple string representation of a compunit_metricclass object.

Return type:str Returns:The string representation.

>>> v0 = compunit_metricclass_manager.metricclasses()
>>> v1 = next(v0)
>>> str(v1)
'fnlen_func'

allowed()

Check: are METRIC_FILTER settings such that reported instances of this metric class will be submitted to the hub?

Return type:bool Returns:True if reported instances of the class will be submitted to the hub, False otherwise.

If you have defined a custom metric class C in a plug-in, you can use a test based on C.allowed() to avoid unnecessary work in the case where C is ignored.

This is the complement of compunit_metricclass.always_discarded().

>>> v0 = compunit_metricclass_manager.metricclasses()
>>> v1 = v0.__next__()
>>> v1.allowed()
True

always_discarded()

Check: are METRIC_FILTER settings such that instances of this metric class will always be ignored?

Return type:bool Returns:True if all instances of the class are being discarded, False otherwise.

If you have defined a custom metric class C in a plug-in, you can use a test based on C.always_discarded() to avoid unnecessary work in the case where C is ignored.

This is the complement of compunit_metricclass.allowed().

>>> v0 = compunit_metricclass_manager.metricclasses()
>>> v1 = v0.__next__()
>>> v1.always_discarded()
False

description()

Get the description (longer, human readable identifier) for a metric class ( compunit_metricclass ).

Return type:str Returns:The description, as a string.

For example, CodeSonar ships with built-in project granularity metric class Include file instances.

• its tag is “InclF”
• its description is “Include file instances”

>>> v0 = compunit_metricclass_manager.metricclasses()
>>> v1 = next(v0)
>>> v1.description()
'fnlen_func'

flags()

Get the metricclass_flags for a compunit_metricclass .

Return type:metricclass_flags Returns:The metricclass_flags .

>>> v0 = compunit_metricclass_manager.metricclasses()
>>> v1 = next(v0)
>>> v1.flags()
<cs.metricclass_flags auto>

report(elt, val)

Report a metric value to the hub.

Parameters:

• elt (compunit) – The element that the metric value is associated with.
• val (float) – The value to report.

Return type:

NoneType

Raises:

• result.ERROR_INVALID_PHASE_FOR_OPERATION if called during a traversal phase that is not consistent with the metricclass_flags for the compunit_metricclass. See the metricclass_flags.POST_ANALYSIS documentation for more information.
• result.FILTERED_OUT if the compunit_metricclass is filtered out by a METRIC_FILTER discard rule.
• result.GENERATED_COMPILATION if elt was generated in the back end.
• result.ERROR_INVALID_SLAVE_OPERATION if called from a CodeSonar slave process.

You do not need to call this method if the metric class was created with a metric function decorator. In that case, CodeSonar will automatically report the values calculated using the decorated function.

>>> v0 = project.current()
>>> v1 = v0.compunits_vector()
>>> v2 = compunit_metricclass_manager.create('new', '{<cs.symbol mymalloc(int)>, <cs.symbol i-12>}')
>>> v2.report(v1[1], 14.270499229431152)

retract(elt)

Retract a metric value.

Parameters:

elt (compunit) – The element for which the value will be retracted.

Return type:

Raises:

• result.ERROR_INVALID_PHASE_FOR_OPERATION if called outside the drop traversal phase.
• result.ELEMENT_NOT_PRESENT if retraction did not occur for any other reason.
• result.ERROR_INVALID_SLAVE_OPERATION if called from a CodeSonar slave process.

In typical usage, compunit_metricclass.retract() is called during the drop traversal (that is, by a drop visitor).

tag()

Get the tag (short string identifier) for a metric class ( compunit_metricclass ).

Return type:str Returns:The short tag, as a string.

The tag will usually be only a few characters long. Retrieve the metric class description with compunit_metricclass.description() for a longer string that is generally more human-readable.

For example, CodeSonar ships with built-in project granularity metric class Include file instances.

• its tag is “InclF”
• its description is “Include file instances”

>>> v0 = compunit_metricclass_manager.metricclasses()
>>> v1 = next(v0)
>>> v1.tag()
'fnlen_func'

value(elt)

Get the value of a metric.

Parameters:

elt (compunit) – The element for which the metric value is required.

Return type:

float

Returns:

The metric value for elt.

Raises:

• result.FILTERED_OUT if the compunit_metricclass is filtered out by a METRIC_FILTER discard rule.
• result.METRIC_NOT_COMPUTED if a value for the metric has not been computed. This can happen if the compunit_metricclass was not created with metricclass_flags.AUTO and a value has not been reported with compunit_metricclass.report(), or if the compunit_metricclass was not created with metricclass_flags.POST_ANALYSIS but compunit_metricclass.value() is called during the serial depth-first traversal or parallel-depth first traversal.

>>> v0 = compunit_metricclass_manager.metricclasses()
>>> v1 = project.current()
>>> v2 = next(v0)
>>> v3 = v1.compunits_vector()
>>> v2.value(v3[1])
62.0