Domain variable and Basic functions

A CSint is an integer domain variable. Only pointers to CSint (CSint*) are used in the pre-defined iZ functions.

Constructors

CSint variables can be constructed by these following functions:

CSint *cs_createCSint(int min, int max): Creates a CSint variable whose domain is { min .. max }.

CSint *cs_createNamedCSint(int min, int max, char *name): Creates a CSint variable whose domain is { min .. max }, and associates a name to it. (It is equivalent to cs_createCSint() followed by cs_setName().)

CSint *CSINT(int n): Creates an already instantiated (i.e. its domain is reduced to one element) CSint variable. This function is equivalent to cs_createCSint(n, n).

CSint *cs_createCSintFromDomain(int *array, int size): Creates a CSint variable its domain is defined by the array (of size integers).

CSint **cs_createCSintArray(int nbVars, int min, int max)

Creates an array of nbVars CSint variables, which all have the same { min .. max } domain.

<note>This function returns pointer to array of CSint pointers. Don’t call free() for this array because array is managed by iZ-C.

Functions to Access Domain Variable

Following basic functions give access to CSint (a domain variable):

int cs_getMin(CSint *vint): Returns the minimum value of the domain of vint.

int cs_getMax(CSint *vint): Returns the maximum value of the domain of vint.

int cs_getNbElements(CSint *vint): Returns the number of elements in the domain of vint.

int cs_getNbConstraints(CSint *vint): Returns the number of constraints vint is involved in. (Constraints which failed when setting are not included.)

char *cs_getName(CSint *vint): Returns the name of vint (which has been set using cs_setName()). The name of a CSint variable can also be displayed by using the “%T” format conversion string of the cs_printf() or cs_fprintf() functions.

int cs_getNextValue(CSint *vint, int val)

Returns the first element in the domain of vint which is strictly greater than val. If val is greater than cs_getMax(vint), then it returns INT_MAX (the maximum value of an int).

In the following code, cs_getNextValue() is used as an expression of a ‘for’ statement:

void display(CSint *vint)
{
  int val;
  for (val = cs_getMin(vint); val <= cs_getMax(vint); val = cs_getNextValue(vint, val))
      printf("%d ", val);
}

The display() function defined above will print on the stdout file all the possible values of a CSint variable (i.e. its domain) in increasing order.

int cs_getPreviousValue(CSint *vint, int val): Returns the first element in the domain of vint which is strictly lower than val. If val is lower than cs_getMin(vint), then it returns INT_MIN (the minimum value of an int).

int *cs_getDomain(CSint *vint): Returns an array of cs_getNbElements( vint ) elements whose values are the elements of the domain of vint. (Returned array should be ‘free’ed by user)

void cs_freeDomain(int *array): Free array allocated by cs_getDomain().

IZBOOL cs_isIn(CSint *vint, int val): Returns TRUE if val is an element of the domain of vint. Otherwise it returns FALSE.

void cs_setName(CSint *vint, char *name): Associate a name to a CSint variable vint. When the vint will be displayed (using cs_printf() or cs_fprintf()), its associated name can also be displayed (if the format “%T” is specified).

IZBOOL cs_isFree(CSint *vint): Returns TRUE if vint is not yet instantiated (i.e. cs_getNbElements( vint ) > 1, i.e. cs_getMin( vint ) < cs_getMax( vint )). Otherwise returns FALSE.

IZBOOL cs_isInstantiated(CSint *vint): Returns TRUE if vint is instantiated (i.e. cs_getNbElements( vint ) == 1, i.e. cs_getMin( vint ) == cs_getMax( vint )). Otherwise returns FALSE.

int cs_getValue(CSint *vint): Returns the value of vint in case vint has been instantiated. An error occurs (i.e. a call to cs_getErr() returns CS_ERR_GETVALUE) if vint has not been instantiated yet, and cs_getValue( vint ) returns cs_getMin( vint ).

void cs_printf(const char *control, ...)

Is similar to the standard printf() C function except that three new conversion characters dedicated to CSint variables and CSint variable arrays has been added:

cs_printf("%T", vint) prints the name of vint (if it has one) followed by its domain.
cs_printf("%D", vint) prints only the domain of vint on the standard output file, stdout.
cs_printf("%A", array, size) prints the array of CSint variables (with their name, if any) array, of size elements, separated by a comma.

void cs_fprintf(FILE *f, const char *control, ...): It is similar to cs_printf() except that it takes a pointer to FILE as an argument, and writes to the indicated file when the function is invoked.

Constraints for Domain

Following functions are constraints, and may fail (i.e. return a FALSE value) when posted:

IZBOOL cs_InArray(CSint *vint, int *array, int size): Constrains the domain of CSint variable vint to be the domain contained in the array .

IZBOOL cs_NotInArray(CSint *vint, int *array, int size)

Constrains the CSint variable vint not to have the values in the array . All the values of the domain of vint that are in array are removed.

It could be defined as:

IZBOOL cs_notInArray(CSint *vint, int *array, int size) {
  int i;
  for (i = 0; i < size; i++)
   if (!cs_NEQ(vint, array[i])
     return FALSE;

  return TRUE;
}

IZBOOL cs_InInterval(CSint *vint, int min, int max)

Constrains the CSint variable vint to be { min .. max } (i.e. cs_getMin(vint) >= min and cs_getMax(vint) <= max).

It could be defined as:

IZBOOL cs_InInterval(CSint *vint, int min, int max) {
  return(cs_GE(vint, min) && cs_LE(vint, max));
}

IZBOOL cs_NotInInterval(CSint *vint, int min, int max)

Constrains the CSint variable vint not to have the values in { min .. max }. All the values of the domain of vint that are in {min..max} are removed.

It could be defined as:

IZBOOL cs_NotInInterval(CSint *vint, int min, int max) {
  int i;
  for (i = min; i <= max; i++)
    if (!cs_NEQ(vint, i))
      return FALSE;

  return TRUE;
}