## `Cat::BaseCategory` -- the base category

#### Introduction

`Cat::BaseCategory` is the ``universal'' category, any domain in the `Dom` package is of this category.

#### Generating the category

`Cat::BaseCategory()`

#### Details

- `Cat::BaseCategory` is the most general super-category of all categories defined by the `Cat` package. Any domain in the `Dom` package is of this category.
- The methods defined by `Cat::BaseCategory` are related to type conversion and equality testing, they are not related to an algebraic structure.

#### Method convert: convert into this domain

- `convert(x)`
- - Must convert `x` into an element of this domain or return `FAIL` if that is not possible.

#### Method convert_to: convert to certain type

- `convert_to(dom x, type T)`
- - Must convert `x` into an element of type `T` or return `FAIL` if that is not possible. `T` may be domain or a type expression.

#### Method equal: test for equality

- `equal(dom x, dom y)`
- - This method must return `TRUE` if it can decide that `x` is equal to `y` in the mathematical sense imposed by this domain. It must return `FALSE` if it can decide that `x` is not equal to `y` mathematically. If the method can not decide the equality it must return `UNKNOWN`.
  - Note that this method does not overload the function `_equal`, i.e. the `=` operator. The function `_equal` may not be overloaded.

#### Method expr: convert into expression

- `expr(dom x)`
- - Must convert `x` into an expression consisting of elements of kernel domains. The expression should canonically represent an element of this domain, if possible.

#### Method coerce: coerce into this domain

- `coerce(x)`
- - Tries to coerce `x` into an element of this domain. Must return `FAIL` if not successful.
  - The implementation provided tries to convert `x` into an element of this domain by first calling `dom::convert(x)` and then, if this fails, `x::dom::convert_to(x, dom)`; it retuns `FAIL` if both methods fail.

#### Method equiv: test for equivalence

- `equiv(x, y)`
- - Tries to decide if the arguments are equal when regarded as elements of this domain. Returns `FAIL` if no decision was possible.
  - The implementation provided tries to convert `x` and `y` into elements of this domain and then calls `dom::equal` with these elements. It returns `FAIL` if the conversion fails or the equality test returns `UNKNOWN`.

#### Method new: create element of this domain

- `new(x)`
- - Creates a new element of this domain.
  - Given a domain `D`, an expression of the form `D(x,...)` results in a call of the form `D::new(x,...)`.
  - The implementation provided here tries to convert `x` by calling `dom::convert(x)` and returns the result. It raises an error if `dom::convert` returns `FAIL`.

#### Method print: return expression to print an element

- `print(dom x)`
- - This method must return an expression which is printed instead of the original element `x`. It may be used to configure the printing of domain elements.
  - Please do not print directly in this method by calling the function `print` for example!
  - The implementation provided here is `dom::expr`.

#### Method testtype: test type of object

- `testtype(x, T)`
- - This method is called by the function `testtype`. It is used to test if `x` is of type `T`.
  - This method must return `TRUE` if it can decide that `x` is of type `T`, `FALSE` if it can decide that `x` is not of type `T` and `FAIL` if it can not decide the test.
  - This method is called in three different situations: Either if the argument `x` is of this domain, or if `T` is this domain, or if `T` is an element of this domain. Thus the following three situations can arise:

- `testtype(dom x, type T)`
- - In this case it must be tested if `x` may be regarded as an element of the type `T`, which may either be a domain or type expression. `dom::convert_to(x,T)` is called, if this is successful `TRUE` is returned and `FAIL` if not.

- `testtype(x, dom)`
- - In this case it must be tested if `x` may be regarded as an element of this domain. `dom::convert(x)` is called, if this is successful `TRUE` is returned and `FAIL` if not.

- `testtype(x, dom T)`
- - In this case `T` is regarded as a type expression. The implementation provided assumes that `T` represents the type consisting of the singleton element `T` and returns the result of the call `dom::equiv(x,T)`.

#### Method new_extelement: create element of kernel or facade domain

- `new_extelement(x...)`
- - This method is defined only for domains with axiom `Ax::systemRep`, i.e. for kernel or facade domains. (Facade domains are domains which do not have elements of their own domain but operate on elements of kernel domains like `DOM_POLY`.)
  - When an expression `new(D,x...)` is evaluated and `D` is a domain with method `"new_extelement"`, then `D::new_extelement(D,x...)` is evaluated and returned as result.
  - Kernel or facade domains must define this method because otherwise the function `new` would return a ``container'' element of `D` rather than a ``raw'' element as intended.
  - The implementation provided here returns the result of `D::new(x...)`. Thus a call of the form `new(D,x...)` yields the same result as a call of the form `D(x...)`.

#### Changes

- Has been renamed. Used to be `Cat::SetCat`.
- The method `"printElem"` has been removed.

Do you have questions or comments?
Copyright © SciFace Software GmbH & Co. KG 2000