<section id="r_fd">
<title/The class <<OZ_FiniteDomain>>/
<p>
Instances of this class represent the domains for finite domain integer
variables. A domain may have holes and can range from <math/0/ to
<<OZ_getFDSup()>>, which is currently <math/134\;217\;726/.

<p>
The representation of a finite domain consists of two parts. As long as
there are no holes in the domain it suffices to store the lower and
upper bound of the domain. Holes are stored in the so-called extension
of the domain representation. This extension is either a bit-vector or a
list of intervals. The kind of extension used is automatically
determined and not visible outside.

<p>
The smallest element of a domain <math/d/ is denoted by <math/min(d)/ and
the largest element by <math/max(d)/.

<p>

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

<subsection id="r_fd.misc">
<title/Miscellaneous/

<P>

<List proglang=cc>

<Entry class="enumtype"><<OZ_FDState>>
<Index class=proglang><<OZ_FDState>></Index>
<Synopsis><<enum OZ_FDState {fd_empty, fd_full, fd_bool, fd_singl};>>

<Item>
Values of this enumerable type are used when constructing an instance
of the class <<OZ_FiniteDomain>> or in conjunction with operators
<<==>> &resp <<!=>>.
<p>
<table>
<tr> <th/value/ <th/explanation/
<tr> <td/<<fd_empty>>/ <td/The domain does not contain any element./
<tr> <td/<<fd_full>>/ <td/The domain contains all elements possible,/
<tr> <td/<P.silent>/<td/&ie <math/0, \ldots, \mbox{\tt OZ\_getFDSup()}./
<tr> <td/<<fd_bool>>/ <td/The domain contains <math/0/ and <math/1/./
<tr> <td/<<fd_singl>>/ <td/The domain contains a single element./
</table>

</List>

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

<subsection id="r_fd.member">
<title/Constructor Member Functions/

<P> 
<List proglang=cc>

<Entry class="default constructor"><<OZ_FiniteDomain>>
<Index class=proglang><<OZ_FiniteDomain>></Index>
<Synopsis> <<OZ_FiniteDomain(void);>>

<Item> This default constructor creates an <em/uninitialized/
instance.


<Entry class="copy constructor"><<OZ_FiniteDomain>>
<Index class=proglang><<OZ_FiniteDomain>></Index>
<Synopsis> <<OZ_FiniteDomain(const OZ_FiniteDomain &amp;d);>>

<Item> This copy constructor copies the current domain of <<d>> to
<<*this>>, so that <<d>> and <<*this>> denote the same domain but are
independent representations of it.

<Entry class="overloaded constructor"><<OZ_FiniteDomain>>
<Index class=proglang><<OZ_FiniteDomain>></Index>
<Synopsis> <<OZ_FiniteDomain(OZ_FDState state);>> 

<Item> This constructor creates an object which represents a domain
according to the value of <<state>>. Valid values for <<state>> are
<<fd_empty>> and <<fd_full>>.

<Entry class="overloaded constructor"><<OZ_FiniteDomain>>
<Index class=proglang><<OZ_FiniteDomain>></Index>
<Synopsis> <<OZ_FiniteDomain(OZ_Term t);>> 

<Item> This constructor is the composition of the default constructor and the
member function <<initDescr()>>.

<Entry class="overloaded constructor"><<OZ_FiniteDomain>>
<Index class=proglang><<OZ_FiniteDomain>></Index>
<Synopsis> <<OZ_FiniteDomain(const OZ_FSetValue &amp;fs);>>

<Item>
This constructor initialises <<*this>> with the values contained in
the finite set <<fs>>.

</List>

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

<subsection id="r_fd.init">
<title/Initialisation Member Functions/
<p>

The return value of all initialisation member functions is the size of
the domain they initialised.
<p>

<List proglang=cc>

<Entry class="member function"><<initRange>>
<Index class=proglang><<OZ_FiniteDomain>><And><<initRange>></Index>
<Synopsis> <<int OZ_FiniteDomain::initRange(int l, int u);>>

<Item> Initialises an instance of class <<OZ_FiniteDomain>> to the
domain <math/\{l, \ldots, u\}/. 
<P> In case <<l>> &gt; <<u>>, the domain
is set to be empty.


<Entry class="member function"><<initSingleton>>
<Index class=proglang><<OZ_FiniteDomain>><And><<initSingleton>></Index>
<Synopsis> <<int OZ_FiniteDomain::initSingleton(int l);>>

<Item> Initialises an instance of class <<OZ_FiniteDomain>> to the
domain <math/\{l\}/.


<Entry class="member function"><<initDescr>>
<Index class=proglang><<OZ_FiniteDomain>><And><<initDescr>></Index>
<Synopsis> <<int OZ_FiniteDomain::initDescr(OZ_Term d);>>

<Item> Initialises an instance of class <<OZ_FiniteDomain>> to a
domain according to the domain description <<d>>. The domain
description must be conform with <em/level4/ (see syntax definition of
a domain description in <ptr to="expect.checkconstr">, entry
<<expectDomDesc>>).


<Entry class="member function"><<initFull>>
<Index class=proglang><<OZ_FiniteDomain>><And><<initFull>></Index>
<Synopsis> <<int OZ_FiniteDomain::initFull(void);>>

<Item> Initialises an instance of class <<OZ_FiniteDomain>> to the
domain <math/\{0, \ldots, \mbox{\tt OZ\_getFDSup()}\}/.


<Entry class="member function"><<initEmpty>>
<Index class=proglang><<OZ_FiniteDomain>><And><<initEmpty>></Index>
<Synopsis> <<int OZ_FiniteDomain::initEmpty(void);>>

<Item> Initialises an instance of class <<OZ_FiniteDomain>> to the empty
domain.


<Entry class="member function"><<initBool>>
<Index class=proglang><<OZ_FiniteDomain>><And><<initBool>></Index>
<Synopsis> <<int OZ_FiniteDomain::initBool(void);>>

<Item> Initialises an instance of class <<OZ_FiniteDomain>> to the domain
<math/\{0,1\}/.

</List>

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

<subsection id="r_fd.reflect">
<title/Reflection Member Functions/
<p>

<List proglang=cc>

<Entry class="constant member function"><<getMidElem>>
<Index class=proglang><<OZ_FiniteDomain>><And><<getMidElem>></Index>
<Synopsis> <<int getMidElem(void) const;>>

<Item> This member function returns the element in the middle of the
domain. For the domain <math/d/ it is <math/(max(d)-min(d))\; div\;
2/. If this value happens to be a hole the element closest to it will
be returned. In case there are two elements with the same distance to
the middle of the domain the smaller one will be taken.


<Entry class="constant member function"><<getNextSmallerElem>>
<Index class=proglang><<OZ_FiniteDomain>><And><<getNextSmallerElem>></Index>
<Synopsis> <<int getNextSmallerElem(int v) const;>>

<Item> This member function returns the largest element in the domain
smaller than <<v>>.  In case <<v>> is the smallest element it returns
<math/-1/.


<Entry class="constant member function"><<getNextLargerElem>>
<Index class=proglang><<OZ_FiniteDomain>><And><<getNextLargerElem>></Index>
<Synopsis> <<int getNextLargerElem(int v) const;>>

<Item> This member function returns the smallest element in the domain
larger than <<v>>.  In case <<v>> is the largest element it returns
<math/-1/.


<Entry class="constant member function"><<getLowerIntervalBd>>
<Index class=proglang><<OZ_FiniteDomain>><And><<getLowerIntervalBd>></Index>
<Synopsis> <<int getLowerIntervalBd(int v) const;>>

<Item> This member function returns the smallest value of the interval
<<v>> belongs to. In case <<v>> does not belong to any interval the
function returns <math/-1/.


<Entry class="constant member function"><<getUpperIntervalBd>>
<Index class=proglang><<OZ_FiniteDomain>><And><<getUpperIntervalBd>></Index>
<Synopsis> <<int getUpperIntervalBd(int v) const;>>

<Item> This member function returns the largest value of the interval
<<v>> belongs to. In case <<v>> does not belong to any interval the
function returns <math/-1/.


<Entry class="constant member function"><<getSize>>
<Index class=proglang><<OZ_FiniteDomain>><And><<getSize>></Index>
<Synopsis> <<int getSize(void) const;>>

<Item> This member function returns the size of the domain, &ie the
number of elements in the domain.


<Entry class="constant member function"><<getMinElem>>
<Index class=proglang><<OZ_FiniteDomain>><And><<getMinElem>></Index>
<Synopsis> <<int getMinElem(void) const;>>

<Item> This member function returns the smallest element of the domain.


<Entry class="constant member function"><<getMaxElem>>
<Index class=proglang><<OZ_FiniteDomain>><And><<getMaxElem>></Index>
<Synopsis> <<int getMaxElem(void) const;>>

<Item> This member function returns the largest element of the domain.


<Entry class="constant member function"><<getSingleElem>>
<Index class=proglang><<OZ_FiniteDomain>><And><<getSingleElem>></Index>
<Synopsis> <<int getSingleElem(void) const;>>

<Item> This member function returns the element of a singleton domain. In case
the domain is not a singleton domain it returns <math/-1/.

</List>

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

<subsection id="r_fd.op">
<title/Operator Member Functions/
<p>

<List proglang=cc>

<Entry class="operator member function"><<operator =>>
<Index class=proglang><<OZ_FiniteDomain>><And><<operator =>></Index>
<Synopsis> <<const OZ_FiniteDomain &amp;operator = (const OZ_FiniteDomain &amp;fd);>>

<Item> This assignment operator copies <<fd>> to its left hand side,
so that both domains are the same but are independent of each other.


<Entry class="constant operator member function"><<operator ==>>
<Index class=proglang><<OZ_FiniteDomain>><And><<operator ==>></Index>
<Synopsis> <<OZ_Boolean operator == (const OZ_FDState s) const;>>

<Item> This operator returns <<OZ_TRUE>> if the domain corresponds to
the value of <<s>>. Otherwise it returns <<OZ_FALSE>>.

<Entry class="constant operator member function"><<operator ==>>
<Index class=proglang><<OZ_FiniteDomain>><And><<operator ==>></Index>
<Synopsis> <<OZ_Boolean operator == (const int i) const;>>

<Item> This operator returns <<OZ_TRUE>> if the domain contains only
<<i>>. Otherwise it returns <<OZ_FALSE>>.


<Entry class="constant operator member function"><<operator !=>>
<Index class=proglang><<OZ_FiniteDomain>><And><<operator !=>></Index>
<Synopsis> <<OZ_Boolean operator != (const OZ_FDState s) const;>>

<Item> This operator returns <<OZ_TRUE>> if the domain does <em/not/
correspond to the value of <<s>>. Otherwise it returns <<OZ_FALSE>>.

<Entry class="constant operator member function"><<operator !=>>
<Index class=proglang><<OZ_FiniteDomain>><And><<operator !=>></Index>
<Synopsis> <<OZ_Boolean operator != (const int i) const;>>

<Item> This operator returns <<OZ_TRUE>> if the domain does <em/not/
contain <<i>> or contains more than one element. Otherwise it returns
<<OZ_FALSE>>.


<Entry class="constant operator member function"><<operator &amp;>>
<Index class=proglang><<OZ_FiniteDomain>><And><<operator &amp;>></Index>
<Synopsis> <<OZ_FiniteDomain operator &amp; (const OZ_FiniteDomain &amp;y) const;>>

<Item> This member function returns the intersection of the finite
domains represented by <<y>> and <<*this>>.


<Entry class="constant operator member function"><<operator |>>
<Index class=proglang><<OZ_FiniteDomain>><And><<operator |>></Index>
<Synopsis> <<OZ_FiniteDomain operator | (const OZ_FiniteDomain &amp;y) const;>>

<Item> This member function returns the union of the finite domains
represented by <<y>> and <<*this>>.


<Entry class="constant operator member function"><<operator ~>>
<Index class=proglang><<OZ_FiniteDomain>><And><<operator ~>></Index>
<Synopsis> <<OZ_FiniteDomain operator ~ (void) const;>>

<Item>
This member function returns the negation of the finite domain
represented by <<*this>>. The negation is computed by removing all
elements in <<*this>> from <math/\{0, \ldots, \mbox{\tt
OZ\_getFDSup()}\}/.


<Entry class="operator member function"><<operator &amp;=>>
<Index class=proglang><<OZ_FiniteDomain>><And><<operator &amp;=>></Index>
<Synopsis> 
<<<
int operator &= (const OZ_FiniteDomain &amp;y);
int operator &= (const int y);
>>>

<Item> This member function computes the intersection of the finite domains
represented by <<y>> and <<*this>> and assigns the result to
<<*this>>. Further, the size of the updated domain is returned.


<Entry class="operator member function"><<operator +=>>
<Index class=proglang><<OZ_FiniteDomain>><And><<operator +=>></Index>
<Synopsis> <<int operator += (const int y);>>

<Item> This member function adds the element <<y>> to the domain
represented by <<*this>> and returns the size of the updated domain.


<Entry class="operator member function"><<operator -=>>
<Index class=proglang><<OZ_FiniteDomain>><And><<operator -=>></Index>
<Synopsis> <<int operator -= (const int y);>>

<Item>
This member function removes the element <<y>> from the domain
represented by <<*this>> and returns the size of the updated domain.

<Entry class="operator member function"><<operator -=>>
<Index class=proglang><<OZ_FiniteDomain>><And><<operator -=>></Index>
<Synopsis> <<int operator -= (const OZ_FiniteDomain &amp;y);>>

<Item> This member function removes all elements contained in the
domain represented by <<y>> from the domain represented by <<*this>>
and returns the size of the updated domain.


<Entry class="operator member function"><<operator &lt;=>>
<Index class=proglang><<OZ_FiniteDomain>><And><<operator &lt;=>></Index>
<Synopsis> <<int operator &lt;= (const int y);>>

<Item>
This member function removes all elements being larger than <<y>>
from the domain represented by <<*this>> and returns the size of the
updated domain.


<Entry class="operator member function"><<operator &gt;=>>
<Index class=proglang><<OZ_FiniteDomain>><And><<operator &gt;=>></Index>
<Synopsis> <<int operator &gt;= (const int y);>>

<Item> This member function removes all elements being smaller than
<<y>> from the domain represented by <<*this>> and returns the size of
the updated domain.

</List>

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

<subsection id="r_fd.aux">
<title/Auxiliary Member Functions/
<p>

<List proglang=cc>

<Entry class="member function"><<intersectWithBool>>
<Index class=proglang><<OZ_FiniteDomain>><And><<intersectWithBool>></Index>
<Synopsis> <<int intersectWithBool(void);>>

<Item>
This member function intersects the current domain with the domain
<math/\{0,1\}/ and produces the following return value.
<P>

<table>
<tr> <th/return value/ <th/meaning/
<tr> <td/<math/-2// <td/The resulting domain is empty./
<tr> <td/<math/-1// <td/The resulting domain is <math/\{0,1\}//
<tr> <td/otherwise/ <td/The remaining element is returned.
</table>


<Entry class="member function"><<constrainBool>>
<Index class=proglang><<OZ_FiniteDomain>><And><<constrainBool>></Index>
<Synopsis> <<int constrainBool(void);>>

<Item> This member function intersects the current domain with the
domain <math/\{0,1\}/ and returns the size of resulting domain.


<Entry class="member function"><<isIn>>
<Index class=proglang><<OZ_FiniteDomain>><And><<isIn>></Index>
<Synopsis> <<OZ_Boolean isIn(int i) const;>>

<Item> This member function returns <<OZ_TRUE>> if <<i>> is contained
in the domain represented by <<*this>>. Otherwise it returns
<<OZ_FALSE>>.


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

<Item> This member function replaces the current extension of the
domain representation by a copy of it.


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

<Item> This member function frees the heap memory occupied by the
extension of the domain.

<Entry class="constant member function"><<toString>>
<Index class=proglang><<OZ_FiniteDomain>><And><<toString>></Index>
<Synopsis><<char * toString(void) const;>>

<Item> Returns a textual representation of the finite domain pointing
to a static array of <<char>>s.

</List>

<p>
