Colour set functions
Description of predefined functions for colour sets CPN ML


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

Declare clause

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

Equality Operators

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

Operations for All Colour Sets

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

Examples of Use

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"
Illegal expressions
INT.lt(3,true)
INT.legal(3.1415)

Input/Output Operations

cs.input(s) read a colour from input stream s
cs.input_ms(s) read a multi-set from input stream s
cs.output(s,c) write colour 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 Colour Sets

The following functions can be used for all small colour 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(c) 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 colour sets. However, an exception will raised when these functions are invoked for large colour sets.

Examples of Use

Useful expressions
Day.size() evaluates to 7
Day.col(0) evaluates to Mon
SmallInt.ran() returns an integer between 1 and 10
Expressions resulting in exceptions
INT.ran()
String.size()

Functions for Union Colour Sets

The of_ functions are only available for union colour 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 Colour Sets

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

cs.set_idi c v changes component idi in colour 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 colour set namei as determined by the declaration for cs.

For product colour sets idi must be a value between 1 and n, where n is the number of components in the product. For record colour sets idi must be one of the labels defined in the declaration of the colour 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.