This function can be used to define simple constraints that are not predefined in CP Optimizer. (For similar functionality to use in an IBM® ILOG® Concert Technology model, see IloAllowedAssignments and IloForbiddenAssignments.) This function creates and returns a constraint. That constraint is defined for all the constrained variables in the array vars or for the single constrained variable y.

This kind of constraint is sometimes known as an element constraint.

The semantics of that generic constraint can be indicated in either one of several ways:

• by a predicate; in that case, the argument predicate, of course, indicates that predicate;
• by the values that satisfy the constraint; in that case, the argument set indicates the combinations of values that satisfy the constraint, and the argument compatible must be IlcTrue;
• by the values that do not satisfy the constraint; in that case, the argument set indicates the unsatisfactory combinations of values, and the argument compatible must be IlcFalse;
• by making the constrained variable y equal to the element of the array a at the index indicated by x. In other words, y=a[x];

The order of the constrained variables in the array vars is important because the same order is respected in the predicate or the set. That is, IlcTableConstraint passes an array of values to the member function isTrue for a predicate or to the member function isIn for a set, where the first such value is a value of vars[0], the second is a value of vars[1], and in general, the ith value is a value of the constrained variable vars[i].

This function will throw an exception (an instance of IloException) if any of the following conditions occur:

• the function is called with a predicate as an argument but the size of the array of constrained variables is greater than three;
• the size of vars is different from the size of the set.

This function reduces domains efficiently, but it may take some time to do so. The time it needs for domain reduction depends on the size of the domains of the constrained variables in vars.

Examples:

The following code defines a constraint of arity four such that only these combinations of values are allowed: (0, 1, 1, 2), (1, 0, 2, 3), and (0, 0, 2, 1).

 IlcIntTupleSet set(cp,4);
 set.add(IlcIntArray(cp,4,0,1,1,2));
 set.add(IlcIntArray(cp,4,1,0,2,3));
 set.add(IlcIntArray(cp,4,0,0,2,1));
 set.close();

 IlcIntVar x(cp,0,1),y(cp,0,1),z(cp,0,3),t(cp,0,2);
 IlcIntVarArray vars(cp,4,x,y,z,t);
 

Inside a goal or constraint now, you can post that constraint by adding it to an instance of IloCPEngine, like this:

 cp.add(IlcTableConstraint(vars,set,IlcTrue));

The following code defines a constraint of arity three. It uses a predicate that is true if the three variables are pairwise different or the sum of the first two constrained variables is equal to the third variable.

 IlcBool IlcIntPredicateI::isTrue(IlcIntArray val) {
    return((val[0] != val[1] && val[1] != val[2] && val[0] != val[2])
                || (val[0] + val[1] == val[2]));
 }

 IlcIntVar x(cp, 0, 3), y(cp, 0, 3), z(cp, 0, 3);
 IlcIntVarArray vars(cp, 3, x, y, z);
 

Inside a goal or constraint now, you can post this constraint by adding it to an instance of IloCPEngine, like this:

 cp.add(IlcTableConstraint(vars, Predicate(cp));