Enumerations as PropertyObjects

TestStand 2019 Help

Edition Date: May 2019

Part Number: 370052AA-01

»View Product Info
Download Help (Windows Only)

TestStand enumerations are PropertyObjects just like other TestStand data types. As such, you can invoke PropertyObject methods and properties on enumerations. In most cases, the extension of existing methods to TestStand enumerations is obvious, but cases specifically related to type or value require further explanation.

<Enumeration.Type.ValueType> — Returns PropValType_Enum.

<Enumeration>.SetValString() — SetValString() fails with a type mismatch error unless you pass PropOption_CoerceToEnum. With the PropOption_CoerceToEnum option, SetValString() attempts to set the enumeration instance to the enumerator matching the string value passed. If the string value matches one of the enumerators, the call succeeds and both the enumerator and numeric values of the enumeration instance are updated. For flags enumerations, the string can be any combination of enumerators combined with bitwise OR, including the empty string. Passing a string that does not correspond to the enumerators results in a runtime error.

<Enumeration>.GetValString() — GetValString() fails with a type mismatch error unless you pass PropOption_CoerceFromEnum. With the PropOption_CoerceFromEnum option, GetValString() returns a string representation of the enumeration. If the enumeration instance has enumerator information, the enumerator name is returned. For flags, this may be multiple enumerators combined with bitwise OR.

If the enumeration instance has no enumerator information (i.e. because it is loose and set to a value that does not correspond to its enumerators), the behavior depends on the options you pass. If you pass PropOption_CoerceFromNumber, the numeric value is converted to a string and returned. For flags enumerations, this may be a combination of enumerators combined with bitwise OR along with whatever number is left over. If you do not pass PropOption_CoerceFromNumber, GetValString() returns an empty string. Generally, PropOption_CoerceFromNumber is appropriate when the purpose of the string is for display. PropOption_CoerceFromNumber is not usually appropriate for data persistence applications.

Calling GetValString() on an invalid enumeration results in a runtime error.

Note Note  PropOption_Coerce includes both PropOption_CoerceFromEnum and PropOption_CoerceFromNumber.
Property Options(s) Enum State Result
None Any Runtime error
CoerceFromEnum Has enumerator info Enumerator(s) represented as string.
CoerceFromEnum No enumerator info Empty string.
CoerceFromEnum | CoerceFromNumber Has enumerator info Enumerator(s) represented as string.
CoerceFromEnum | CoerceFromNumber No enumerator info Numeric value converted to a string. For flags enumerations, could be some combination of enumerators combined with the OR operator with left-over number.
Any Invalid Runtime error

<Enumeration>.SetValNumber() — SetValNumber() fails with a type mismatch error unless you pass PropOption_CoerceToEnum. With the PropOption_CoerceToEnum option, SetValNumber() attempts to set the enumeration instance to the specified value. If the number matches one of the enumerators, the call succeeds. For flags enumerations, the number can correspond to any combination of enumerators combined with a bitwise OR, including 0, which indicates no enumerators. The enumerator info is cleared unless the CoerceToString option is passed. If CoerceToString is passed, the enumerator information will be updated to match the numeric value. If there are multiple enumerators or combinations of flags that can represent the specified numeric value, a valid combination is chosen arbitrarily.

If the number does not correspond to the enumerators, the behavior depends on whether the enumeration is strict or loose. If the enumeration is loose, the number is updated to the specified value and the enumeration information is cleared. If the enumeration is strict, SetValNumber() fails with a runtime error.

Property Options(s) Strict/Loose Number In Range Behavior
None Any Any Runtime error
CoerceToEnum Any In Range Numeric value set. Enumerator information cleared.
CoerceToEnum | CoerceToString Any In Range Numeric value set. TestStand engine sets enumerator(s) matching specified value. If ambiguous, choice is arbitrary.
CoerceToEnum Strict Out of Range Runtime error. (CoerceToString has no effect.)
CoerceToEnum Loose Out of Range Numeric value set. Enumerator information cleared. (CoerceToString has no effect.)
SetValInteger64() and SetValUnsignedInteger64() work similarly to SetValNumber() for enumerations with the associated representations. As with TestStand numbers, passing PropOption_CoerceToNumber coerces the numeric representation if necessary.

<Enumeration>.GetValNumber() — GetValNumber() fails with a type mismatch error unless you pass PropOption_CoerceFromEnum. With the PropOption_CoerceFromEnum option, GetValNumber() returns the numeric value of the enumeration. Calling GetValNumber() on an invalid enumeration results in a runtime error.

GetValInteger64() and GetValUnsignedInteger64() work similarly for enumerations with the associated representations. As with TestStand numbers, passing PropOption_CoerceFromNumber coerces the numeric representation if necessary.

WAS THIS ARTICLE HELPFUL?

Not Helpful