Studio:Working with Enumerated Types

STRIDE AutoScript supports working with enumerated types symbolically or numerically, in a manner similar to the C language. AutoScript also supports assigning and retrieving values outside the numeric range of the enumeration. The following rules apply:

• In-range assignments may use either numeric or symbolic (string) values (Example 1)
• Out-of-range assignments must use numeric values (Example 2)
• In-range values are always retrieved as symbolic values (Example 1)
• Out-of-range values are always retrieved as numeric values (Example 2)
• Most scripting languages provide simple ways to test to determine if a value is a number or a string, allowing scripts to easily
  determine if a value is in-range or out-of-range (Example 3).

You can also display and enter values in STRIDE Studio.

Note: This article applies to both enumerated types and types to which the scl_values() #pragma has been applied.

Sample Header File

The following header file is used for Examples 1 – 3:

typedef enum
{
   ZERO,
   ONE,
   TWO,
} eVals;

void f(eVals val);
#pragma scl_function(f)

Example 1: Assigning and retrieving in-range values

JScript

// In-range assignment can be made by symbolic name or numeric value
// and the result is the same

var f = ascript.Functions.Item("f").User;
f.ParameterList.val = "ONE";    // Symbolic assignment
ascript.MessageBox("Symbolic Assignment Result: " + f.ParameterList.val);

f.ParameterList.val = 1;        // Numeric assignment

// Notice that the value is a string even though it was set numerically
ascript.MessageBox("Numeric Assignment Result: " + f.ParameterList.val);

Perl

# In-range assignment can be made by symbolic name
# or numeric value and the result is the same. 

use strict;
use Win32::OLE;
use Win32::OLE::Variant;
Win32::OLE->Option(Warn => 3);

my $f = $main::ascript->Functions->Item("f")->User;

$f->ParameterList->{val} = "ONE";    # Symbolic Assignment
$main::ascript->MessageBox("Symbolic Assignment Result: ".$f->ParameterList->val); 

$f->ParameterList->{val} = 1;        # Numeric Assignment

# Notice that the value is a string even though it was
# set numerically. 
$main::ascript->MessageBox("Numeric Assignment Result: ".$f->ParameterList->val);

Example 2: Assigning and retrieving out-of-range values

JScript

// Out-of-range assignment must use numeric values; there is
// no symbolic value. When retrieved the value is numeric,
// not string.
var f = ascript.Functions.Item("f").User;
f.ParameterList.val = -44;   

// out of range numeric assignment
// Notice that the value is -44, a number
ascript.MessageBox("Out of Range Assignment Result: " +  f.ParameterList.val);

Perl

# Out-of-range assignment must use numeric values; there is
# no symbolic value 
use strict;
use Win32::OLE;
use Win32::OLE::Variant;
Win32::OLE->Option(Warn => 3);

my $f = $main::ascript->Functions->Item("f")->User;

$f->ParameterList->{val} = -44;    # Out of range numeric assignment

# Notice that the extracted value is -44, a number
$main::ascript->MessageBox("Symbolic Assignment Result: ".
                            $f->ParameterList->val);

Example 3: Creating the isEnumOutOfRange() function

JScript

var f = ascript.Functions.Item("f").User;
for (var i = -1; i <= 3; i++)
{
   // set enum by value
   f.ParameterList.val = i;

   // read the enum; if it's in range the enumerator name is returned; if
   // it's out of range, the number value is returned instead

   var e = f.ParameterList.val;
   ascript.MessageBox(e + "  OutOfRange: " + isEnumOutOfRange(e));
}

// returns true if enum is out of range (is a number),
// returns false if enum is in range (is a string)

function isEnumOutOfRange(eVal)
{
   return (Number(eVal) == eVal)
}

Perl

use strict;
use Win32::OLE;
use Win32::OLE::Variant;
Win32::OLE->Option(Warn => 3);
my $f = $main::ascript->Functions->Item("f")->User;

for (my $i = -1; $i <= 3; $i++)
{
   # set the enum value. If the value is in-range it can be set using the
   # enumerator name (e.g. "ZERO"), but here we set all values using numbers

   $f->ParameterList->{val} = $i;

   # read the enum; if it's in range the enumerator name is returned; if
   # it's out of range, the number value is returned instead

   my $e = $f->ParameterList->val;
   $main::ascript->MessageBox($e."  OutOfRange: ".isEnumOutOfRange($e));
}

# returns 1 if enum is out of range (is a number),
# returns 0 if enum is in range (is a string)
sub isEnumOutOfRange()
{
   my $enum = shift;
   # here we determine lexically if the value passed in is a number or not
   if ($enum != /-?\d+/)
   {
      return 1;
   }
   return 0;
}

Displaying and entering values in STRIDE Studio

If you open an interface via the Interfaces pane in STRIDE Studio, its enum values are displayed. Enum values may be typed in or selected from the dropdown list. If, for example, you want to test an out-of-range value such as -1, type it in the Item field.