<Chapter id="chapter.ct">
  <Title/Building Constraint Systems from Scratch/

<Section id="ct.reference.def"> 
  <Title>The class <<OZ_CtDefinition>> </Title>

<P>
<List proglang=cc>

<Entry class="purevirtual member function"><<getKind>>
<Index class=proglang><<OZ_CtDefinition>><And><<getKind>></Index>
<Synopsis><<virtual int getKind(void) = 0;>> 

<Item> Returns an integer identifying a constraint system. The integer
value has to be unique for each constraint system.  Call <<int
OZ_getUniqueId(void)>> to obtain a unique identifier.

<Entry class="purevirtual member function"><<getNoOfWakeUpLists>>
<Index class=proglang><<OZ_CtDefinition>><And><<getNoOfWakeUpLists>></Index>
<Synopsis><<virtual int getNoOfWakeUpLists(void) = 0;>>

<Item> Returns the numbers of wake-up lists of variables constrained
with this kind of constraint. This number corresponds to the number
of events which can cause a propagator being imposed on that kind of
variable being rerun.

<Entry class="purevirtual member function"><<getNamesOfWakeUpLists>>
<Index class=proglang><<OZ_CtDefinition>><And><<getNamesOfWakeUpLists>></Index>
<Synopsis><<virtual char ** getNamesOfWakeUpLists(void) = 0;>> 

<Item> Returns an array (with <<getNoOfWakeUpLists()>> entries) of
strings describing the event(s) associated to the corresponding
wake-up list.

<Entry class="purevirtual member function"><<getName>>
<Index class=proglang><<OZ_CtDefinition>><And><<getName>></Index>
<Synopsis><<virtual char * getName(void) = 0;>> 

<Item> Returns the name of the constraint system. Is used when
outputting variables of that kind.

<Entry class="purevirtual member function"><<leastConstraint>>
<Index class=proglang><<OZ_CtDefinition>><And><<leastConstraint>></Index>
<Synopsis><<virtual OZ_Ct * leastConstraint(void) = 0;>> 

<Item> Returns the constraint which is subsumed by or equal to all
other constraints of a certain constraint system.

<Entry class="purevirtual member function"><<isValidValue>>
<Index class=proglang><<OZ_CtDefinition>><And><<isValidValue>></Index>
<Synopsis><<virtual OZ_Boolean isValidValue(OZ_Term t) = 0;>>

<Item> Returns <<OZ_True>> if the &oz; value referred to by <<t>> is a
value which is in the domain of the constraint system. Otherwise it
returns <<OZ_False>>.

</List>

</Section>

<!-- ************************************************************************** -->

<Section id="ct.reference.wakeup"> <Title>The class <<OZ_CtWakeUp>> </Title>

<P>
<List proglang=cc>

<Entry class="member function"><<init>>
<Index class=proglang><<OZ_CtWakeUp>><And><<init>></Index>
<Synopsis><<void init(void);>>

<Item> Initializes an instance of this class. <Note foot> Note that
there is no default constructor for some implementational
reasons. </Note>

<Entry class="member function"><<isEmpty>>
<Index class=proglang><<OZ_CtWakeUp>><And><<isEmpty>></Index>
<Synopsis><<OZ_Boolean isEmpty(void);>>

<Item> Returns <<OZ_True>> if no wake-up list has to be scanned.

<Entry class="member function"><<setWakeUp>>
<Index class=proglang><<OZ_CtWakeUp>><And><<setWakeUp>></Index>
<Synopsis><<OZ_Boolean setWakeUp(int i);>>

<Item> Sets the wake-up list indexed by <<i>> (<<i>> <Math>=
0,\ldots,</Math> <<getNoOfWakeUpLists()>>-1) to be scanned.

<Entry class="member function"><<isWakeUp>>
<Index class=proglang><<OZ_CtWakeUp>><And><<isWakeUp>></Index>
<Synopsis><<OZ_Boolean isWakeUp(int i);>>

<Item> Returns <<OZ_True>> if the corresponding wake-up list indexed by
<<i>> is to be scanned.

<Entry class="static member function"><<getWakeUpAll>>
<Index class=proglang><<OZ_CtWakeUp>><And><<getWakeUpAll>></Index>
<Synopsis><<static OZ_CtWakeUp getWakeUpAll(void);>> 

<Item> Sets all possible wake-up events.

</List>

</Section>

<!-- ************************************************************************** -->

<Section id="ct.reference.profile"> <Title>The class <<OZ_CtProfile>> </Title>

<P>
<List proglang=cc>

<Entry class="constructor"><<OZ_CtProfile>>
<Index class=proglang><<OZ_CtProfile>><And><<OZ_CtProfile>></Index>
<Synopsis><<OZ_CtProfile(void);>>

<Item> Initializes an instance of this class.

<Entry class="purevirtual member function"><<init>>
<Index class=proglang><<OZ_CtProfile>><And><<init>></Index>
<Synopsis><<virtual void init(OZ_Ct * c) = 0;>>

<Item> Stores a profile according to the constraint referred to by <<c>>.

</List>

</Section>

<!-- ************************************************************************** -->

<Section id="ct.reference.constraint"> <Title>The class <<OZ_Ct>> </Title>

<P> An instance of this class represents a constraint of a certain
constraint system.

<P>
<List proglang=cc>

<Entry class="constructor"><<OZ_Ct>>
<Index class=proglang><<OZ_Ct>><And><<OZ_Ct>></Index>
<Synopsis><<OZ_Ct(void);>>

<Item> Initializes an instance of this class.

<Entry class="purevirtual member function"><<isValue()>>
<Index class=proglang><<OZ_Ct>><And><<isValue>></Index>
<Synopsis><<virtual OZ_Boolean isValue(void) = 0;>>

<Item> Returns <<OZ_True>> if the constraint denotes exactly one value
of the domain of the constraint system.

<Entry class="purevirtual member function"><<toValue>>
<Index class=proglang><<OZ_Ct>><And><<toValue>></Index>
<Synopsis><<virtual OZ_Term toValue(void) = 0;>>

<Item> Returns an &oz; value of the value denoted by the
constraint. Returned value is only defined if <<isValue>> yields
<<OZ_True>>.

<Entry class="purevirtual member function"><<isValid>>
<Index class=proglang><<OZ_Ct>><And><<isValid>></Index>
<Synopsis><<virtual OZ_Boolean isValid(void) = 0;>> 

<Item> Returns <<OZ_True>> if the constraint denotes at least one
element of the domain of the constraint system. Otherwise it returns
<<OZ_False>>.

<Entry class="purevirtual member function"><<isWeakerThan>>
<Index class=proglang><<OZ_Ct>><And><<isWeakerThan>></Index>
<Synopsis><<virtual OZ_Boolean isWeakerThan(OZ_Ct * c) = 0;>>

<Item> Returns <<OZ_True>> if the constraint represented by <<*c>>
subsumes the constraint represented by <<*this>> instance.

<Entry class="purevirtual member function"><<unify>>
<Index class=proglang><<OZ_Ct>><And><<unify>></Index>
<Synopsis><<virtual OZ_Ct * unify(OZ_Ct * c) = 0;>>

<Item> Returns a constraint that approximates all elements of the
constraint domain denoted by the constraints <<*c>> <Em>and</Em> <<*this>>.

<Entry class="purevirtual member function"><<unify>>
<Index class=proglang><<OZ_Ct>><And><<unify>></Index>
<Synopsis><<virtual OZ_Boolean unify(OZ_Term t) = 0;>> 

<Item> Returns <<OZ_True>> if the value denoted by <<t>> is included
in the values approximated by the constraint.

<Entry class="purevirtual member function"><<sizeOf>>
<Index class=proglang><<OZ_Ct>><And><<sizeOf>></Index>
<Synopsis><<virtual size_t sizeOf(void) = 0;>>

<Item> Returns the size of an instance of the class derived <<OZ_Ct>>
(analogue to C's <<sizeof>> operator).

<Entry class="purevirtual member function"><<getProfile>>
<Index class=proglang><<OZ_Ct>><And><<getProfile>></Index>
<Synopsis><<virtual OZ_CtProfile * getProfile(void) = 0;>>

<Item> Returns a constraint profile (see <Ptr to="ct.reference.profile">) according to the constraint. 

<Entry class="purevirtual member function"><<getWakeUpDescriptor>>
<Index class=proglang><<OZ_Ct>><And><<getWakeUpDescriptor>></Index>
<Synopsis><<virtual OZ_CtWakeUp getWakeUpDescriptor(OZ_CtProfile * p) = 0;>>

<Item> Returns a descriptor for the wake-up lists to be scanned (see
<Ptr to="ct.reference.wakeup">). This descriptor is computed by
comparing the constraint with the profile <<p>>. Note the profile is
usually taken from the constraint before modifying it.

<Entry class="purevirtual member function"><<toString>>
<Index class=proglang><<OZ_Ct>><And><<toString>></Index>
<Synopsis><<virtual char * toString(int) = 0;>>

<Item> Returns a textual representation of the constraint.

<Entry class="purevirtual member function"><<copy>>
<Index class=proglang><<OZ_Ct>><And><<copy>></Index>
<Synopsis><<virtual OZ_Ct * copy(void) = 0;>>

<Item> Returns a pointer to a copy of the constraint. The memory for
the copy is to be allocated by the operator <<OZ_Ct::new>>.

<Entry class="static operator member function"><<operator new>>
<Index class=proglang><<OZ_Ct>><And><<operator new>></Index>
<Synopsis><<static void * operator new(size_t, int align = sizeof(void
*));>> 

<Item> Allocates memory for an instance of the constraint on the heap
of the &oz; runtime system.


<Entry class="static operator member function"><<operator delete>>
<Index class=proglang><<OZ_Ct>><And><<operator delete>></Index>
<Synopsis><<static void operator delete(void *, size_t);>>

<Item> Deallocates memory of an instance of the constraint from the heap
of the &oz; runtime system.

</List>

</Section>

<!-- ************************************************************************** -->

<Section id="ct.reference.ctvar"> <Title>The class <<OZ_CtVar>> </Title>

<P proglang=cc>
The constraint system dependent part of a class derived from
<<OZ_CtVar>> stores typically

<List>

<Item> a constraint <<C>>, &ie;, an instance of the class representing
a constraint,

<Item> a constraint <<EC>>, &ie;, an instance of the class representing
a constraint,

<Item> a reference to a constraint <<CR>>, and

<Item> a constraint profile <<CP>>.

</List>

The constraint <<C>> is used to handle constraints of global
variables. The constraint <<EC>> is used to handle encapsulate
propagation typically occurring in reified constraints. The reference
to a constraint <<CR>> is used to access the actual constraint and
thus to be able to modify it. It either points to <<C>>, <<EC>>, or
directly to the constraint associated with a constrained variable.

<SubSection id="ct.reference.ctvar.protected"> <Title>Members to
be Defined</Title>

<P>
<List proglang=cc>

<Entry class="protected purevirtual member function"><<ctSetValue>>
<Index class=proglang><<OZ_CtVar>><And><<ctSetValue>></Index>
<Synopsis><<virtual void ctSetValue(OZ_Term t) = 0;>> 

<Item> Initializes <<C>> to the value denoted by <<t>> and makes
<<CR>> pointing to <<C>>.

<Entry class="protected purevirtual member function"><<ctRefConstraint>>
<Index class=proglang><<OZ_CtVar>><And><<ctRefConstraint>></Index>
<Synopsis><<virtual OZ_Ct * ctRefConstraint(OZ_Ct * c) = 0;>>

<Item> Sets <<CR>> to <<c>> and returns <<CR>>.

<Entry class="protected purevirtual member function"><<ctSaveConstraint>>
<Index class=proglang><<OZ_CtVar>><And><<ctSaveConstraint>></Index>
<Synopsis><<virtual OZ_Ct * ctSaveConstraint(OZ_Ct * c) = 0;>>

<Item> Stores <<c>> in <<C>> and returns a reference to <<C>>.

<Entry class="protected purevirtual member function"><<ctSaveEncapConstraint>>
<Index class=proglang><<OZ_CtVar>><And><<ctSaveEncapConstraint>></Index>
<Synopsis><<virtual OZ_Ct * ctSaveEncapConstraint(OZ_Ct * c) = 0;>>

<Item> Stores <<c>> in <<EC>> and returns a reference to <<EC>>.

<Entry class="protected purevirtual member function"><<ctRestoreConstraint>>
<Index class=proglang><<OZ_CtVar>><And><<ctRestoreConstraint>></Index>
<Synopsis><<virtual void ctRestoreConstraint(void) = 0;>>

<Item> Stores <<C>> at <<*CR>>.

<Entry class="protected purevirtual member function"><<ctSetConstraintProfile>>
<Index class=proglang><<OZ_CtVar>><And><<ctSetConstraintProfile>></Index>
<Synopsis><<virtual void ctSetConstraintProfile(void) = 0;>>

<Item> Initializes <<CP>> with the profile of <<CR>>.

<Entry class="protected purevirtual member function"><<ctGetConstraintProfile>>
<Index class=proglang><<OZ_CtVar>><And><<ctGetConstraintProfile>></Index>
<Synopsis><<virtual OZ_CtProfile * ctGetConstraintProfile(void) = 0;>>

<Item> Returns <<CP>>.

<Entry class="protected purevirtual member function"><<ctGetConstraint>>
<Index class=proglang><<OZ_CtVar>><And><<ctGetConstraint>></Index>
<Synopsis><<virtual OZ_Ct * ctGetConstraint(void) = 0;>>
<Item> Returns <<CR>>.

<Entry class="public purevirtual member function"><<isTouched>>
<Index class=proglang><<OZ_CtVar>><And><<isTouched>></Index>
<Synopsis><<virtual OZ_Boolean isTouched(void) const = 0;>>

<Item> Returns <<OZ_True>> if current constraint is not implied
anymore by the constraint that was present upon calling <<read()>> or
<<readEncap()>>.

</List>

</SubSection>

<!-- ************************************************************************** -->

<SubSection id="ct.reference.ctvar.public"> <Title> Provided Members</Title>

<P>
<List proglang=cc>

<Entry class="constructor"><<OZ_CtVar>>
<Index class=proglang><<OZ_CtVar>><And><<OZ_CtVar>></Index>
<Synopsis><<OZ_CtVar(void);>>

<Item> Initializes an instance of this class.

<Entry class="static operator member function"><<operator new>>
<Index class=proglang><<OZ_CtVar>><And><<operator new>></Index>
<Synopsis><<static void * operator new(size_t);>>

<Item> Allocates memory for an instance of a class derived from
<<OZ_CtVar>> on the propagator heap of the &oz; runtime system.

<Entry class="static operator member function"><<operator delete>>
<Index class=proglang><<OZ_CtVar>><And><<operator delete>></Index>
<Synopsis><<static void operator delete(void *, size_t);>>

<Item> Deallocates memory of an instance of a class derived from
<<OZ_CtVar>> from the propagator heap of the &oz; runtime system.

<Entry class="static operator member function"><<operator new[]>>
<Index class=proglang><<OZ_CtVar>><And><<operator new[]>></Index>
<Synopsis><<static void * operator new[](size_t);>>

<Item> Allocates memory for an array of instances of a class derived
from <<OZ_CtVar>> on the propagator heap of the &oz; runtime system.

<Entry class="static operator member function"><<operator delete[]>>
<Index class=proglang><<OZ_CtVar>><And><<operator delete[]>></Index>
<Synopsis><<static void operator delete[](void *, size_t);>>

<Item> Deallocates memory of an array of instances of a class derived from
<<OZ_CtVar>> from the propagator heap of the &oz; runtime system.

<Entry class="member function"><<ask>>
<Index class=proglang><<OZ_CtVar>><And><<ask>></Index>
<Synopsis><<void ask(OZ_Term);>>

<Item> Initializes an instance of a derived class of <<OZ_CtVar>> for
reading the constraint of the corresponding variable. The members
<<leave()>> and <<fail()>> <Em/must not/ be called.

<Entry class="member function"><<read>>
<Index class=proglang><<OZ_CtVar>><And><<read>></Index>
<Synopsis><<void read(OZ_Term);>>

<Item> Initializes an instance of a derived class of <<OZ_CtVar>> for
accessing the corresponding variable in the constraint store for
constraint propagation. Modifying the constraint is visible in the
store. The members <<leave()>> and <<fail()>> <Em/must be/ called.

<Entry class="member function"><<readEncap>>
<Index class=proglang><<OZ_CtVar>><And><<readEncap>></Index>
<Synopsis><<void readEncap(OZ_Term);>>

<Item> Initializes an instance of a derived class of <<OZ_CtVar>> for
accessing the corresponding variable in the constraint store for
encapsulated constraint propagation (typically used for reified
constraints). Modifying the constraint is <Em/not/ visible in the
store. The members <<leave()>> and <<fail()>> <Em/must be/ called.

<Entry class="member function"><<leave>>
<Index class=proglang><<OZ_CtVar>><And><<leave>></Index>
<Synopsis><<OZ_Boolean leave(void);>>

<Item> This member function has to be called if the instance of
a derived class of <<OZ_CtVar>> has been initialized by <<read()>> &resp;
<<readEncap()>> and the constraint represented by the propagator is
<Em/consistent/ with the constraint store. It returns <<OZ_False>> if
the corresponding variable denotes a value. Otherwise it returns
<<OZ_True>>. Further, this member function causes suspending
computation to be woken up.

<Entry class="member function"><<fail>>
<Index class=proglang><<OZ_CtVar>><And><<fail>></Index>
<Synopsis><<void fail(void);>>

<Item> This member function has to be called if the instance of a
derived class of <<OZ_CtVar>> has been initialized by <<read()>>
&resp; <<readEncap()>> and the constraint represented by the
propagator is <Em/inconsistent/ with the constraint store. 

<Entry class="member function"><<dropParameter>>
<Index class=proglang><<OZ_CtVar>><And><<dropParameter>></Index>
<Synopsis><<void dropParameter(void);>>

<Item> This member function removes the parameter associated with
<<*this>> from the parameter set of the current propagator. This
function takes care of multiple occurrences of a single variable as
parameter, i.e., a parameter is removed if there is only one
occurrence of the corresponding variable in the set of parameter left.

</List>

</SubSection>

</Section>

</Chapter>
