1.2 The class OZ_Expect

## 1.2 The class `OZ_Expect`

The functionality provided by class `OZ_Expect` is intended to be used for implementing header functions.

### 1.2.1 Types

`OZ_expect_t` [data type]

  > > `struct OZ_expect_t {
  > > int size, accepted;
  > > OZ_expect_t(int s, int a) : size(s), accepted(a) {}
  > > };`

  Return type of member functions which check for constraints on parameters (see Section 1.2.4).

`OZ_FDPropState` [enumerable type]

  > > `enum
  > > OZ_FDPropState {fd_prop_singl = 0,
  > > fd_prop_bounds,
  > > fd_prop_any};`

  The values of this enumerable type are used to determine what kind of pruning of a finite domain causes a propagator to be resumed. The values `OZ_FDPropState` have the following meaning.

  value | rerun propagator in case ...
  --- | ---
  `fd_prop_singl` | ... a finite domain becomes a singleton.
  `fd_prop_bounds` | ... the bounds of a finite domain are narrowed.
  `fd_prop_any` | ... an arbitrary value is removed from a finite
  | domain or an equality constraint is imposed.

`OZ_FSetPropState` [enumerable type]

  > > `enum
  > > OZ_FSetPropState {fs_prop_glb = 0,
  > > fs_prop_lub,
  > > fs_prop_val,
  > > fs_prop_any,
  > > fs_prop_bounds};`

  The values of this enumerable type are used to determine what kind of pruning of a finite set constraint causes a propagator to be resumed. The values `OZ_FSetPropState` have the following meaning.

  value | rerun propagator in case ...
  --- | ---
  `fs_prop_val` | ... a finite set constraint becomes a finite set value.
  `fs_prop_glb` | ... a value is added to a set.
  `fs_prop_lub` | ... a value is removed from a set.
  `fs_prop_bounds` | ... a value is added to or removed from a set.
  `fs_prop_any` | ... either the conditions for `fs_prop_bounds` apply
  | or an equality constraint is imposed.

`OZ_ExpectMeth` [data type]

  > > `typedef
  > > OZ_expect_t (OZ_Expect::*OZ_ExpectMeth)(OZ_Term)`

  Type of member functions which check for constraints on parameters (see Section 1.2.4).

### 1.2.2 Constructor and Destructor

`OZ_expect` [default constructor]

  > > `OZ_Expect(void);`

  Default constructor of the class `OZ_Expect`.

`~OZ_expect` [destructor]

  > > `~OZ_Expect();`

  Destructor of the class `OZ_Expect`.

### 1.2.3 Specification of a Set of Integers

Specification of a set of integers is mainly used in context with finite domain and finite set constraints.

> level_4 | ::= | level_3
> | | | compl(level_3)

> level_3 | ::= | level_2
> | | | [level_2+]
> | | | `nil`

> level_2 | ::= | level_1
> | | | level_1`#`level_1

> level_1 | ::= | `OZ_getFDInf()`,...,`OZ_getFDSup()`
> |  | (in case of `OZ_Expect::expectDomDescr()`)
> | | | `OZ_getFSetInf()`,...,`OZ_getFSetSup()`
> |  | (in case of `OZ_Expect::expectFSetDescr()`)

### 1.2.4 Member Functions for Checking the Constraint Store

A member function described in this section takes as first argument a term, typically a parameter of a propagator. Extra arguments allow to control the behaviour of the member function or to specify the way subterms are to be checked. The returned value is of type `OZ_expect_t` and denotes the result of the examination of the constraint store.

`expectDomDescr` [member function]

  > > `OZ_expect_t expectDomDescr(OZ_Term descr, int level = 4);`

  This member function expects `descr` to be a finite domain specification (see Section 1.2.3) according to `level`. The non-terminal level_n in Section 1.2.3 corresponds to `level=n`.

`expectFSetDescr` [member function]

  > > `OZ_expect_t expectFSetDescr(OZ_Term descr, int level = 4);`

  This member function expects `descr` to be a finite set specification (see Section 1.2.3) according to `level`. The non-terminal level_n in Section 1.2.3 corresponds to `level=n`.

`expectVar` [member function]

  > > `OZ_expect_t expectVar(OZ_Term t);`

  Expects `t` to be a variable. A determined term `t` is regarded as an inconsistency.

`expectRecordVar` [member function]

  > > `OZ_expect_t expectRecordVar(OZ_Term t);`

  Expects `t` to be a record.

`expectBoolVar` [member function]

  > > `OZ_expect_t expectBoolVar(OZ_Term t);`

  Expects `t` to be a finite domain variable with domain resp. the value 0 or 1.

`expectIntVar` [member function]

  > > `OZ_expect_t
  > > expectIntVar(OZ_Term t,
  > > OZ_FDPropState ps = fd_prop_any);`

  Expects `t` to be a finite domain variable or a finite domain integer. The value of `ps` controls on what events the propagator has to be resumed. See the explanation on `OZ_FDPropState` in Section 1.2.1 for the values of `ps`.

`expectFSetVar` [member function]

  > > `OZ_expect_t
  > > expectFSetVar(OZ_Term t,
  > > OZ_FSetPropState ps = fs_prop_any);`

  Expects `t` to be a finite set variable or a finite set value. The value of `ps` controls on what events the propagator has to be resumed. See the explanation on `OZ_FSetPropState` in Section 1.2.1 for the values of `ps`.

`expectGenCtVar` [member function]

  > > `OZ_expect_t expectGenCtVar(OZ_Term t,
  > > OZ_CtDefinition * def,
  > > OZ_CtWakeUp w);`

  Expects `t` to be a constrained variable resp. a compatible value according to `def`. The value `w` determines the event the propagator is reinvoked. See Section 2.1 for details on `OZ_CtDefinition` and Section 2.2 for details on `OZ_CtWakeUp`.

`expectInt` [member function]

  > > `OZ_expect_t expectInt(OZ_Term t);`

  Expects `t` to be a small integer. See the systems manual ``Interfacing to C and C++'' for details.

`expectFloat` [member function]

  > > `OZ_expect_t expectFloat(OZ_Term t);`

  Expects `t` to be a float.

`expectFSetValue` [member function]

  > > `OZ_expect_t expectFSetValue(OZ_Term t);`

  Expects `t` to be a finite set value.

`expectLiteral` [member function]

  > > `OZ_expect_t expectLiteral(OZ_Term t);`

  Expects `t` to be a literal.

`expectLiteralOutOf` [member function]

  > > `OZ_expect_t expectLiteralOutOf(OZ_Term t, OZ_Term * ls);`

  Expects `t` to be a literal contained in `ls` where `ls` points to an array of literals terminated with `(OZ_Term) NULL`.

`expectVector` [member function]

  > > `OZ_expect_t expectVector(OZ_Term t,
  > > OZ_ExpectMeth expect_f);`

  Expects `t` to be a vector of terms which are all sufficiently constrained with respect to `expect_f`. A vector is either a tuple, a closed record, or a list.

`expectProperRecord` [member function]

  > > `OZ_expect_t expectProperRecord(OZ_Term t,
  > > OZ_ExpectMeth expect_f);`

  Expects `t` to be a proper record where all subtrees are sufficiently constrained with respect to `expect_f`. A proper record expects its subtrees to be indexed by literals.

`expectProperRecord` [member function]

  > > `OZ_expect_t expectProperRecord(OZ_Term t,
  > > OZ_Term * ar);`

  Expects `t` to be a proper record with at least subtrees under the features in `ar` are present where `ar` points to an array of features terminated with `(OZ_Term) NULL`.

`expectProperTuple` [member function]

  > > `OZ_expect_t expectProperTuple(OZ_Term t,
  > > OZ_ExpectMeth expect_f);`

  Expects `t` to be a proper tuple where all subtrees are sufficiently constrained with respect to `expect_f`. A proper tuple expects its subtrees to be indexed by integers.

`expectList` [member function]

  > > `OZ_expect_t expectList(OZ_Term t, OZ_ExpectMeth expect_f);`

  Expects `t` to be a list where all elements are sufficiently constrained with respect to `expect_f`. A list is either the atom `nil` or a 2-tuple with label `'|'` where the second element is a list again.

`expectStream` [member function]

  > > `OZ_expect_t expectStream(OZ_Term st);`

  Expects either an unbound variable or `nil` resp. a 2-tuple with label `'|'` where the second element is a stream too.

### 1.2.5 Member Functions for Control Purposes

`collectVarsOn` [member function]

  > > `void collectVarsOn(void);`

  This member function turns collecting variables on. That means that pruning of parameters checked in this mode may cause the propagator to be resumed.

`collectVarsOff` [member function]

  > > `void collectVarsOff(void);`

  This member function turns collecting variables off. That means that pruning of parameters checked in this mode cannot cause the propagator to be resumed.

`impose` [member function]

  > > `OZ_Return impose(OZ_Propagator *p);`

  The propagator `p` is imposed. The return value is the result of the initial invocation of `OZ_Propagator::propagate()`.

`suspend` [member function]

  > > `OZ_Return suspend(OZ_Thread th);`

  This member function is to be called if the header function has to be suspended. The thread `th` can be created with `OZ_makeSuspendedThread()` which is defined by the SCI (see ``Interfacing to C and C++'' for details).

`fail` [member function]

  > > `OZ_Return fail(void);`

  This member function is to be called if an inconsistency has been detected.

`isSuspending` [member function]

  > > `OZ_Boolean isSuspending(OZ_expect_t r);`

  Returns `OZ_TRUE` if `r` indicates that constraints expected on a parameter are not present in the current store. Otherwise it returns `OZ_FALSE`.

`isFailing` [member function]

  > > `OZ_Boolean isFailing(OZ_expect_t r);`

  Returns `OZ_TRUE` if `r` indicates an inconsistency. Otherwise it returns `OZ_FALSE`.

`isExceptional` [member function]

  > > `OZ_Boolean isFailing(OZ_expect_t r);`

  Returns `OZ_TRUE` if `r` indicates an inconsistency causing an exception. Otherwise it returns `OZ_FALSE`.

### 1.2.6 Macros

`OZ_EXPECTED_TYPE` [macro]

  > > `OZ_EXPECTED_TYPE(S)`

  This macro declares a C/C++ string used by the macros `OZ_EXPECT` and `OZ_EXPECT_SUPEND` in case an inconsistency is detected. For details see Section 1.4.2 of ``The Mozart Constraint Extensions Tutorial''.

`OZ_EM` [macro]

  > The macros `OZ_EM_` are provided to create standardized error messages.

  expected constraint | macro to be used
  --- | ---
  literal | `OZ_EM_LIT`
  float | `OZ_EM_FLOAT`
  small integer | `OZ_EM_INT`
  finite domain integer | `OZ_EM_FD`
  boolean finite domain integer in | `OZ_EM_FDBOOL`
  description of a finite domain integer | `OZ_EM_FDDESCR`
  finite set of integers | `OZ_EM_FSETVAL`
  finite set of integers constraint | `OZ_EM_FSET`
  description of a finite set of integers | `OZ_EM_FSETDESCR`
  vector of | `OZ_EM_VECT`
  record of | `OZ_EM_RECORD`
  truth name | `OZ_EM_TNAME`
  stream | `OZ_EM_STREAM`

`OZ_EXPECT` [macro]

  > > `OZ_EXPECT(O, P, F)`

  This macros checks if a term occurring at argument position `P` of a SCI function is currently expectedly constrained with respect to the function `F`. The first parameter `O` must be an instance of the class `OZ_Expect` resp. a class derived from it. Only if the expected constraints are available in the store the code following this macro is executed.

`OZ_EXPECT_SUSPEND` [macro]

  > > `OZ_EXPECT_SUSPEND(O, P, F, SC)`

  This macros has the same semantics as the previous one except that in case that expected constraints are currently not present in the store the counter `SC` is incremented and the following code is executed.