Color set functions

A number of functions are predefined for some or all color sets. In the following, we assume that the color set cs has been declared.

If cs is a timed color set, then the functions below can be used for the untimed version of the color set. Functions for the timed version of the color set are described on the help page for Timed color set functions.

Declare clause

Please read about the Declare clause if one or more of the following is true:

  • The version of CPN Tools that you are using is 0.1.53 or below
  • You have declared product color sets that are cartesian products of 10 or more sets
  • You have declared record color sets with 10 or more identifiers.

Equality Operators

The equality operators = and <> are defined for all colour sets, while <, >, <= and >= are only defined for integer color sets and string color sets. To test the order of the elements in other color sets, use the lt function, which is described below.

Operations for all color sets

cs.lt(c1,c2)
less than in the color set ordering
cs.legal(v)
test whether value v is a member of the color set cs. v must be a member of either the color set cs, an alias color set for cs or a superset color set of cs.
cs.mkstr( c)
make string representation of a color
cs.mkstr_ms(ms)
make string representation of a multi-set

Examples of legal expressions

INT.lt(3,5) evaluates to true

Weekend.legal(Mon) evaluates to false

Answer.mkstr(no) evaluates to “no”

INT.mkstr_ms(1`3++2`7++4`3) evaluates to “5`3++2`7”

Examples of illegal expressions

INT.lt(3,true)

INT.legal(3.1415)

Input/Output Operations

cs.input(s)
read a color from input stream s
cs.input_ms(s)
read a multi-set from input stream s
cs.output(s,c)
write color c to output stream s
cs.output_ms(s,ms)
write multi-set ms to output stream s

Examples of use

val fid = TextIO.openOut(”/tmp/outputfile.txt”);

INT.output_ms(fid,1`3++2`7);

TextIO.closeOut(fid);

For additional details about opening and closing text files see the TextIO structure in the SML Basis Library Manual.

Operations for small color sets

The following functions can be used for all small color sets.

cs.all()
multi-set with one of each element in the colour set
cs.ran()
returns a random colour
cs.size()
number of elements in the colour set
cs.ord©
convert colour to number representing its position in the colour set, where positions are numbered from 0 to cs.size()-1
cs.col(i)
convert position number to colour

These functions also exist for large color sets. However, an exception will raised when these functions are invoked for large color sets.

Examples of useful expressions

Day.size() evaluates to 7

Day.col(0) evaluates to Mon

SmallInt.ran() returns an integer between 1 and 10

Examples of expressions resulting in exceptions

INT.ran()

String.size()

Functions for union color sets

The of_ functions are only available for union color sets

cs.of_idi(v) tests whether value v belongs to the component idi

Examples of use

Packet.of_DATA(DATA(“abc”)) returns true

Packet.of_DATA(DATA(“abc123”)) returns false

Packet.of_DATA(ACK) returns false

Functions for product and record color sets

The following functions are only available for product color sets and record color sets.

cs.set_idi c v changes component idi in color c to value v while leaving all other components unchanged.

cs.mult(ms1, ms2, …,msn) returns product of multi-sets, where for i=1..n, msi is a multi-set of values from color set namei as determined by the declaration for cs.

For product color sets idi must be a value between 1 and n, where n is the number of components in the product. For record color sets idi must be one of the labels defined in the declaration of the color set.

Examples of use

colset P = product INT * STRING;
colset R = record i:INT * s:STRING;

P.set_1 (5, “abc”) 3 evaluates to (3, “abc”)

R.set_s {s=“abc”, i=5} “def” evaluates to {i=5, s=“def”}

P.mult(1`2++1`3, 1`”abc”++1`”def”) evaluates to 1`(2,”abc”)++1`(2,”def”)++1`(3,”abc”)++1`(3,”def”)

The mult function is used in the example CP-net for the Distributed database example.