diff --git a/.gitattributes b/.gitattributes index d185cfc0ebb..976f1db4d28 100644 --- a/.gitattributes +++ b/.gitattributes @@ -51,6 +51,61 @@ AABB_tree/test/AABB_tree/data/cube.off -text AABB_tree/test/AABB_tree/data/finger.off -text AABB_tree/test/AABB_tree/data/pinion.off -text AABB_tree/test/AABB_tree/data/tetrahedron.off -text +Algebraic_foundations/doc/Algebraic_foundations/Algebraic_foundations.txt -text +Algebraic_foundations/doc/Algebraic_foundations/CGAL/Algebraic_structure_traits.h -text +Algebraic_foundations/doc/Algebraic_foundations/CGAL/Coercion_traits.h -text +Algebraic_foundations/doc/Algebraic_foundations/CGAL/Fraction_traits.h -text +Algebraic_foundations/doc/Algebraic_foundations/CGAL/Real_embeddable_traits.h -text +Algebraic_foundations/doc/Algebraic_foundations/CGAL/number_utils.h -text +Algebraic_foundations/doc/Algebraic_foundations/Classified.txt -text +Algebraic_foundations/doc/Algebraic_foundations/Concepts/AlgebraicStructureTraits--Div.h -text +Algebraic_foundations/doc/Algebraic_foundations/Concepts/AlgebraicStructureTraits--DivMod.h -text +Algebraic_foundations/doc/Algebraic_foundations/Concepts/AlgebraicStructureTraits--Divides.h -text +Algebraic_foundations/doc/Algebraic_foundations/Concepts/AlgebraicStructureTraits--Gcd.h -text +Algebraic_foundations/doc/Algebraic_foundations/Concepts/AlgebraicStructureTraits--IntegralDivision.h -text +Algebraic_foundations/doc/Algebraic_foundations/Concepts/AlgebraicStructureTraits--Inverse.h -text +Algebraic_foundations/doc/Algebraic_foundations/Concepts/AlgebraicStructureTraits--IsOne.h -text +Algebraic_foundations/doc/Algebraic_foundations/Concepts/AlgebraicStructureTraits--IsSquare.h -text +Algebraic_foundations/doc/Algebraic_foundations/Concepts/AlgebraicStructureTraits--IsZero.h -text +Algebraic_foundations/doc/Algebraic_foundations/Concepts/AlgebraicStructureTraits--KthRoot.h -text +Algebraic_foundations/doc/Algebraic_foundations/Concepts/AlgebraicStructureTraits--Mod.h -text +Algebraic_foundations/doc/Algebraic_foundations/Concepts/AlgebraicStructureTraits--RootOf.h -text +Algebraic_foundations/doc/Algebraic_foundations/Concepts/AlgebraicStructureTraits--Simplify.h -text +Algebraic_foundations/doc/Algebraic_foundations/Concepts/AlgebraicStructureTraits--Sqrt.h -text +Algebraic_foundations/doc/Algebraic_foundations/Concepts/AlgebraicStructureTraits--Square.h -text +Algebraic_foundations/doc/Algebraic_foundations/Concepts/AlgebraicStructureTraits--UnitPart.h -text +Algebraic_foundations/doc/Algebraic_foundations/Concepts/AlgebraicStructureTraits.h -text +Algebraic_foundations/doc/Algebraic_foundations/Concepts/EuclideanRing.h -text +Algebraic_foundations/doc/Algebraic_foundations/Concepts/ExplicitInteroperable.h -text +Algebraic_foundations/doc/Algebraic_foundations/Concepts/Field.h -text +Algebraic_foundations/doc/Algebraic_foundations/Concepts/FieldNumberType.h -text +Algebraic_foundations/doc/Algebraic_foundations/Concepts/FieldWithKthRoot.h -text +Algebraic_foundations/doc/Algebraic_foundations/Concepts/FieldWithRootOf.h -text +Algebraic_foundations/doc/Algebraic_foundations/Concepts/FieldWithSqrt.h -text +Algebraic_foundations/doc/Algebraic_foundations/Concepts/Fraction.h -text +Algebraic_foundations/doc/Algebraic_foundations/Concepts/FractionTraits.h -text +Algebraic_foundations/doc/Algebraic_foundations/Concepts/FromDoubleConstructible.h -text +Algebraic_foundations/doc/Algebraic_foundations/Concepts/FromIntConstructible.h -text +Algebraic_foundations/doc/Algebraic_foundations/Concepts/ImplicitInteroperable.h -text +Algebraic_foundations/doc/Algebraic_foundations/Concepts/IntegralDomain.h -text +Algebraic_foundations/doc/Algebraic_foundations/Concepts/IntegralDomainWithoutDivision.h -text +Algebraic_foundations/doc/Algebraic_foundations/Concepts/RealEmbeddable.h -text +Algebraic_foundations/doc/Algebraic_foundations/Concepts/RealEmbeddableTraits--Abs.h -text +Algebraic_foundations/doc/Algebraic_foundations/Concepts/RealEmbeddableTraits--Compare.h -text +Algebraic_foundations/doc/Algebraic_foundations/Concepts/RealEmbeddableTraits--IsNegative.h -text +Algebraic_foundations/doc/Algebraic_foundations/Concepts/RealEmbeddableTraits--IsPositive.h -text +Algebraic_foundations/doc/Algebraic_foundations/Concepts/RealEmbeddableTraits--IsZero.h -text +Algebraic_foundations/doc/Algebraic_foundations/Concepts/RealEmbeddableTraits--Sgn.h -text +Algebraic_foundations/doc/Algebraic_foundations/Concepts/RealEmbeddableTraits--ToDouble.h -text +Algebraic_foundations/doc/Algebraic_foundations/Concepts/RealEmbeddableTraits--ToInterval.h -text +Algebraic_foundations/doc/Algebraic_foundations/Concepts/RealEmbeddableTraits.h -text +Algebraic_foundations/doc/Algebraic_foundations/Concepts/RingNumberType.h -text +Algebraic_foundations/doc/Algebraic_foundations/Concepts/UniqueFactorizationDomain.h -text +Algebraic_foundations/doc/Algebraic_foundations/PackageDescription.txt -text +Algebraic_foundations/doc/Algebraic_foundations/fig/AlgebraicConceptHierarchy.gif -text svneol=unset#image/gif +Algebraic_foundations/doc/Algebraic_foundations/fig/AlgebraicConceptHierarchy.pdf -text svneol=unset#application/pdf +Algebraic_foundations/doc/Algebraic_foundations/fig/Algebraic_foundations.png -text svneol=unset#image/png +Algebraic_foundations/doc/Algebraic_foundations/fig/Algebraic_foundations2.png -text svneol=unset#image/png Algebraic_foundations/doc_old/Algebraic_foundations/Algebraic_foundations.txt -text Algebraic_foundations/doc_old/Algebraic_foundations/CGAL/Algebraic_structure_traits.h -text Algebraic_foundations/doc_old/Algebraic_foundations/CGAL/Coercion_traits.h -text diff --git a/Algebraic_foundations/doc/Algebraic_foundations/Algebraic_foundations.txt b/Algebraic_foundations/doc/Algebraic_foundations/Algebraic_foundations.txt new file mode 100644 index 00000000000..b0e6dce76b0 --- /dev/null +++ b/Algebraic_foundations/doc/Algebraic_foundations/Algebraic_foundations.txt @@ -0,0 +1,281 @@ + +\page ChapterAlgebraicFoundations Algebraic Foundations + +namespace CGAL { +/*! + +\mainpage Algebraic Foundations +\anchor ChapterAlgebraicFoundations + +\authors Michael Hemmer + +# Introduction # + +\cgal is targeting towards exact computation with non-linear objects, +in particular objects defined on algebraic curves and surfaces. +As a consequence types representing polynomials, algebraic extensions and +finite fields play a more important role in related implementations. +This package has been introduced to stay abreast of these changes. +Since in particular polynomials must be supported by the introduced framework +the package avoids the term number type. Instead the package distinguishes +between the algebraic structure of a type and whether a type is embeddable on +the real axis, or real embeddable for short. +Moreover, the package introduces the notion of interoperable types which +allows an explicit handling of mixed operations. + +# Algebraic Structures # + +The algebraic structure concepts introduced within this section are +motivated by their well known counterparts in traditional algebra, +but we also had to pay tribute to existing types and their restrictions. +To keep the interface minimal, +it was not desirable to cover all known algebraic structures, +e.g., we did not introduce concepts for such basic structures as groups or +exceptional structures as skew fields. + +\anchor figConceptHierarchyOfAlgebraicStructures +\image html AlgebraicConceptHierarchy.gif "Concept Hierarchy of Algebraic Structures" + +Figure \ref figConceptHierarchyOfAlgebraicStructures shows the refinement +relationship of the algebraic structure concepts. +`IntegralDomain`, `UniqueFactorizationDomain`, `EuclideanRing` and +`Field` correspond to the algebraic structures with the +same name. `FieldWithSqrt`, `FieldWithKthRoot` and +`FieldWithRootOf` are fields that in addition are closed under +the operations 'sqrt', 'k-th root' and 'real root of a polynomial', +respectively. The concept `IntegralDomainWithoutDivision` also +corresponds to integral domains in the algebraic sense, the +distinction results from the fact that some implementations of +integral domains lack the (algebraically always well defined) integral +division. +Note that `Field` refines `IntegralDomain`. This is because +most ring-theoretic notions like greatest common divisors become trivial for +`Field`s. Hence we see `Field` as a refinement of +`IntegralDomain` and not as a +refinement of one of the more advanced ring concepts. +If an algorithm wants to rely on gcd or remainder computation, it is trying +to do things it should not do with a `Field` in the first place. + +The main properties of an algebraic structure are collected in the class +`Algebraic_structure_traits`. +In particular the (most refined) concept each concrete model `AS` +fulfills is encoded in the tag +`Algebraic_structure_traits::Algebraic_category`. +An algebraic structure is at least `Assignable`, +`CopyConstructible`, `DefaultConstructible` and +`EqualityComparable`. Moreover, we require that it is +constructible from `int`. +For ease of use and since their semantic is sufficiently standard to presume +their existence, the usual arithmetic and comparison operators are required +to be realized via \cpp operator overloading. +The division operator is reserved for division in fields. +All other unary (e.g., sqrt) and binary functions +(e.g., gcd, div) must be models of the well known \stl-concepts +`AdaptableUnaryFunction` or `AdaptableBinaryFunction` +concept and local to the traits class +(e.g., `Algebraic_structure_traits::Sqrt()(x)`). +This design allows us to profit from all parts in the +\stl and its programming style and avoids the name-lookup and +two-pass template compilation problems experienced with the old design +using overloaded functions. However, for ease of use and backward +compatibility all functionality is also +accessible through global functions defined within namespace `CGAL`, +e.g., `CGAL::sqrt(x)`. This is realized via function templates using +the according functor of the traits class. For an overview see +Section \ref caf_refclassified_refernce_pages in the reference manual. + +## Tags in Algebraic Structure Traits ## + +## Algebraic Category ## + +For a type `AS`, `Algebraic_structure_traits` +provides several tags. The most important tag is the `Algebraic_category` +tag, which indicates the most refined algebraic concept the type `AS` +fulfills. The tag is one of; +`Integral_domain_without_division_tag`, `Integral_domain_tag`, +`Field_tag`, `Field_with_sqrt_tag`, `Field_with_kth_root_tag`, +`Field_with_root_of_tag`, `Unique_factorization_domain_tag`, +`Euclidean_ring_tag`, or even `Null_tag` +in case the type is not a model of an algebraic structure concept. +The tags are derived from each other such that they reflect the +hierarchy of the algebraic structure concept, e.g., +`Field_with_sqrt_tag` is derived from `Field_tag`. + +## Exact and Numerical Sensitive ## + +Moreover, `Algebraic_structure_traits` provides the tags `Is_exact` +and `Is_numerical_sensitive`, which are both `Boolean_tag`s. + +An algebraic structure is considered exact, +if all operations required by its concept are computed such that a comparison +of two algebraic expressions is always correct. + +An algebraic structure is considered as numerically sensitive, +if the performance of the type is sensitive to the condition number of an +algorithm. +Note that there is really a difference among these two notions, +e.g., the fundamental type `int` is not numerical sensitive but +considered inexact due to overflow. +Conversely, types as `leda_real` or `CORE::Expr` are exact but sensitive +to numerical issues due to the internal use of multi precision floating point +arithmetic. We expect that `Is_numerical_sensitive` is used for dispatching +of algorithms, while `Is_exact` is useful to enable assertions that can be +check for exact types only. + +Tags are very useful to dispatch between alternative implementations. +The following example illustrates a dispatch for `Field`s using overloaded +functions. The example only needs two overloads since the algebraic +category tags reflect the algebraic structure hierarchy. + +\cgalexample{algebraic_structure_dispatch.cpp} + +# Real Embeddable # + +\anchor secRealEmbeddable + +Most number types represent some subset of the real numbers. From those types +we expect functionality to compute the sign, absolute value or double +approximations. In particular we can expect an order on such a type that +reflects the order along the real axis. +All these properties are gathered in the concept `RealComparable`. +The concept is orthogonal to the algebraic structure concepts, +i.e., it is possible +that a type is a model of `RealEmbeddable` only, +since the type may just represent values on the real axis +but does not provide any arithmetic operations. + +As for algebraic structures this concept is also traits class oriented. +The main functionality related to `RealEmbeddable` is gathered in +the class `Real_embeddable_traits`. In particular, it porivdes the boolean +tag `Is_real_embeddable` indicating whether a type is a model of +`RealEmbeddable`. The comparison operators are required to be realized via +\cpp operator overloading. +All unary functions (e.g. sign, to_double) and +binary functions (e.g. compare ) are models of the \stl-concepts +`AdaptableUnaryFunction` and `AdaptableBinaryFunction` and are local +to `Real_embeddable_traits`. + +In case a type is a model of `IntegralDomainWithoutDivision` and +`RealEmbeddable` the number represented by an object of this type is +the same for arithmetic and comparison. +It follows that the ring represented by this type is a superset of the integers +and a subset of the real numbers and hence has characteristic zero. + +In case the type is a model of `Field` and `RealEmbeddable` it is a +superset of the rational numbers. + +# Real Number Types # + +Every \cgal `Kernel` comes with two real number types +(number types embeddable into the real numbers). One of them is a +`FieldNumberType`, and the other a `RingNumberType`. The +coordinates of the basic kernel objects (points, vectors, etc.) come +from one of these types (the `FieldNumberType` in case of Cartesian +kernels, and the `RingNumberType` for Homogeneous kernels). + +The concept `FieldNumberType` combines the requirements of the +concepts `Field` and `RealEmbeddable`, while +`RingNumberType` combines `IntegralDomainWithoutDivision` and +`RealEmbeddable`. Algebraically, the real number types do not form +distinct structures and are therefore not listed in the concept +hierarchy of Figure \ref figConceptHierarchyOfAlgebraicStructures. + +# Interoperability # + +This section introduces two concepts for interoperability of types, +namely `ImplicitInteroperable` and `ExplicitInteroperable`. While +`ExplicitInteroperable` is the base concept, we start with +`ImplicitInteroperable` since it is the more intuitive one. + +In general mixed operations are provided by overloaded operators and +functions or just via implicit constructor calls. +This level of interoperability is reflected by the concept +`ImplicitInteroperable`. However, within template code the result type, +or so called coercion type, of a mixed arithmetic operation may be unclear. +Therefore, the package introduces `CGAL::Coercion_traits` +giving access to the coercion type via `CGAL::Coercion_traits::Type` +for two interoperable types `A` and `B`. + +Some trivial example are `int` and `double` with coercion type double +or `CGAL::Gmpz` and `CGAL::Gmpq` with coercion type `CGAL::Gmpq`. +However, the coercion type is not necessarily one of the input types, +e.g. the coercion type of a polynomial +with integer coefficients that is multiplied by a rational type +is supposed to be a polynomial with rational coefficients. + +`CGAL::Coercion_traits` is also +required to provide a functor `CGAL::Coercion_traits::Cast()`, that +converts from an input type into the coercion type. This is in fact the core +of the more basic concept `ExplicitInteroperable`. +`ExplicitInteroperable` has been introduced to cover more complex cases +for which it is hard or impossible to guarantee implicit interoperability. +Note that this functor can be useful for `ImplicitInteroperable` types +as well, since it can be used to void redundant type conversions. + +In case two types `A` and `B` are `ExplicitInteroperable` with +coercion type `C` they are valid argument types for all binary functors +provided by `Algebraic_structure_traits` and `Real_embeddable_traits` of +`C`. This is also true for the according global functions. + +## Examples ## + +The following example illustrates how two write code for +`ExplicitInteroperable` types. + +\cgalexample{interoperable.cpp} + +The following example illustrates a dispatch for `ImplicitInteroperable` and +`ExplicitInteroperable` types. +The binary function (that just multiplies its two arguments) is supposed to +take two `ExplicitInteroperable` arguments. For `ImplicitInteroperable` +types a variant that avoids the explicit cast is selected. + +\cgalexample{implicit_interoperable_dispatch.cpp} + +# Fractions # + +Beyond the need for performing algebraic operations on objects as a +whole, there are also number types which one would like to decompose into +numerator and denominator. This does not only hold for rational numbers +as `Quotient`, `Gmpq`, `mpq_class` or `leda_rational`, but +also for compound objects as `Sqrt_extension` or `Polynomial` +which may decompose into a (scalar) +denominator and a compound numerator with a simpler coefficient type +(e.g. integer instead of rational). Often operations can be performed faster on +these denominator-free multiples. In case a type is a `Fraction` +the relevant functionality as well as the numerator and denominator +type are provided by `CGAL::Fraction_traits`. In particular +`CGAL::Fraction_traits` provides a tag `Is_fraction` that can be +used for dispatching. + +A related class is `CGAL::Rational_traits` which has been kept for backward +compatibility reasons. However, we recommend to use `Fraction_traits` since +it is more general and offers dispatching functionality. + +## Examples ## + +The following example show a simple use of `Fraction_traits`: +\cgalexample{fraction_traits.cpp} + +The following example illustrates the integralization of a vector, +i.e., the coefficient vector of a polynomial. Note that for minimizing +coefficient growth `Fraction_traits::Common_factor` is used to +compute the 'least' common multiple of the denominators. + +\cgalexample{integralize.cpp} + +# Design and Implementation History # + +The package is part of \cgal since release 3.3. Of course the package is based +on the former Number type support of CGAL. This goes back to Stefan Schirra and Andreas Fabri. But on the other hand the package is to a large extend influenced +by the experience with the number type support in Exacus \cite beh+-eeeafcs-05, +which in the main goes back to +Lutz Kettner, Susan Hert, Arno Eigenwillig and Michael Hemmer. +However, the package abstracts from the pure support for +number types that are embedded on the real axis which allows the support of +polynomials, finite fields, and algebraic extensions as well. See also related +subsequent chapters. + +*/ +} /* namespace CGAL */ + diff --git a/Algebraic_foundations/doc/Algebraic_foundations/CGAL/Algebraic_structure_traits.h b/Algebraic_foundations/doc/Algebraic_foundations/CGAL/Algebraic_structure_traits.h new file mode 100644 index 00000000000..45693374beb --- /dev/null +++ b/Algebraic_foundations/doc/Algebraic_foundations/CGAL/Algebraic_structure_traits.h @@ -0,0 +1,162 @@ +namespace CGAL { + +/*! +\ingroup PkgAlgebraicFoundations + +An instance of `Algebraic_structure_traits` is a model of `AlgebraicStructureTraits`, where T is the associated type. + +\models ::AlgebraicStructureTraits + +*/ +template< typename T > +class Algebraic_structure_traits { + +}; /* end Algebraic_structure_traits */ +} /* end namespace CGAL */ + +namespace CGAL { + +/*! +\ingroup PkgAlgebraicFoundations + +\anchor Euclidean_ring_tag + +Tag indicating that a type is a model of the +`EuclideanRing` concept. + +\models ::DefaultConstructible + +\sa `EuclideanRing` +\sa `AlgebraicStructureTraits` + +*/ + +class Euclidean_ring_tag : public Unique_factorization_domain_tag { + +}; /* end Euclidean_ring_tag */ + +/*! +\ingroup PkgAlgebraicFoundations + +\anchor Field_tag + +Tag indicating that a type is a model of the `Field` concept. + +\models ::DefaultConstructible + +\sa `Field` +\sa `AlgebraicStructureTraits` + +*/ + +class Field_tag : public Integral_domain_tag { + +}; /* end Field_tag */ + +/*! +\ingroup PkgAlgebraicFoundations + +\anchor Field_with_kth_root_tag + +Tag indicating that a type is a model of the `FieldWithKthRoot` concept. + +\models ::DefaultConstructible + +\sa `FieldWithKthRoot` +\sa `AlgebraicStructureTraits` + +*/ + +class Field_with_kth_root_tag : public Field_with_sqrt_tag { + +}; /* end Field_with_kth_root_tag */ + +/*! +\ingroup PkgAlgebraicFoundations + +\anchor Field_with_root_of_tag + +Tag indicating that a type is a model of the `FieldWithRootOf` concept. + +\models ::DefaultConstructible + +\sa `FieldWithRootOf` +\sa `AlgebraicStructureTraits` + +*/ + +class Field_with_root_of_tag : public Field_with_kth_root_tag { + +}; /* end Field_with_root_of_tag */ + +/*! +\ingroup PkgAlgebraicFoundations + +\anchor Field_with_sqrt_tag + +Tag indicating that a type is a model of the `FieldWithSqrt` concept. + +\models ::DefaultConstructible + +\sa `FieldWithSqrt` +\sa `AlgebraicStructureTraits` + +*/ + +class Field_with_sqrt_tag : public Field_tag { + +}; /* end Field_with_sqrt_tag */ + +/*! +\ingroup PkgAlgebraicFoundations + +\anchor Integral_domain_tag + +Tag indicating that a type is a model of the `IntegralDomain` concept. + +\models ::DefaultConstructible + +\sa `IntegralDomain` +\sa `AlgebraicStructureTraits` + +*/ + +class Integral_domain_tag : public Integral_domain_without_division_tag { + +}; /* end Integral_domain_tag */ + +/*! +\ingroup PkgAlgebraicFoundations + +\anchor Integral_domain_without_division_tag + +Tag indicating that a type is a model of the `IntegralDomainWithoutDivision` concept. + +\models ::DefaultConstructible + +\sa `IntegralDomainWithoutDivision` + +*/ + +class Integral_domain_without_division_tag { + +}; /* end Integral_domain_without_division_tag */ + +/*! +\ingroup PkgAlgebraicFoundations + +\anchor Unique_factorization_domain_tag + +Tag indicating that a type is a model of the `UniqueFactorizationDomain` concept. + +\models ::DefaultConstructible + +\sa `UniqueFactorizationDomain` +\sa `AlgebraicStructureTraits` + +*/ + +class Unique_factorization_domain_tag : public Integral_domain_tag { + +}; /* end Unique_factorization_domain_tag */ +} /* end namespace CGAL */ diff --git a/Algebraic_foundations/doc/Algebraic_foundations/CGAL/Coercion_traits.h b/Algebraic_foundations/doc/Algebraic_foundations/CGAL/Coercion_traits.h new file mode 100644 index 00000000000..eff58a59a6a --- /dev/null +++ b/Algebraic_foundations/doc/Algebraic_foundations/CGAL/Coercion_traits.h @@ -0,0 +1,52 @@ + +namespace CGAL { + +/*! +\ingroup PkgAlgebraicFoundations + +An instance of `Coercion_traits` reflects the type coercion of the types +A and B, it is symmetric in the two template arguments. + +\sa `ExplicitInteroperable` +\sa `ImplicitInteroperable` + +*/ +template< typename A, typename B > +class Coercion_traits { +public: + +/// \name Types +/// @{ + +/*! +Tag indicating whether the two types A and B are a model of `ExplicitInteroperable` + +This is either `CGAL::Tag_true` or `CGAL::Tag_false`. +*/ +typedef Hidden_type Are_explicit_interoperable; + +/*! +Tag indicating whether the two types A and B are a model of `ImplicitInteroperable` + +This is either `CGAL::Tag_true` or `CGAL::Tag_false`. +*/ +typedef Hidden_type Are_implicit_interoperable; + +/*! +The coercion type of `A` and `B`. + +In case A and B are not `ExplicitInteroperable` this is undefined. +*/ +typedef Hidden_type Type; + +/*! +A model of the `AdaptableFunctor` concept, providing the conversion of `A` or `B` to `Type`. + +In case A and B are not `ExplicitInteroperable` this is undefined. +*/ +typedef Hidden_type Cast; + +/// @} + +}; /* end Coercion_traits */ +} /* end namespace CGAL */ diff --git a/Algebraic_foundations/doc/Algebraic_foundations/CGAL/Fraction_traits.h b/Algebraic_foundations/doc/Algebraic_foundations/CGAL/Fraction_traits.h new file mode 100644 index 00000000000..946e802ca2a --- /dev/null +++ b/Algebraic_foundations/doc/Algebraic_foundations/CGAL/Fraction_traits.h @@ -0,0 +1,19 @@ +namespace CGAL { + +/*! +\ingroup PkgAlgebraicFoundations + +An instance of `Fraction_traits` is a model of `FractionTraits`, +where `T` is the associated type. + +\models ::FractionTraits + +*/ +template< typename T > +class Fraction_traits { +public: + +/// @} + +}; /* end Fraction_traits */ +} /* end namespace CGAL */ diff --git a/Algebraic_foundations/doc/Algebraic_foundations/CGAL/Real_embeddable_traits.h b/Algebraic_foundations/doc/Algebraic_foundations/CGAL/Real_embeddable_traits.h new file mode 100644 index 00000000000..2620c92470a --- /dev/null +++ b/Algebraic_foundations/doc/Algebraic_foundations/CGAL/Real_embeddable_traits.h @@ -0,0 +1,16 @@ + +namespace CGAL { + +/*! +\ingroup PkgAlgebraicFoundations + +An instance of `Real_embeddable_traits` is a model of `RealEmbeddableTraits`, where T is the associated type. + +\models ::RealEmbeddableTraits + +*/ +template< typename T > +class Real_embeddable_traits { + +}; /* end Real_embeddable_traits */ +} /* end namespace CGAL */ diff --git a/Algebraic_foundations/doc/Algebraic_foundations/CGAL/number_utils.h b/Algebraic_foundations/doc/Algebraic_foundations/CGAL/number_utils.h new file mode 100644 index 00000000000..95da8f04182 --- /dev/null +++ b/Algebraic_foundations/doc/Algebraic_foundations/CGAL/number_utils.h @@ -0,0 +1,514 @@ +namespace CGAL { + +/*! +\ingroup PkgAlgebraicFoundations + +The template function `abs` returns the absolute value of a number. + +The function is defined if the argument type +is a model of the `RealEmbeddable` concept. + +\sa `RealEmbeddable` +\sa `RealEmbeddableTraits::Abs` + +*/ +template NT abs(const NT& x); + +} /* namespace CGAL */ + +namespace CGAL { + +/*! +\ingroup PkgAlgebraicFoundations + +The template function `compare` compares the first argument with respect to +the second, i.e. it returns `CGAL::LARGER` if \f$ x\f$ is larger then \f$ y\f$. + +In case the argument types `NT1` and `NT2` differ, +`compare` is performed with the semantic of the type determined via +`Coercion_traits`. +The function is defined if this type +is a model of the `RealEmbeddable` concept. + +The `result_type` is convertible to `CGAL::Comparison_result`. + +\sa `RealEmbeddable` +\sa `RealEmbeddableTraits::Compare` +*/ +template +result_type compare(const NT &x, const NT &y); + +} /* namespace CGAL */ + +namespace CGAL { + +/*! +\ingroup PkgAlgebraicFoundations + +The function `div` computes the integral quotient of division +with remainder. + +In case the argument types `NT1` and `NT2` differ, +the `result_type` is determined via `Coercion_traits`. + +Thus, the `result_type` is well defined if `NT1` and `NT2` +are a model of `ExplicitInteroperable`. + +The actual `div` is performed with the semantic of that type. + +The function is defined if `result_type` +is a model of the `EuclideanRing` concept. + +\sa `EuclideanRing` +\sa `AlgebraicStructureTraits::Div` +\sa CGAL::mod +\sa CGAL::div_mod + +*/ +template< class NT1, class NT2> +result_type +div(const NT1& x, const NT2& y); + +} /* namespace CGAL */ + +namespace CGAL { + +/*! +\ingroup PkgAlgebraicFoundations + +computes the quotient \f$ q\f$ and remainder \f$ r\f$, such that \f$ x = q*y + r\f$ +and \f$ r\f$ minimal with respect to the Euclidean Norm of the +`result_type`. + +The function `div_mod` computes the integral quotient and remainder of +division with remainder. + +In case the argument types `NT1` and `NT2` differ, +the `result_type` is determined via `Coercion_traits`. + +Thus, the `result_type` is well defined if `NT1` and `NT2` +are a model of `ExplicitInteroperable`. + +The actual `div_mod` is performed with the semantic of that type. + +The function is defined if `result_type` +is a model of the `EuclideanRing` concept. + +\sa `EuclideanRing` +\sa `AlgebraicStructureTraits::DivMod` +\sa CGAL::mod +\sa CGAL::div + +*/ +template +void +div_mod(const NT1& x, const NT2& y, result_type& q, result_type& r); + +} /* namespace CGAL */ + +namespace CGAL { + +/*! +\ingroup PkgAlgebraicFoundations + +The function `gcd` computes the greatest common divisor of two values. + +In case the argument types `NT1` and `NT2` differ, +the `result_type` is determined via `Coercion_traits`. + +Thus, the `result_type` is well defined if `NT1` and `NT2` +are a model of `ExplicitInteroperable`. + +The actual `gcd` is performed with the semantic of that type. + +The function is defined if `result_type` +is a model of the `UniqueFactorizationDomain` concept. + +\sa `UniqueFactorizationDomain` +\sa `AlgebraicStructureTraits::Gcd` + +*/ +template result_type +gcd(const NT1& x, const NT2& y); + +} /* namespace CGAL */ + +namespace CGAL { + +/*! +\ingroup PkgAlgebraicFoundations + +The function `integral_division` (a.k.a. exact division or division without remainder) +maps ring elements \f$ (x,y)\f$ to ring element \f$ z\f$ such that \f$ x = yz\f$ if such a \f$ z\f$ +exists (i.e. if \f$ x\f$ is divisible by \f$ y\f$). Otherwise the effect of invoking +this operation is undefined. Since the ring represented is an integral domain, +\f$ z\f$ is uniquely defined if it exists. + +In case the argument types `NT1` and `NT2` differ, +the `result_type` is determined via `Coercion_traits`. + +Thus, the `result_type` is well defined if `NT1` and `NT2` +are a model of `ExplicitInteroperable`. + +The actual `integral_division` is performed with the semantic of that type. + +The function is defined if `result_type` +is a model of the `IntegralDomain` concept. + +\sa `IntegralDomain` +\sa `AlgebraicStructureTraits::IntegralDivision` + +*/ +template result_type +integral_division(const NT1& x, const NT2& y); + +} /* namespace CGAL */ + +namespace CGAL { + +/*! +\ingroup PkgAlgebraicFoundations + +The function `inverse` returns the inverse element with respect to multiplication. + +The function is defined if the argument type +is a model of the `Field` concept. + +\pre \f$ x \neq0\f$. + +\sa `Field` +\sa `AlgebraicStructureTraits::Inverse` + +*/ +template NT inverse(const NT& x); + +} /* namespace CGAL */ + +namespace CGAL { + +/*! +\ingroup PkgAlgebraicFoundations + +The template function `is_negative` determines if a value is negative or not. +The function is defined if the argument type +is a model of the `RealEmbeddable` concept. + +The `result_type` is convertible to `bool`. + +\sa `RealEmbeddable` +\sa `RealEmbeddableTraits::IsNegative` + +*/ +result_type is_negative(const NT& x); + +} /* namespace CGAL */ + +namespace CGAL { + +/*! +\ingroup PkgAlgebraicFoundations + +The function `is_one` determines if a value is equal to 1 or not. + +The function is defined if the argument type +is a model of the `IntegralDomainWithoutDivision` concept. + +The `result_type` is convertible to `bool`. + +\sa `IntegralDomainWithoutDivision` +\sa `AlgebraicStructureTraits::IsOne` + +*/ +template result_type is_one(const NT& x); + +} /* namespace CGAL */ + +namespace CGAL { + +/*! +\ingroup PkgAlgebraicFoundations + +The template function `is_positive` determines if a value is positive or not. +The function is defined if the argument type +is a model of the `RealEmbeddable` concept. + +The `result_type` is convertible to `bool`. + +\sa `RealEmbeddable` +\sa `RealEmbeddableTraits::IsPositive` + +*/ +result_type is_positive(const NT& x); + +} /* namespace CGAL */ + +namespace CGAL { + +/*! +\ingroup PkgAlgebraicFoundations + +An ring element \f$ x\f$ is said to be a square iff there exists a ring element +\f$ y\f$ such +that \f$ x= y*y\f$. In case the ring is a `UniqueFactorizationDomain`, +\f$ y\f$ is uniquely defined up to multiplication by units. + +The function `is_square` is available if +`Algebraic_structure_traits::Is_square` is not the `CGAL::Null_functor`. + +The `result_type` is convertible to `bool`. + +\sa `UniqueFactorizationDomain` +\sa `AlgebraicStructureTraits::IsSquare` + +*/ +template result_type is_square(const NT& x); + +/*! +\ingroup PkgAlgebraicFoundations + +An ring element \f$ x\f$ is said to be a square iff there exists a ring element +\f$ y\f$ such +that \f$ x= y*y\f$. In case the ring is a `UniqueFactorizationDomain`, +\f$ y\f$ is uniquely defined up to multiplication by units. + +The function `is_square` is available if +`Algebraic_structure_traits::Is_square` is not the `CGAL::Null_functor`. + +The `result_type` is convertible to `bool`. + +\sa `UniqueFactorizationDomain` +\sa `AlgebraicStructureTraits::IsSquare` + +*/ +template result_type is_square(const NT& x, NT& y); + +} /* namespace CGAL */ + +namespace CGAL { + +/*! +\ingroup PkgAlgebraicFoundations + +The function `is_zero` determines if a value is equal to 0 or not. + +The function is defined if the argument type +is a model of the `RealEmbeddable` or of +the `IntegralDomainWithoutDivision` concept. + +The `result_type` is convertible to `bool`. + +\sa `RealEmbeddable` +\sa `RealEmbeddableTraits::IsZero` +\sa `IntegralDomainWithoutDivision` +\sa `AlgebraicStructureTraits::IsZero` +*/ +template result_type is_zero(const NT& x); + +} /* namespace CGAL */ + +namespace CGAL { + +/*! +\ingroup PkgAlgebraicFoundations + +The function `kth_root` returns the k-th root of a value. + +The function is defined if the second argument type +is a model of the `FieldWithKthRoot` concept. + +\sa `FieldWithKthRoot` +\sa `AlgebraicStructureTraits::KthRoot` + +*/ +template NT kth_root(int k, const NT& x); + +} /* namespace CGAL */ + +namespace CGAL { + +/*! +\ingroup PkgAlgebraicFoundations + +The function `mod` computes the remainder of division with remainder. + +In case the argument types `NT1` and `NT2` differ, +the `result_type` is determined via `Coercion_traits`. + +Thus, the `result_type` is well defined if `NT1` and `NT2` +are a model of `ExplicitInteroperable`. + +The actual `mod` is performed with the semantic of that type. + +The function is defined if `result_type` +is a model of the `EuclideanRing` concept. + +\sa `EuclideanRing` +\sa `AlgebraicStructureTraits::DivMod` +\sa CGAL::div_mod +\sa CGAL::div + +*/ +template< class NT1, class NT2> +result_type +mod(const NT1& x, const NT2& y); + +} /* namespace CGAL */ + +namespace CGAL { + +/*! +\ingroup PkgAlgebraicFoundations + +returns the k-th real root of the univariate polynomial, which is +defined by the iterator range, where begin refers to the constant +term. + +The function `root_of` computes a real root of a square-free univariate +polynomial. + +The function is defined if the value type, `NT`, +of the iterator range is a model of the `FieldWithRootOf` concept. + +\pre The polynomial is square-free. + +\sa `FieldWithRootOf` +\sa `AlgebraicStructureTraits::RootOf` + +*/ +template NT +root_of(int k, InputIterator begin, InputIterator end); + +} /* namespace CGAL */ + +namespace CGAL { + +/*! +\ingroup PkgAlgebraicFoundations + +The template function `sign` returns the sign of its argument. + +The function is defined if the argument type +is a model of the `RealEmbeddable` concept. + +The `result_type` is convertible to `CGAL::Sign`. + +\sa `RealEmbeddable` +\sa `RealEmbeddableTraits::Sgn` + +*/ +template result_type sign(const NT& x); + +} /* namespace CGAL */ + +namespace CGAL { + +/*! +\ingroup PkgAlgebraicFoundations + +The function `simplify` may simplify a given object. + +The function is defined if the argument type +is a model of the `IntegralDomainWithoutDivision` concept. + +\sa `IntegralDomainWithoutDivision` +\sa `AlgebraicStructureTraits::Simplify` + +*/ +template void simplify(const NT& x); + +} /* namespace CGAL */ + +namespace CGAL { + +/*! +\ingroup PkgAlgebraicFoundations + +The function `sqrt` returns the square root of a value. + +The function is defined if the argument type +is a model of the `FieldWithSqrt` concept. + +\sa `FieldWithSqrt` +\sa `AlgebraicStructureTraits::Sqrt` + +*/ +template NT sqrt(const NT& x); + +} /* namespace CGAL */ + +namespace CGAL { + +/*! +\ingroup PkgAlgebraicFoundations + +The function `square` returns the square of a number. + +The function is defined if the argument type +is a model of the `IntegralDomainWithoutDivision` concept. + +\sa `IntegralDomainWithoutDivision` +\sa `AlgebraicStructureTraits::Square` + +*/ +template NT square(const NT& x); + +} /* namespace CGAL */ + +namespace CGAL { + +/*! +\ingroup PkgAlgebraicFoundations + +The template function `to_double` returns an double approximation of a number. +The function is defined if the argument type +is a model of the `RealEmbeddable` concept. + +Remark: In order to control the quality of approximation one has to resort to methods that are specific to NT. There are no general guarantees whatsoever. + +\sa `RealEmbeddable` +\sa `RealEmbeddableTraits::ToDouble` + +*/ +template double to_double(const NT& x); + +} /* namespace CGAL */ + +namespace CGAL { + +/*! +\ingroup PkgAlgebraicFoundations + +The template function `to_interval` computes for a given real embeddable +number \f$ x\f$ a double interval containing \f$ x\f$. +This interval is represented by a `std::pair`. +The function is defined if the argument type +is a model of the `RealEmbeddable` concept. + +\sa `RealEmbeddable` +\sa `RealEmbeddableTraits::ToInterval` + +*/ +template +std::pair to_interval(const NT& x); + +} /* namespace CGAL */ + +namespace CGAL { + +/*! +\ingroup PkgAlgebraicFoundations + +The function `unit_part` computes the unit part of a given ring +element. + +The function is defined if the argument type +is a model of the `IntegralDomainWithoutDivision` concept. + +\sa `IntegralDomainWithoutDivision` +\sa `AlgebraicStructureTraits::UnitPart` + +*/ +template NT unit_part(const NT& x); + +} /* namespace CGAL */ + diff --git a/Algebraic_foundations/doc/Algebraic_foundations/Classified.txt b/Algebraic_foundations/doc/Algebraic_foundations/Classified.txt new file mode 100644 index 00000000000..d88552ef4e5 --- /dev/null +++ b/Algebraic_foundations/doc/Algebraic_foundations/Classified.txt @@ -0,0 +1,206 @@ +/*! +\page classified_ref +\authors Michael Hemmer + +\section caf_refclassified_refernce_pages Classified Reference Pages + +## Algebraic Structures ## + +## Concepts ## + +`IntegralDomainWithoutDivision` + +`IntegralDomain` + +`UniqueFactorizationDomain` + +`EuclideanRing` + +`Field` + +`FieldWithSqrt` + +`FieldWithKthRoot` + +`FieldWithRootOf` + + + +`AlgebraicStructureTraits` + +`AlgebraicStructureTraits::IsZero` + +`AlgebraicStructureTraits::IsOne` + +`AlgebraicStructureTraits::Square` + +`AlgebraicStructureTraits::Simplify` + +`AlgebraicStructureTraits::UnitPart` + +`AlgebraicStructureTraits::IntegralDivision` + +`AlgebraicStructureTraits::Divides` + +`AlgebraicStructureTraits::Gcd` + +`AlgebraicStructureTraits::DivMod` + +`AlgebraicStructureTraits::Div` + +`AlgebraicStructureTraits::Mod` + +`AlgebraicStructureTraits::Inverse` + +`AlgebraicStructureTraits::Sqrt` + +`AlgebraicStructureTraits::IsSquare` + +`AlgebraicStructureTraits::KthRoot` + +`AlgebraicStructureTraits::RootOf` + +## Classes ## + +\ref ::CGAL::Algebraic_structure_traits + +\ref ::CGAL::Integral_domain_without_division_tag + +\ref ::CGAL::Integral_domain_tag + +\ref ::CGAL::Field_tag + +\ref ::CGAL::Field_with_sqrt_tag + +\ref ::CGAL::Unique_factorization_domain_tag + +\ref ::CGAL::Euclidean_ring_tag + +## Global Functions ## + +\ref ::CGAL::is_zero + +\ref ::CGAL::is_one + +\ref ::CGAL::square + +\ref ::CGAL::simplify + +\ref ::CGAL::unit_part + +\ref ::CGAL::integral_division + +\ref ::CGAL::is_square + +\ref ::CGAL::gcd + +\ref ::CGAL::div_mod + +\ref ::CGAL::div + +\ref ::CGAL::mod + +\ref ::CGAL::inverse + +\ref ::CGAL::sqrt + +\ref ::CGAL::kth_root + +\ref ::CGAL::root_of + +## Real Embeddable ## + +\anchor caf_refreal_embeddable_concept + +## Concepts ## + +`RealEmbeddable` + + + +`RealEmbeddableTraits` + +`RealEmbeddableTraits::IsZero` + +`RealEmbeddableTraits::Abs` + +`RealEmbeddableTraits::Sgn` + +`RealEmbeddableTraits::IsPositive` + +`RealEmbeddableTraits::IsNegative` + +`RealEmbeddableTraits::Compare` + +`RealEmbeddableTraits::ToDouble` + +`RealEmbeddableTraits::ToInterval` + +## Classes ## + +\ref ::CGAL::Real_embeddable_traits + +## Global Functions ## + +\ref ::CGAL::is_zero + +\ref ::CGAL::abs + +\ref ::CGAL::sign + +\ref ::CGAL::is_positive + +\ref ::CGAL::is_negative + +\ref ::CGAL::compare + +\ref ::CGAL::to_double + +\ref ::CGAL::to_interval + +## Real Number Types ## + +## Concepts ## + +`RingNumberType` + +`FieldNumberType` + +## Interoperability ## + +## Concepts ## + +`ExplicitInteroperable` + +`ImplicitInteroperable` + +## Classes ## + +\ref ::CGAL::Coercion_traits + +## Fractions ## + +## Concepts ## + +`Fraction` + +`FractionTraits` + +`FractionTraits::Decompose` + +`FractionTraits::Compose` + +`FractionTraits::CommonFactor` + +## Classes ## + +\ref ::CGAL::Fraction_traits + +## Miscellaneous ## + +## Concepts ## + +`FromIntConstructible` + +`FromDoubleConstructible` +*/ diff --git a/Algebraic_foundations/doc/Algebraic_foundations/Concepts/AlgebraicStructureTraits--Div.h b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/AlgebraicStructureTraits--Div.h new file mode 100644 index 00000000000..a995a001b68 --- /dev/null +++ b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/AlgebraicStructureTraits--Div.h @@ -0,0 +1,58 @@ + +/*! +\ingroup PkgAlgebraicFoundationsConcepts +\cgalconcept + +`AdaptableBinaryFunction` computes the integral quotient of division +with remainder. + +\refines ::AdaptableBinaryFunction + +\sa ::AlgebraicStructureTraits +\sa ::AlgebraicStructureTraits::Mod +\sa ::AlgebraicStructureTraits::DivMod + +*/ + +class AlgebraicStructureTraits::Div { +public: + +/// \name Types +/// @{ + +/*! +Is `AlgebraicStructureTraits::Type`. +*/ +typedef Hidden_type result_type; + +/*! +Is `AlgebraicStructureTraits::Type`. +*/ +typedef Hidden_type first_argument; + +/*! +Is `AlgebraicStructureTraits::Type`. +*/ +typedef Hidden_type second_argument; + +/// @} + +/// \name Operations +/// @{ + +/*! + +*/ +result_type operator()(first_argument_type x, +second_argument_type y); + +/*! +This operator is defined if `NT1` and `NT2` are `ExplicitInteroperable` +with coercion type `AlgebraicStructureTraits::Type`. +*/ +template result_type operator()(NT1 x, NT2 y); + +/// @} + +}; /* end AlgebraicStructureTraits::Div */ + diff --git a/Algebraic_foundations/doc/Algebraic_foundations/Concepts/AlgebraicStructureTraits--DivMod.h b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/AlgebraicStructureTraits--DivMod.h new file mode 100644 index 00000000000..ea7ef3bdb6d --- /dev/null +++ b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/AlgebraicStructureTraits--DivMod.h @@ -0,0 +1,255 @@ + +/*! +\ingroup PkgAlgebraicFoundationsConcepts +\cgalconcept + +`AdaptableFunctor` computes both integral quotient and remainder +of division with remainder. The quotient \f$ q\f$ and remainder \f$ r\f$ are computed +such that \f$ x = q*y + r\f$ and \f$ |r| < |y|\f$ with respect to the proper integer norm of +the represented ring. +\footnote{For integers this norm is the absolute value. +For univariate polynomials this norm is the degree.} +In particular, \f$ r\f$ is chosen to be \f$ 0\f$ if possible. +Moreover, we require \f$ q\f$ to be minimized with respect to the proper integer norm. + +Note that the last condition is needed to ensure a unique computation of the +pair \f$ (q,r)\f$. However, an other option is to require minimality for \f$ |r|\f$, +with the advantage that +a mod(x,y) operation would return the unique representative of the +residue class of \f$ x\f$ with respect to \f$ y\f$, e.g. \f$ mod(2,3)\f$ should return \f$ -1\f$. +But this conflicts with nearly all current implementation +of integer types. From there, we decided to stay conform with common +implementations and require \f$ q\f$ to be computed as \f$ x/y\f$ rounded towards zero. + +The following table illustrates the behavior for integers: + + + +
+ + + + + + + + + +
+
+x + +y + +q + +r +
+
+3 + +3 + +1 + +0 +
+2 + +3 + +0 + +2 +
+1 + +3 + +0 + +1 +
+0 + +3 + +0 + +0 +
+-1 + +3 + +0 + +-1 +
+-2 + +3 + +0 + +-2 +
+-3 + +3 + +-1 + +0 +
+
+ +		 +- + + + + + + + + + + +
+
+x + +y + +q + +r +
+
+3 + +-3 + +-1 + +0 +
+2 + +-3 + +0 + +2 +
+1 + +-3 + +0 + +1 +
+0 + +-3 + +0 + +0 +
+-1 + +-3 + +0 + +-1 +
+-2 + +-3 + +0 + +-2 +
+-3 + +-3 + +1 + +0 +
+
+ +
+ +\refines ::AdaptableFunctor + +\sa ::AlgebraicStructureTraits +\sa ::AlgebraicStructureTraits::Mod +\sa ::AlgebraicStructureTraits::Div + +*/ + +class AlgebraicStructureTraits::DivMod { +public: + +/// \name Types +/// @{ + +/*! +Is void. +*/ +typedef Hidden_type result_type; + +/*! +Is `AlgebraicStructureTraits::Type`. +*/ +typedef Hidden_type first_argument_type; + +/*! +Is `AlgebraicStructureTraits::Type`. +*/ +typedef Hidden_type second_argument_type; + +/*! +Is `AlgebraicStructureTraits::Type&`. +*/ +typedef Hidden_type third_argument_type; + +/*! +Is `AlgebraicStructureTraits::Type&`. +*/ +typedef Hidden_type fourth_argument_type; + +/// @} + +/// \name Operations +/// @{ + +/*! + +computes the quotient \f$ q\f$ and remainder \f$ r\f$, such that \f$ x = q*y + r\f$ +and \f$ r\f$ minimal with respect to the Euclidean Norm on +`Type`. +*/ +result_type operator()( first_argument_type x, +second_argument_type y, +third_argument_type q, +fourth_argument_type r); + +/*! +This operator is defined if `NT1` and `NT2` are `ExplicitInteroperable` +with coercion type `AlgebraicStructureTraits::Type`. +*/ +template result_type +operator()(NT1 x, NT2 y, third_argument_type q, fourth_argument_type r); + +/// @} + +}; /* end AlgebraicStructureTraits::DivMod */ + diff --git a/Algebraic_foundations/doc/Algebraic_foundations/Concepts/AlgebraicStructureTraits--Divides.h b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/AlgebraicStructureTraits--Divides.h new file mode 100644 index 00000000000..a8a6e68faed --- /dev/null +++ b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/AlgebraicStructureTraits--Divides.h @@ -0,0 +1,71 @@ + +/*! +\ingroup PkgAlgebraicFoundationsConcepts +\cgalconcept + +`AdaptableBinaryFunction`, +returns true if the first argument divides the second argument. + +Integral division (a.k.a. exact division or division without remainder) maps +ring elements \f$ (n,d)\f$ to ring element \f$ c\f$ such that \f$ n = dc\f$ if such a \f$ c\f$ +exists. In this case it is said that \f$ d\f$ divides \f$ n\f$. + +This functor is required to provide two operators. The first operator takes two +arguments and returns true if the first argument divides the second argument. +The second operator returns \f$ c\f$ via the additional third argument. + +\refines ::AdaptableBinaryFunction + +\sa ::AlgebraicStructureTraits +\sa ::AlgebraicStructureTraits::IntegralDivision + +*/ + +class AlgebraicStructureTraits::Divides { +public: + +/// \name Types +/// @{ + +/*! +Is `AlgebraicStructureTraits::Boolean`. +*/ +typedef Hidden_type result_type; + +/*! +Is `AlgebraicStructureTraits::Type`. +*/ +typedef Hidden_type first_argument; + +/*! +Is `AlgebraicStructureTraits::Type`. +*/ +typedef Hidden_type second_argument; + +/// @} + +/// \name Operations +/// @{ + +/*! +Computes whether \f$ d\f$ divides \f$ n\f$. +*/ +result_type operator()(first_argument_type d, +second_argument_type n); + +/*! + +Computes whether \f$ d\f$ divides \f$ n\f$. +Moreover it computes \f$ c\f$ if \f$ d\f$ divides \f$ n\f$, +otherwise the value of \f$ c\f$ is undefined. + +*/ +result_type operator()( +first_argument_type d, +second_argument_type n, +AlgebraicStructureTraits::Type& c); + +/// @} + +}; /* end AlgebraicStructureTraits::Divides */ + diff --git a/Algebraic_foundations/doc/Algebraic_foundations/Concepts/AlgebraicStructureTraits--Gcd.h b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/AlgebraicStructureTraits--Gcd.h new file mode 100644 index 00000000000..dca4615171b --- /dev/null +++ b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/AlgebraicStructureTraits--Gcd.h @@ -0,0 +1,65 @@ + +/*! +\ingroup PkgAlgebraicFoundationsConcepts +\cgalconcept + +`AdaptableBinaryFunction` providing the gcd. + +The greatest common divisor (\f$ gcd\f$) of ring elements \f$ x\f$ and \f$ y\f$ is the unique +ring element \f$ d\f$ (up to a unit) with the property that any common divisor of +\f$ x\f$ and \f$ y\f$ also divides \f$ d\f$. (In other words: \f$ d\f$ is the greatest lower bound +of \f$ x\f$ and \f$ y\f$ in the partial order of divisibility.) We demand the \f$ gcd\f$ to be +unit-normal (i.e. have unit part 1). + +\f$ gcd(0,0)\f$ is defined as \f$ 0\f$, since \f$ 0\f$ is the greatest element with respect +to the partial order of divisibility. This is because an element \f$ a \in R\f$ is said to divide \f$ b \in R\f$, iff \f$ \exists r \in R\f$ such that \f$ a \cdot r = b\f$. +Thus, \f$ 0\f$ is divided by every element of the Ring, in particular by itself. + +\refines ::AdaptableBinaryFunction + +\sa ::AlgebraicStructureTraits + +*/ + +class AlgebraicStructureTraits::Gcd { +public: + +/// \name Types +/// @{ + +/*! +Is `AlgebraicStructureTraits::Type`. +*/ +typedef Hidden_type result_type; + +/*! +Is `AlgebraicStructureTraits::Type`. +*/ +typedef Hidden_type first_argument; + +/*! +Is `AlgebraicStructureTraits::Type`. +*/ +typedef Hidden_type second_argument; + +/// @} + +/// \name Operations +/// @{ + +/*! +returns \f$ gcd(x,y)\f$. +*/ +result_type operator()(first_argument_type x, +second_argument_type y); + +/*! +This operator is defined if `NT1` and `NT2` are `ExplicitInteroperable` +with coercion type `AlgebraicStructureTraits::Type`. +*/ +template result_type operator()(NT1 x, NT2 y); + +/// @} + +}; /* end AlgebraicStructureTraits::Gcd */ + diff --git a/Algebraic_foundations/doc/Algebraic_foundations/Concepts/AlgebraicStructureTraits--IntegralDivision.h b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/AlgebraicStructureTraits--IntegralDivision.h new file mode 100644 index 00000000000..3184cd50a98 --- /dev/null +++ b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/AlgebraicStructureTraits--IntegralDivision.h @@ -0,0 +1,62 @@ + +/*! +\ingroup PkgAlgebraicFoundationsConcepts +\cgalconcept + +`AdaptableBinaryFunction` providing an integral division. + +Integral division (a.k.a. exact division or division without remainder) maps +ring elements \f$ (x,y)\f$ to ring element \f$ z\f$ such that \f$ x = yz\f$ if such a \f$ z\f$ +exists (i.e. if \f$ x\f$ is divisible by \f$ y\f$). Otherwise the effect of invoking +this operation is undefined. Since the ring represented is an integral domain, +\f$ z\f$ is uniquely defined if it exists. + +\refines ::AdaptableBinaryFunction + +\sa ::AlgebraicStructureTraits +\sa ::AlgebraicStructureTraits::Divides + +*/ + +class AlgebraicStructureTraits::IntegralDivision { +public: + +/// \name Types +/// @{ + +/*! +Is `AlgebraicStructureTraits::Type`. +*/ +typedef Hidden_type result_type; + +/*! +Is `AlgebraicStructureTraits::Type`. +*/ +typedef Hidden_type first_argument; + +/*! +Is `AlgebraicStructureTraits::Type`. +*/ +typedef Hidden_type second_argument; + +/// @} + +/// \name Operations +/// @{ + +/*! +returns \f$ x/y\f$, this is an integral division. +*/ +result_type operator()(first_argument_type x, +second_argument_type y); + +/*! +This operator is defined if `NT1` and `NT2` are `ExplicitInteroperable` +with coercion type `AlgebraicStructureTraits::Type`. +*/ +template result_type operator()(NT1 x, NT2 y); + +/// @} + +}; /* end AlgebraicStructureTraits::IntegralDivision */ + diff --git a/Algebraic_foundations/doc/Algebraic_foundations/Concepts/AlgebraicStructureTraits--Inverse.h b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/AlgebraicStructureTraits--Inverse.h new file mode 100644 index 00000000000..1d827acbf57 --- /dev/null +++ b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/AlgebraicStructureTraits--Inverse.h @@ -0,0 +1,46 @@ + +/*! +\ingroup PkgAlgebraicFoundationsConcepts +\cgalconcept + +`AdaptableUnaryFunction` providing the inverse element with +respect to multiplication of a `Field`. + +\refines ::AdaptableUnaryFunction + +\sa ::AlgebraicStructureTraits + +*/ + +class AlgebraicStructureTraits::Inverse { +public: + +/// \name Types +/// @{ + +/*! +Is `AlgebraicStructureTraits::Type`. +*/ +typedef Hidden_type result_type; + +/*! +Is `AlgebraicStructureTraits::Type`. +*/ +typedef Hidden_type argument_type; + +/// @} + +/// \name Operations +/// @{ + +/*! +returns the inverse element of \f$ x\f$ with respect to multiplication. +\pre \f$ x \neq0\f$. + +*/ +result_type operator()(argument_type x) const; + +/// @} + +}; /* end AlgebraicStructureTraits::Inverse */ + diff --git a/Algebraic_foundations/doc/Algebraic_foundations/Concepts/AlgebraicStructureTraits--IsOne.h b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/AlgebraicStructureTraits--IsOne.h new file mode 100644 index 00000000000..aae3be05f45 --- /dev/null +++ b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/AlgebraicStructureTraits--IsOne.h @@ -0,0 +1,45 @@ + +/*! +\ingroup PkgAlgebraicFoundationsConcepts +\cgalconcept + +`AdaptableUnaryFunction`, +returns true in case the argument is the one of the ring. + +\refines ::AdaptableUnaryFunction + +\sa ::AlgebraicStructureTraits + +*/ + +class AlgebraicStructureTraits::IsOne { +public: + +/// \name Types +/// @{ + +/*! +Is `AlgebraicStructureTraits::Boolean`. +*/ +typedef Hidden_type result_type; + +/*! +Is `AlgebraicStructureTraits::Type`. +*/ +typedef Hidden_type argument_type; + +/// @} + +/// \name Operations +/// @{ + +/*! + +returns true in case \f$ x\f$ is the one of the ring. +*/ +result_type operator()(argument_type x); + +/// @} + +}; /* end AlgebraicStructureTraits::IsOne */ + diff --git a/Algebraic_foundations/doc/Algebraic_foundations/Concepts/AlgebraicStructureTraits--IsSquare.h b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/AlgebraicStructureTraits--IsSquare.h new file mode 100644 index 00000000000..2647f05b921 --- /dev/null +++ b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/AlgebraicStructureTraits--IsSquare.h @@ -0,0 +1,63 @@ + +/*! +\ingroup PkgAlgebraicFoundationsConcepts +\cgalconcept + +`AdaptableBinaryFunction` that computes whether the first argument is a square. +If the first argument is a square the second argument, which is taken by reference, contains the square root. +Otherwise, the content of the second argument is undefined. + +A ring element \f$ x\f$ is said to be a square iff there exists a ring element \f$ y\f$ such +that \f$ x= y*y\f$. In case the ring is a `UniqueFactorizationDomain`, +\f$ y\f$ is uniquely defined up to multiplication by units. + +\refines ::AdaptableBinaryFunction + +\sa ::AlgebraicStructureTraits + +*/ + +class AlgebraicStructureTraits::IsSquare { +public: + +/// \name Types +/// @{ + +/*! +Is `AlgebraicStructureTraits::Boolean`. +*/ +typedef Hidden_type result_type; + +/*! +Is `AlgebraicStructureTraits::Type`. +*/ +typedef Hidden_type first_argument; + +/*! +Is `AlgebraicStructureTraits::Type&`. +*/ +typedef Hidden_type second_argument; + +/// @} + +/// \name Operations +/// @{ + +/*! +returns true in case \f$ x\f$ is a square, i.e. \f$ x = y*y\f$. +\post \f$ unit\_part(y) == 1\f$. + +*/ +result_type operator()(first_argument_type x, +second_argument_type y); + +/*! +returns true in case \f$ x\f$ is a square. + +*/ +result_type operator()(first_argument_type x); + +/// @} + +}; /* end AlgebraicStructureTraits::IsSquare */ + diff --git a/Algebraic_foundations/doc/Algebraic_foundations/Concepts/AlgebraicStructureTraits--IsZero.h b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/AlgebraicStructureTraits--IsZero.h new file mode 100644 index 00000000000..8ee0c673ebe --- /dev/null +++ b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/AlgebraicStructureTraits--IsZero.h @@ -0,0 +1,45 @@ + +/*! +\ingroup PkgAlgebraicFoundationsConcepts +\cgalconcept + +`AdaptableUnaryFunction`, returns true in case the argument is the zero element of the ring. + +\refines ::AdaptableUnaryFunction + +\sa ::AlgebraicStructureTraits +\sa ::RealEmbeddableTraits::IsZero + +*/ + +class AlgebraicStructureTraits::IsZero { +public: + +/// \name Types +/// @{ + +/*! +Is `AlgebraicStructureTraits::Boolean`. +*/ +typedef Hidden_type result_type; + +/*! +Is `AlgebraicStructureTraits::Type`. +*/ +typedef Hidden_type argument_type; + +/// @} + +/// \name Operations +/// @{ + +/*! + +returns true in case \f$ x\f$ is the zero element of the ring. +*/ +result_type operator()(argument_type x) const; + +/// @} + +}; /* end AlgebraicStructureTraits::IsZero */ + diff --git a/Algebraic_foundations/doc/Algebraic_foundations/Concepts/AlgebraicStructureTraits--KthRoot.h b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/AlgebraicStructureTraits--KthRoot.h new file mode 100644 index 00000000000..11c9bdd0427 --- /dev/null +++ b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/AlgebraicStructureTraits--KthRoot.h @@ -0,0 +1,51 @@ + +/*! +\ingroup PkgAlgebraicFoundationsConcepts +\cgalconcept + +`AdaptableBinaryFunction` providing the k-th root. + +\refines ::AdaptableBinaryFunction + +\sa ::FieldWithRootOf +\sa ::AlgebraicStructureTraits + +*/ + +class AlgebraicStructureTraits::KthRoot { +public: + +/// \name Types +/// @{ + +/*! +Is `AlgebraicStructureTraits::Type`. +*/ +typedef Hidden_type result_type; + +/*! +Is int. +*/ +typedef Hidden_type first_argument; + +/*! +Is `AlgebraicStructureTraits::Type`. +*/ +typedef Hidden_type second_argument; + +/// @} + +/// \name Operations +/// @{ + +/*! +returns the \f$ k\f$-th root of \f$ x\f$. +\pre \f$ k \geq1\f$ + +*/ +result_type operator()(int k, second_argument_type x); + +/// @} + +}; /* end AlgebraicStructureTraits::KthRoot */ + diff --git a/Algebraic_foundations/doc/Algebraic_foundations/Concepts/AlgebraicStructureTraits--Mod.h b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/AlgebraicStructureTraits--Mod.h new file mode 100644 index 00000000000..5c46284ee20 --- /dev/null +++ b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/AlgebraicStructureTraits--Mod.h @@ -0,0 +1,57 @@ + +/*! +\ingroup PkgAlgebraicFoundationsConcepts +\cgalconcept + +`AdaptableBinaryFunction` computes the remainder of division with remainder. + +\refines ::AdaptableBinaryFunction + +\sa ::AlgebraicStructureTraits +\sa ::AlgebraicStructureTraits::Div +\sa ::AlgebraicStructureTraits::DivMod + +*/ + +class AlgebraicStructureTraits::Mod { +public: + +/// \name Types +/// @{ + +/*! +Is `AlgebraicStructureTraits::Type`. +*/ +typedef Hidden_type result_type; + +/*! +Is `AlgebraicStructureTraits::Type`. +*/ +typedef Hidden_type first_argument; + +/*! +Is `AlgebraicStructureTraits::Type`. +*/ +typedef Hidden_type second_argument; + +/// @} + +/// \name Operations +/// @{ + +/*! + +*/ +result_type operator()(first_argument_type x, +second_argument_type y); + +/*! +This operator is defined if `NT1` and `NT2` are `ExplicitInteroperable` +with coercion type `AlgebraicStructureTraits::Type`. +*/ +template result_type operator()(NT1 x, NT2 y); + +/// @} + +}; /* end AlgebraicStructureTraits::Mod */ + diff --git a/Algebraic_foundations/doc/Algebraic_foundations/Concepts/AlgebraicStructureTraits--RootOf.h b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/AlgebraicStructureTraits--RootOf.h new file mode 100644 index 00000000000..f8f4709524d --- /dev/null +++ b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/AlgebraicStructureTraits--RootOf.h @@ -0,0 +1,45 @@ + +/*! +\ingroup PkgAlgebraicFoundationsConcepts +\cgalconcept + +`AdaptableFunctor` computes a real root of a square-free univariate +polynomial. + +\refines ::AdaptableFunctor + +\sa ::FieldWithRootOf +\sa ::AlgebraicStructureTraits + +*/ + +class AlgebraicStructureTraits::RootOf { +public: + +/// \name Types +/// @{ + +/*! +Is `AlgebraicStructureTraits::Type`. +*/ +typedef Hidden_type result_type; + +/// @} + +/// \name Operations +/// @{ + +/*! +returns the k-th real root of the univariate polynomial, +which is defined by the iterator range, +where begin refers to the constant term. +\pre The polynomial is square-free. +\pre The value type of the InputIterator is `AlgebraicStructureTraits::Type`. +*/ +template +result_type operator() (int k, InputIterator begin, InputIterator end); + +/// @} + +}; /* end AlgebraicStructureTraits::RootOf */ + diff --git a/Algebraic_foundations/doc/Algebraic_foundations/Concepts/AlgebraicStructureTraits--Simplify.h b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/AlgebraicStructureTraits--Simplify.h new file mode 100644 index 00000000000..90ac2fdb422 --- /dev/null +++ b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/AlgebraicStructureTraits--Simplify.h @@ -0,0 +1,43 @@ + +/*! +\ingroup PkgAlgebraicFoundationsConcepts +\cgalconcept + +This `AdaptableUnaryFunction` may simplify a given object. + +\refines ::AdaptableUnaryFunction + +\sa ::AlgebraicStructureTraits + +*/ + +class AlgebraicStructureTraits::Simplify { +public: + +/// \name Types +/// @{ + +/*! +Is void. +*/ +typedef Hidden_type result_type; + +/*! +Is `AlgebraicStructureTraits::Type`. +*/ +typedef Hidden_type argument_type; + +/// @} + +/// \name Operations +/// @{ + +/*! +may simplify \f$ x\f$. +*/ +result_type operator()(argument_type x); + +/// @} + +}; /* end AlgebraicStructureTraits::Simplify */ + diff --git a/Algebraic_foundations/doc/Algebraic_foundations/Concepts/AlgebraicStructureTraits--Sqrt.h b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/AlgebraicStructureTraits--Sqrt.h new file mode 100644 index 00000000000..1d983ca4232 --- /dev/null +++ b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/AlgebraicStructureTraits--Sqrt.h @@ -0,0 +1,43 @@ + +/*! +\ingroup PkgAlgebraicFoundationsConcepts +\cgalconcept + +`AdaptableUnaryFunction` providing the square root. + +\refines ::AdaptableUnaryFunction + +\sa ::AlgebraicStructureTraits + +*/ + +class AlgebraicStructureTraits::Sqrt { +public: + +/// \name Types +/// @{ + +/*! +Is `AlgebraicStructureTraits::Type`. +*/ +typedef Hidden_type result_type; + +/*! +Is `AlgebraicStructureTraits::Type`. +*/ +typedef Hidden_type argument_type; + +/// @} + +/// \name Operations +/// @{ + +/*! +returns \f$ \sqrt{x}\f$. +*/ +result_type operator()(argument_type x) const; + +/// @} + +}; /* end AlgebraicStructureTraits::Sqrt */ + diff --git a/Algebraic_foundations/doc/Algebraic_foundations/Concepts/AlgebraicStructureTraits--Square.h b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/AlgebraicStructureTraits--Square.h new file mode 100644 index 00000000000..6e55aa83ca7 --- /dev/null +++ b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/AlgebraicStructureTraits--Square.h @@ -0,0 +1,43 @@ + +/*! +\ingroup PkgAlgebraicFoundationsConcepts +\cgalconcept + +`AdaptableUnaryFunction`, computing the square of the argument. + +\refines ::AdaptableUnaryFunction + +\sa ::AlgebraicStructureTraits + +*/ + +class AlgebraicStructureTraits::Square { +public: + +/// \name Types +/// @{ + +/*! +Is `AlgebraicStructureTraits::Type`. +*/ +typedef Hidden_type result_type; + +/*! +Is `AlgebraicStructureTraits::Type`. +*/ +typedef Hidden_type argument_type; + +/// @} + +/// \name Operations +/// @{ + +/*! +returns the square of \f$ x\f$. +*/ +result_type operator()(argument_type x); + +/// @} + +}; /* end AlgebraicStructureTraits::Square */ + diff --git a/Algebraic_foundations/doc/Algebraic_foundations/Concepts/AlgebraicStructureTraits--UnitPart.h b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/AlgebraicStructureTraits--UnitPart.h new file mode 100644 index 00000000000..fcc6a06104d --- /dev/null +++ b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/AlgebraicStructureTraits--UnitPart.h @@ -0,0 +1,57 @@ + +/*! +\ingroup PkgAlgebraicFoundationsConcepts +\cgalconcept + +This `AdaptableUnaryFunction` computes the unit part of a given ring +element. + +The mathematical definition of unit part is as follows: Two ring elements \f$ a\f$ +and \f$ b\f$ are said to be associate if there exists an invertible ring element +(i.e. a unit) \f$ u\f$ such that \f$ a = ub\f$. This defines an equivalence relation. +We can distinguish exactly one element of every equivalence class as being +unit normal. Then each element of a ring possesses a factorization into a unit +(called its unit part) and a unit-normal ring element +(called its unit normal associate). + +For the integers, the non-negative numbers are by convention unit normal, +hence the unit-part of a non-zero integer is its sign. For a `Field`, every +non-zero element is a unit and is its own unit part, its unit normal +associate being one. The unit part of zero is, by convention, one. + +\refines ::AdaptableUnaryFunction + +\sa ::AlgebraicStructureTraits + +*/ + +class AlgebraicStructureTraits::UnitPart { +public: + +/// \name Types +/// @{ + +/*! +Is `AlgebraicStructureTraits::Type`. +*/ +typedef Hidden_type result_type; + +/*! +Is `AlgebraicStructureTraits::Type`. +*/ +typedef Hidden_type argument_type; + +/// @} + +/// \name Operations +/// @{ + +/*! +returns the unit part of \f$ x\f$. +*/ +result_type operator()(argument_type x); + +/// @} + +}; /* end AlgebraicStructureTraits::UnitPart */ + diff --git a/Algebraic_foundations/doc/Algebraic_foundations/Concepts/AlgebraicStructureTraits.h b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/AlgebraicStructureTraits.h new file mode 100644 index 00000000000..1caffdf9bbf --- /dev/null +++ b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/AlgebraicStructureTraits.h @@ -0,0 +1,303 @@ + +/*! +\ingroup PkgAlgebraicFoundationsConcepts +\cgalconcept + +A model of `AlgebraicStructureTraits` reflects the algebraic structure +of an associated type `Type`. + +Depending on the concepts that `Type` fulfills, +it contains various functors and descriptive tags. +Moreover it gives access to the several possible +algebraic operations within that structure. + +\sa ::IntegralDomainWithoutDivision +\sa ::IntegralDomain +\sa ::UniqueFactorizationDomain +\sa ::EuclideanRing +\sa ::Field +\sa ::FieldWithSqrt +\sa ::FieldWithKthRoot +\sa ::FieldWithRootOf +\sa ::CGAL::Integral_domain_without_division_tag +\sa ::CGAL::Integral_domain_tag +\sa ::CGAL::Unique_factorization_domain_tag +\sa ::CGAL::Euclidean_ring_tag +\sa ::CGAL::Field_tag +\sa ::CGAL::Field_with_sqrt_tag +\sa ::CGAL::Field_with_kth_root_tag +\sa ::CGAL::Field_with_root_of_tag + +\hasModel `CGAL::Algebraic_structure_traits` + +*/ + +class AlgebraicStructureTraits { +public: + +/// \name Types +/// A model of `AlgebraicStructureTraits` is supposed to provide: +/// @{ + +/*! +The associated type. +*/ +typedef Hidden_type Type; + +/*! +Tag indicating the algebraic structure of the associated type. + + + + + + + + + + + + +
+
+Tag is: + +`Type` is model of: +
+
+`CGAL::Null_tag` + +no algebraic concept +
+`CGAL::Integral_domain_without_division_tag` + +`IntegralDomainWithoutDivision` +
+`CGAL::Integral_domain_tag` + +`IntegralDomain` +
+`CGAL::Unique_factorization_domain_tag` + +`UniqueFactorizationDomain` +
+`CGAL::Euclidean_ring_tag` + +`EuclideanRing` +
+`CGAL::Field_tag` + +`Field` +
+`CGAL::Field_with_sqrt_tag` + +`FieldWithSqrt` +
+`CGAL::Field_with_kth_root_tag` + +`FieldWithKthRoot` +
+`CGAL::Field_with_root_of_tag` + +`FieldWithRootOf` +
+
+ +*/ +typedef Hidden_type Algebraic_category; + +/*! +Tag indicating whether `Type` is exact. + +This is either `CGAL::Tag_true` or `CGAL::Tag_false`. + +An algebraic structure is considered exact, if all operations +required by its concept are computed such that a comparison +of two algebraic expressions is always correct. +The exactness covers only those operations that are required by +the algebraic structure concept. + +e.g. an exact `Field` may have a `Sqrt` functor that +is not exact. + +*/ +typedef Hidden_type Is_exact; + +/*! +Tag indicating whether `Type` is numerical sensitive. + +This is either `CGAL::Tag_true` or `CGAL::Tag_false`. + +An algebraic structure is considered as numerically sensitive, +if the performance of the type is sensitive to the condition +number of an algorithm. + +*/ +typedef Hidden_type Is_numerical_sensitive; + +/*! +This type specifies the return type of the predicates provided +by this traits. The type must be convertible to `bool` and +typically the type indeed maps to `bool`. However, there are also +cases such as interval arithmetic, in which it is `Uncertain` +or some similar type. + +*/ +typedef Hidden_type Boolean; + +/// @} + +/// \name Functors +/// In case a functor is not provided, it is set to `CGAL::Null_functor`. +/// @{ + +/*! + +A model of `AlgebraicStructureTraits::IsZero`. + +Required by the concept `IntegralDomainWithoutDivision`. +In case `Type` is also model of `RealEmbeddable` this is a +model of `RealEmbeddableTraits::IsZero`. + +*/ +typedef Hidden_type Is_zero; + +/*! + +A model of `AlgebraicStructureTraits::IsOne`. + +Required by the concept `IntegralDomainWithoutDivision`. + +*/ +typedef Hidden_type Is_one; + +/*! + +A model of `AlgebraicStructureTraits::Square`. + +Required by the concept `IntegralDomainWithoutDivision`. + +*/ +typedef Hidden_type Square; + +/*! + +A model of `AlgebraicStructureTraits::Simplify`. + +Required by the concept `IntegralDomainWithoutDivision`. + +*/ +typedef Hidden_type Simplify; + +/*! + +A model of `AlgebraicStructureTraits::UnitPart`. + +Required by the concept `IntegralDomainWithoutDivision`. + +*/ +typedef Hidden_type Unit_part; + +/*! + +A model of `AlgebraicStructureTraits::IntegralDivision`. + +Required by the concept `IntegralDomain`. + +*/ +typedef Hidden_type Integral_division; + +/*! + +A model of `AlgebraicStructureTraits::Divides`. + +Required by the concept `IntegralDomain`. + +*/ +typedef Hidden_type Divides; + +/*! + +A model of `AlgebraicStructureTraits::IsSquare`. + +Required by the concept `IntegralDomainWithoutDivision`. + +*/ +typedef Hidden_type Is_square; + +/*! + +A model of `AlgebraicStructureTraits::Gcd`. + +Required by the concept `UniqueFactorizationDomain`. + +*/ +typedef Hidden_type Gcd; + +/*! + +A model of `AlgebraicStructureTraits::Mod`. + +Required by the concept `EuclideanRing`. + +*/ +typedef Hidden_type Mod; + +/*! + +A model of `AlgebraicStructureTraits::Div`. + +Required by the concept `EuclideanRing`. + +*/ +typedef Hidden_type Div; + +/*! + +A model of `AlgebraicStructureTraits::DivMod`. + +Required by the concept `EuclideanRing`. + +*/ +typedef Hidden_type Div_mod; + +/*! + +A model of `AlgebraicStructureTraits::Inverse`. + +Required by the concept `Field`. + +*/ +typedef Hidden_type Inverse; + +/*! + +A model of `AlgebraicStructureTraits::Sqrt`. + +Required by the concept `FieldWithSqrt`. + +*/ +typedef Hidden_type Sqrt; + +/*! + +A model of `AlgebraicStructureTraits::KthRoot`. + +Required by the concept `FieldWithKthRoot`. + +*/ +typedef Hidden_type Kth_root; + +/*! + +A model of `AlgebraicStructureTraits::RootOf`. + +Required by the concept `FieldWithRootOf`. + +*/ +typedef Hidden_type Root_of; + +/// @} + +}; /* end AlgebraicStructureTraits */ + diff --git a/Algebraic_foundations/doc/Algebraic_foundations/Concepts/EuclideanRing.h b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/EuclideanRing.h new file mode 100644 index 00000000000..1a1ccccddf7 --- /dev/null +++ b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/EuclideanRing.h @@ -0,0 +1,50 @@ + +/*! +\ingroup PkgAlgebraicFoundationsConcepts +\cgalconcept + +A model of `EuclideanRing` represents an euclidean ring (or Euclidean domain). +It is an `UniqueFactorizationDomain` that affords a suitable notion of minimality of remainders +such that given \f$ x\f$ and \f$ y \neq 0\f$ we obtain an (almost) unique solution to +\f$ x = qy + r \f$ by demanding that a solution \f$ (q,r)\f$ is chosen to minimize \f$ r\f$. +In particular, \f$ r\f$ is chosen to be \f$ 0\f$ if possible. + +Moreover, `CGAL::Algebraic_structure_traits< EuclideanRing >` is a model of +`AlgebraicStructureTraits` providing: + +- `CGAL::Algebraic_structure_traits< EuclideanRing >::Algebraic_type` derived from `Unique_factorization_domain_tag` + +- `CGAL::Algebraic_structure_traits< EuclideanRing >::Mod` + +- `CGAL::Algebraic_structure_traits< EuclideanRing >::Div` + +- `CGAL::Algebraic_structure_traits< EuclideanRing >::Div_mod` + +Remarks +-------------- + +The most prominent example of a Euclidean ring are the integers. +Whenever both \f$ x\f$ and \f$ y\f$ are positive, then it is conventional to choose +the smallest positive remainder \f$ r\f$. + +\refines ::UniqueFactorizationDomain + +\sa ::IntegralDomainWithoutDivision +\sa ::IntegralDomain +\sa ::UniqueFactorizationDomain +\sa ::EuclideanRing +\sa ::Field +\sa ::FieldWithSqrt +\sa ::FieldWithKthRoot +\sa ::FieldWithRootOf +\sa ::AlgebraicStructureTraits + +*/ + +class EuclideanRing { +public: + +/// @} + +}; /* end EuclideanRing */ + diff --git a/Algebraic_foundations/doc/Algebraic_foundations/Concepts/ExplicitInteroperable.h b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/ExplicitInteroperable.h new file mode 100644 index 00000000000..f225097796f --- /dev/null +++ b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/ExplicitInteroperable.h @@ -0,0 +1,31 @@ + +/*! +\ingroup PkgAlgebraicFoundationsConcepts +\cgalconcept + +Two types `A` and `B` are a model of the `ExplicitInteroperable` +concept, if it is possible to derive a superior type for `A` and `B`, +such that both types are embeddable into this type. +This type is `Coercion_traits::Type`. + +In this case `Coercion_traits::Are_explicit_interoperable` +is `Tag_true`. + +`A` and `B` are valid argument types for all binary functors in +`Algebraic_structure_traits` and `Real_embeddable_traits`. +This is also the case for the respective global functions. + +\sa CGAL::Coercion_traits +\sa `ImplicitInteroperable` +\sa `AlgebraicStructureTraits` +\sa `RealEmbeddableTraits` + +*/ + +class ExplicitInteroperable { +public: + +/// @} + +}; /* end ExplicitInteroperable */ + diff --git a/Algebraic_foundations/doc/Algebraic_foundations/Concepts/Field.h b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/Field.h new file mode 100644 index 00000000000..fafe67059cc --- /dev/null +++ b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/Field.h @@ -0,0 +1,54 @@ + +/*! +\ingroup PkgAlgebraicFoundationsConcepts +\cgalconcept + +A model of `Field` is an `IntegralDomain` in which every non-zero element +has a multiplicative inverse. +Thus, one can divide by any non-zero element. +Hence division is defined for any divisor != 0. +For a Field, we require this division operation to be available through +operators / and /=. + +Moreover, `CGAL::Algebraic_structure_traits< Field >` is a model of +`AlgebraicStructureTraits` providing: + +- `CGAL::Algebraic_structure_traits< Field >::Algebraic_type` derived from `Field_tag` + +- `CGAL::Algebraic_structure_traits< FieldWithSqrt >::Inverse` + +\refines ::IntegralDomain + +\sa ::IntegralDomainWithoutDivision +\sa ::IntegralDomain +\sa ::UniqueFactorizationDomain +\sa ::EuclideanRing +\sa ::Field +\sa ::FieldWithSqrt +\sa ::FieldWithKthRoot +\sa ::FieldWithRootOf +\sa ::AlgebraicStructureTraits + +*/ + +class Field { +public: + +/// \name Operations +/// @{ + +/*! + +*/ +Field operator/(const Field &a, const Field &b); + + +/*! + +*/ +Field operator/=(const Field &b); + +/// @} + +}; /* end Field */ + diff --git a/Algebraic_foundations/doc/Algebraic_foundations/Concepts/FieldNumberType.h b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/FieldNumberType.h new file mode 100644 index 00000000000..9802f51b1e3 --- /dev/null +++ b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/FieldNumberType.h @@ -0,0 +1,36 @@ + +/*! +\ingroup PkgAlgebraicFoundationsConcepts +\cgalconcept + +The concept `FieldNumberType` combines the requirements of the concepts +`Field` and `RealEmbeddable`. +A model of `FieldNumberType` can be used as a template parameter +for Cartesian kernels. + +\refines ::Field +\refines ::RealEmbeddable + +\hasModel float +\hasModel double +\hasModel CGAL::Gmpq +\hasModel CGAL::Interval_nt +\hasModel CGAL::Interval_nt_advanced +\hasModel CGAL::Lazy_exact_nt +\hasModel CGAL::Quotient +\hasModel leda_rational +\hasModel leda_bigfloat +\hasModel leda_real + +\sa `RingNumberType` +\sa `Kernel` + +*/ + +class FieldNumberType { +public: + +/// @} + +}; /* end FieldNumberType */ + diff --git a/Algebraic_foundations/doc/Algebraic_foundations/Concepts/FieldWithKthRoot.h b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/FieldWithKthRoot.h new file mode 100644 index 00000000000..f00ee7047e5 --- /dev/null +++ b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/FieldWithKthRoot.h @@ -0,0 +1,31 @@ + +/*! +\ingroup PkgAlgebraicFoundationsConcepts +\cgalconcept + +A model of `FieldWithKthRoot` is a `FieldWithSqrt` that has operations to take k-th roots. + +Moreover, `CGAL::Algebraic_structure_traits< FieldWithKthRoot >` is a model of `AlgebraicStructureTraits` providing: + +- `CGAL::Algebraic_structure_traits< FieldWithKthRoot >::Algebraic_type` derived from `Field_with_kth_root_tag` + +- `CGAL::Algebraic_structure_traits< FieldWithKthRoot >::Kth_root` + +\refines ::FieldWithSqrt + +\sa ::IntegralDomainWithoutDivision +\sa ::IntegralDomain +\sa ::UniqueFactorizationDomain +\sa ::EuclideanRing +\sa ::Field +\sa ::FieldWithSqrt +\sa ::FieldWithKthRoot +\sa ::FieldWithRootOf +\sa ::AlgebraicStructureTraits + +*/ + +class FieldWithKthRoot { + +}; /* end FieldWithKthRoot */ + diff --git a/Algebraic_foundations/doc/Algebraic_foundations/Concepts/FieldWithRootOf.h b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/FieldWithRootOf.h new file mode 100644 index 00000000000..9a1b6cbd283 --- /dev/null +++ b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/FieldWithRootOf.h @@ -0,0 +1,35 @@ + +/*! +\ingroup PkgAlgebraicFoundationsConcepts +\cgalconcept + +A model of `FieldWithRootOf` is a `FieldWithKthRoot` with the possibility to +construct it as the root of a univariate polynomial. + +Moreover, `CGAL::Algebraic_structure_traits< FieldWithRootOf >` is a model of `AlgebraicStructureTraits` providing: + +- `CGAL::Algebraic_structure_traits< FieldWithRootOf >::Algebraic_type` derived from `Field_with_kth_root_tag` + +- `CGAL::Algebraic_structure_traits< FieldWithRootOf >::Root_of` + +\refines ::FieldWithKthRoot + +\sa ::IntegralDomainWithoutDivision +\sa ::IntegralDomain +\sa ::UniqueFactorizationDomain +\sa ::EuclideanRing +\sa ::Field +\sa ::FieldWithSqrt +\sa ::FieldWithKthRoot +\sa ::FieldWithRootOf +\sa ::AlgebraicStructureTraits + +*/ + +class FieldWithRootOf { +public: + +/// @} + +}; /* end FieldWithRootOf */ + diff --git a/Algebraic_foundations/doc/Algebraic_foundations/Concepts/FieldWithSqrt.h b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/FieldWithSqrt.h new file mode 100644 index 00000000000..4353562dc95 --- /dev/null +++ b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/FieldWithSqrt.h @@ -0,0 +1,34 @@ + +/*! +\ingroup PkgAlgebraicFoundationsConcepts +\cgalconcept + +A model of `FieldWithSqrt` is a `Field` that has operations to take square roots. + +Moreover, `CGAL::Algebraic_structure_traits< FieldWithSqrt >` is a model of `AlgebraicStructureTraits` providing: + +- `CGAL::Algebraic_structure_traits< FieldWithSqrt >::Algebraic_type` derived from `Field_with_sqrt_tag` + +- `CGAL::Algebraic_structure_traits< FieldWithSqrt >::Sqrt` + +\refines ::Field + +\sa ::IntegralDomainWithoutDivision +\sa ::IntegralDomain +\sa ::UniqueFactorizationDomain +\sa ::EuclideanRing +\sa ::Field +\sa ::FieldWithSqrt +\sa ::FieldWithKthRoot +\sa ::FieldWithRootOf +\sa ::AlgebraicStructureTraits + +*/ + +class FieldWithSqrt { +public: + +/// @} + +}; /* end FieldWithSqrt */ + diff --git a/Algebraic_foundations/doc/Algebraic_foundations/Concepts/Fraction.h b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/Fraction.h new file mode 100644 index 00000000000..f9b00cb7fee --- /dev/null +++ b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/Fraction.h @@ -0,0 +1,22 @@ + +/*! +\ingroup PkgAlgebraicFoundationsConcepts +\cgalconcept + +A type is considered as a `Fraction`, if there is a reasonable way to +decompose it into a numerator and denominator. In this case the relevant +functionality for decomposing and re-composing as well as the numerator and +denominator type are provided by `CGAL::Fraction_traits`. + +\sa ::FractionTraits +\sa CGAL::Fraction_traits + +*/ + +class Fraction { +public: + +/// @} + +}; /* end Fraction */ + diff --git a/Algebraic_foundations/doc/Algebraic_foundations/Concepts/FractionTraits.h b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/FractionTraits.h new file mode 100644 index 00000000000..8be3c3e045f --- /dev/null +++ b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/FractionTraits.h @@ -0,0 +1,215 @@ + +/*! +\ingroup PkgAlgebraicFoundationsConcepts +\cgalconcept + +A model of `FractionTraits` is associated with a type `Type`. + +In case the associated type is a `Fraction`, a model of `FractionTraits` provides the relevant functionality for decomposing and re-composing as well +as the numerator and denominator type. + +\hasModel `CGAL::Fraction_traits` + +\sa `FractionTraits::Decompose` +\sa `FractionTraits::Compose` +\sa `FractionTraits::CommonFactor` + +*/ +class FractionTraits { +public: + +/// \name Types +/// @{ + +/*! +the associated type +*/ +typedef Hidden_type Type; + +/*! + +Tag indicating whether the associated type is a fraction and can be +decomposed into a numerator and denominator. + +This is either `CGAL::Tag_true` or `CGAL::Tag_false`. +*/ +typedef Hidden_type Is_fraction; + +/*! +The type to represent the numerator. +This is undefined in case the associated type is not a fraction. +*/ +typedef Hidden_type Numerator_type ; + +/*! +The (simpler) type to represent the denominator. +This is undefined in case the associated type is not a fraction. +*/ +typedef Hidden_type Denominator_type; + +/// @} + +/// \name Functors +/// In case `Type` is not a `Fraction` all functors are `Null_functor`. +/// @{ + + +/*! +\ingroup PkgAlgebraicFoundationsConcepts +\cgalconcept + +Functor decomposing a `Fraction` into its numerator and denominator. + +\sa `Fraction` +\sa `FractionTraits` +\sa `FractionTraits::Compose` +\sa `FractionTraits::CommonFactor` + +*/ + +class Decompose { +public: + +/// \name Operations +/// @{ + +/*! +decompose \f$ f\f$ into numerator \f$ n\f$ and denominator \f$ d\f$. +*/ +void operator()( FractionTraits::Type f, +FractionTraits::Numerator_type & n, +FractionTraits::Denominator_type & d); + +/// @} + +}; /* end FractionTraits::Decompose */ + +/*! +\ingroup PkgAlgebraicFoundationsConcepts +\cgalconcept + +`AdaptableBinaryFunction`, returns the fraction of its arguments. + +\refines ::AdaptableBinaryFunction + +\sa `Fraction` +\sa `FractionTraits` +\sa `FractionTraits::Decompose` +\sa `FractionTraits::CommonFactor` + +*/ + +class Compose { +public: + +/// \name Types +/// @{ + +/*! + +*/ +typedef FractionTraits::Type result_type; + +/*! + +*/ +typedef FractionTraits::Numerator_type first_argument_type; + +/*! + +*/ +typedef FractionTraits::Denominator_type second_argument_type; + +/// @} + +/// \name Operations +/// @{ + +/*! +return the fraction \f$ n/d\f$. +*/ +result_type operator()(first_argument_type n, second_argument_type d); + +/// @} + +}; /* end FractionTraits::Compose */ + + +/*! +\ingroup PkgAlgebraicFoundationsConcepts +\cgalconcept + +`AdaptableBinaryFunction`, finds great common factor of denominators. + +This can be considered as a relaxed version of `AlgebraicStructureTraits::Gcd`, +this is needed because it is not guaranteed that `FractionTraits::Denominator_type` is a model of +`UniqueFactorizationDomain`. + +\refines ::AdaptableBinaryFunction + +\sa `Fraction` +\sa `FractionTraits` +\sa `FractionTraits::Decompose` +\sa `FractionTraits::Compose` +\sa `AlgebraicStructureTraits::Gcd` + +*/ + +class CommonFactor { +public: + +/// \name Types +/// @{ + +/*! + +*/ +typedef FractionTraits::Denominator_type result_type; + +/*! + +*/ +typedef FractionTraits::Denominator_type first_argument_type; + +/*! + +*/ +typedef FractionTraits::Denominator_type second_argument_type; + +/// @} + +/// \name Operations +/// @{ + +/*! +return a great common factor of \f$ d1\f$ and \f$ d2\f$. + +Note: operator()(0,0) = 0 +*/ +result_type operator()(first_argument_type d1, second_argument_type d2); + +/// @} + +}; /* end FractionTraits::CommonFactor */ + + /*! + A model of FractionTraits::Compose. + */ +typedef Hidden_type Compose; + + + /*! + A model of FractionTraits::Decompose. + */ +typedef Hidden_type Decompose; + + + /*! + A model of FractionTraits::CommonFactor. + */ +typedef Hidden_type Common_factor; + + +/// @} + +}; /* end FractionTraits */ diff --git a/Algebraic_foundations/doc/Algebraic_foundations/Concepts/FromDoubleConstructible.h b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/FromDoubleConstructible.h new file mode 100644 index 00000000000..6bfcce92c81 --- /dev/null +++ b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/FromDoubleConstructible.h @@ -0,0 +1,30 @@ + +/*! +\ingroup PkgAlgebraicFoundationsConcepts +\cgalconcept + +A model of the concept `FromDoubleConstructible` is required +to be constructible from the type `double`. + +In case the type is a model of `RealEmbeddable` too, for any double d +the identity: `d == CGAL::to_double(T(d))`, is guaranteed. + +*/ + +class FromDoubleConstructible { +public: + +/// \name Creation +/// @{ + +/*! + +conversion constructor from double. + +*/ +FromDoubleConstructible(const double& d); + +/// @} + +}; /* end FromDoubleConstructible */ + diff --git a/Algebraic_foundations/doc/Algebraic_foundations/Concepts/FromIntConstructible.h b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/FromIntConstructible.h new file mode 100644 index 00000000000..dbc356111d6 --- /dev/null +++ b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/FromIntConstructible.h @@ -0,0 +1,29 @@ + +/*! +\ingroup PkgAlgebraicFoundationsConcepts +\cgalconcept + +A model of the concept `FromIntConstructible` is required +to be constructible from int. + +\hasModel int +\hasModel long +\hasModel double + +*/ + +class FromIntConstructible { +public: + +/// \name Creation +/// @{ + +/*! + +*/ +FromIntConstructible(int& i); + +/// @} + +}; /* end FromIntConstructible */ + diff --git a/Algebraic_foundations/doc/Algebraic_foundations/Concepts/ImplicitInteroperable.h b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/ImplicitInteroperable.h new file mode 100644 index 00000000000..d239339be7f --- /dev/null +++ b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/ImplicitInteroperable.h @@ -0,0 +1,32 @@ + +/*! +\ingroup PkgAlgebraicFoundationsConcepts +\cgalconcept + +Two types `A` and `B` are a model of the concept +`ImplicitInteroperable`, if there is a superior type, such that +binary arithmetic operations involving `A` and `B` result in +this type. This type is `Coercion_traits::Type`. + +The type `Coercion_traits::Type` is required to be +implicit constructible from `A` and `B`. + +In this case `Coercion_traits::Are_implicit_interoperable` +is `Tag_true`. + +\refines ::ExplicitInteroperable + +\sa CGAL::Coercion_traits +\sa `ExplicitInteroperable` +\sa `AlgebraicStructureTraits` +\sa `RealEmbeddableTraits` + +*/ + +class ImplicitInteroperable { +public: + +/// @} + +}; /* end ImplicitInteroperable */ + diff --git a/Algebraic_foundations/doc/Algebraic_foundations/Concepts/IntegralDomain.h b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/IntegralDomain.h new file mode 100644 index 00000000000..a7f8eb0a038 --- /dev/null +++ b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/IntegralDomain.h @@ -0,0 +1,41 @@ + +/*! +\ingroup PkgAlgebraicFoundationsConcepts +\cgalconcept + +`IntegralDomain` refines `IntegralDomainWithoutDivision` by +providing an integral division. + +Note: The concept does not require the operator / for this operation. +We intend to reserve the operator syntax for use with a `Field`. + +Moreover, `CGAL::Algebraic_structure_traits< IntegralDomain >` is a model of +`AlgebraicStructureTraits` providing: + +- `CGAL::Algebraic_structure_traits< IntegralDomain >::Algebraic_type` derived from `Integral_domain_tag` + +- `CGAL::Algebraic_structure_traits< IntegralDomain >::Integral_division` + +- `CGAL::Algebraic_structure_traits< IntegralDomain >::Divides` + +\refines ::IntegralDomainWithoutDivision + +\sa ::IntegralDomainWithoutDivision +\sa ::IntegralDomain +\sa ::UniqueFactorizationDomain +\sa ::EuclideanRing +\sa ::Field +\sa ::FieldWithSqrt +\sa ::FieldWithKthRoot +\sa ::FieldWithRootOf +\sa ::AlgebraicStructureTraits + +*/ + +class IntegralDomain { +public: + +/// @} + +}; /* end IntegralDomain */ + diff --git a/Algebraic_foundations/doc/Algebraic_foundations/Concepts/IntegralDomainWithoutDivision.h b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/IntegralDomainWithoutDivision.h new file mode 100644 index 00000000000..f56d1cf0ae1 --- /dev/null +++ b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/IntegralDomainWithoutDivision.h @@ -0,0 +1,129 @@ + +/*! +\ingroup PkgAlgebraicFoundationsConcepts +\cgalconcept + +This is the most basic concept for algebraic structures considered within CGAL. + +A model `IntegralDomainWithoutDivision` represents an integral domain, +i.e. commutative ring with 0, 1, +, * and unity free of zero divisors. + +Note: A model is not required to offer the always well defined integral division. + +It refines `Assignable`, `CopyConstructible`, `DefaultConstructible` +and `FromIntConstructible`. + +It refines `EqualityComparable`, where equality is defined w.r.t. +the ring element being represented. + +The operators unary and binary plus +, unary and binary minus -, +multiplication * and their compound forms +=, -=, *= are required and +implement the respective ring operations. + +Moreover, `CGAL::Algebraic_structure_traits< IntegralDomainWithoutDivision >` is a model of +`AlgebraicStructureTraits` providing: + +- `CGAL::Algebraic_structure_traits< IntegralDomainWithoutDivision >::Algebraic_type` derived from `Integral_domain_without_division_tag` + +- `CGAL::Algebraic_structure_traits< IntegralDomainWithoutDivision >::Is_zero` + +- `CGAL::Algebraic_structure_traits< IntegralDomainWithoutDivision >::Is_one` + +- `CGAL::Algebraic_structure_traits< IntegralDomainWithoutDivision >::Square` + +- `CGAL::Algebraic_structure_traits< IntegralDomainWithoutDivision >::Simplify` + +- `CGAL::Algebraic_structure_traits< IntegralDomainWithoutDivision >::Unit_part` + +\refines ::Assignable +\refines ::CopyConstructible +\refines ::DefaultConstructible +\refines ::EqualityComparable +\refines ::FromIntConstructible + +\sa ::IntegralDomainWithoutDivision +\sa ::IntegralDomain +\sa ::UniqueFactorizationDomain +\sa ::EuclideanRing +\sa ::Field +\sa ::FieldWithSqrt +\sa ::FieldWithKthRoot +\sa ::FieldWithRootOf +\sa ::AlgebraicStructureTraits + +*/ + +class IntegralDomainWithoutDivision { +public: + +/// \name Operations +/// @{ + +/*! +unary plus +*/ +IntegralDomainWithoutDivision +operator+(const IntegralDomainWithoutDivision &a); + +/*! +unary minus +*/ +IntegralDomainWithoutDivision +operator-(const IntegralDomainWithoutDivision &a); + +/*! + +*/ +IntegralDomainWithoutDivision +operator+(const IntegralDomainWithoutDivision &a, +const IntegralDomainWithoutDivision &b); + +/*! + +*/ +IntegralDomainWithoutDivision +operator-(const IntegralDomainWithoutDivision &a, +const IntegralDomainWithoutDivision &b); + +/*! + +*/ +IntegralDomainWithoutDivision +operator*(const IntegralDomainWithoutDivision &a, +const IntegralDomainWithoutDivision &b); + + +/*! + +*/ +IntegralDomainWithoutDivision +operator+=(const IntegralDomainWithoutDivision &b); + +/*! + +*/ +IntegralDomainWithoutDivision +operator-=(const IntegralDomainWithoutDivision &b); + +/*! + +*/ +IntegralDomainWithoutDivision +operator*=(const IntegralDomainWithoutDivision &b); + +/*! +The `result_type` is convertible to `bool`. +*/ +result_type +operator==(const IntegralDomainWithoutDivision &a, const IntegralDomainWithoutDivision &b); + +/*! +The `result_type` is convertible to `bool`. +*/ +result_type +operator!=(const IntegralDomainWithoutDivision &a, const IntegralDomainWithoutDivision &b); + +/// @} + +}; /* end IntegralDomainWithoutDivision */ + diff --git a/Algebraic_foundations/doc/Algebraic_foundations/Concepts/RealEmbeddable.h b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/RealEmbeddable.h new file mode 100644 index 00000000000..54248932824 --- /dev/null +++ b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/RealEmbeddable.h @@ -0,0 +1,96 @@ + +/*! +\ingroup PkgAlgebraicFoundationsConcepts +\cgalconcept + +A model of this concepts represents numbers that are embeddable on the real +axis. The type obeys the algebraic structure and compares two values according +to the total order of the real numbers. + +Moreover, `CGAL::Real_embeddable_traits< RealEmbeddable >` is a model of +`RealEmbeddableTraits` + +with: + +- `CGAL::Real_embeddable_traits< RealEmbeddable >::Is_real_embeddable` set to `Tag_true` + +and functors : + +- `CGAL::Real_embeddable_traits< RealEmbeddable >::Is_zero` + +- `CGAL::Real_embeddable_traits< RealEmbeddable >::Abs` + +- `CGAL::Real_embeddable_traits< RealEmbeddable >::Sgn` + +- `CGAL::Real_embeddable_traits< RealEmbeddable >::Is_positive` + +- `CGAL::Real_embeddable_traits< RealEmbeddable >::Is_negative` + +- `CGAL::Real_embeddable_traits< RealEmbeddable >::Compare` + +- `CGAL::Real_embeddable_traits< RealEmbeddable >::To_double` + +- `CGAL::Real_embeddable_traits< RealEmbeddable >::To_interval` + +Remark: + +If a number type is a model of both `IntegralDomainWithoutDivision` and +`RealEmbeddable`, it follows that the ring represented by such a number type +is a sub-ring of the real numbers and hence has characteristic zero. + +\refines ::Equality Comparable +\refines ::LessThanComparable + +\sa ::RealEmbeddableTraits + +*/ + +class RealEmbeddable { +public: + +/// \name Operations +/// @{ + +/*! + +*/ +bool operator==(const RealEmbeddable &a, +const RealEmbeddable &b); + + +/*! + +*/ +bool operator!=(const RealEmbeddable &a, +const RealEmbeddable &b); + +/*! + +*/ +bool operator< (const RealEmbeddable &a, +const RealEmbeddable &b); + +/*! + +*/ +bool operator<=(const RealEmbeddable &a, +const RealEmbeddable &b); + +/*! + + +*/ +bool operator> (const RealEmbeddable &a, +const RealEmbeddable &b); + +/*! + +\relates RealEmbeddable +*/ +bool operator>=(const RealEmbeddable &a, +const RealEmbeddable &b); + +/// @} + +}; /* end RealEmbeddable */ + diff --git a/Algebraic_foundations/doc/Algebraic_foundations/Concepts/RealEmbeddableTraits--Abs.h b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/RealEmbeddableTraits--Abs.h new file mode 100644 index 00000000000..db580ef820e --- /dev/null +++ b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/RealEmbeddableTraits--Abs.h @@ -0,0 +1,43 @@ + +/*! +\ingroup PkgAlgebraicFoundationsConcepts +\cgalconcept + +`AdaptableUnaryFunction` computes the absolute value of a number. + +\refines ::AdaptableUnaryFunction + +\sa ::RealEmbeddableTraits + +*/ + +class RealEmbeddableTraits::Abs { +public: + +/// \name Types +/// @{ + +/*! +Is `RealEmbeddableTraits::Type`. +*/ +typedef Hidden_type result_type; + +/*! +Is `RealEmbeddableTraits::Type`. +*/ +typedef Hidden_type argument_type; + +/// @} + +/// \name Operations +/// @{ + +/*! +computes the absolute value of \f$ x\f$. +*/ +result_type operator()(argument_type x); + +/// @} + +}; /* end RealEmbeddableTraits::Abs */ + diff --git a/Algebraic_foundations/doc/Algebraic_foundations/Concepts/RealEmbeddableTraits--Compare.h b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/RealEmbeddableTraits--Compare.h new file mode 100644 index 00000000000..f4993780441 --- /dev/null +++ b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/RealEmbeddableTraits--Compare.h @@ -0,0 +1,58 @@ + +/*! +\ingroup PkgAlgebraicFoundationsConcepts +\cgalconcept + +`AdaptableBinaryFunction` compares two real embeddable numbers. + +\refines ::AdaptableBinaryFunction + +\sa ::RealEmbeddableTraits + +*/ + +class RealEmbeddableTraits::Compare { +public: + +/// \name Types +/// @{ + +/*! +Type convertible to `CGAL::Comparison_result`. +*/ +typedef Hidden_type result_type; + +/*! +Is `RealEmbeddableTraits::Type`. +*/ +typedef Hidden_type first_argument_type; + +/*! +Is `RealEmbeddableTraits::Type`. +*/ +typedef Hidden_type second_argument_type; + +/// @} + +/// \name Operations +/// @{ + +/*! +compares \f$ x\f$ with respect to \f$ y\f$. +*/ +result_type operator()(first_argument_type x, +second_argument_type y); + +/*! + +This operator is defined if `NT1` and `NT2` are +`ExplicitInteroperable` with coercion type +`RealEmbeddableTraits::Type`. +*/ +template +result_type operator()(NT1 x, NT2 y); + +/// @} + +}; /* end RealEmbeddableTraits::Compare */ + diff --git a/Algebraic_foundations/doc/Algebraic_foundations/Concepts/RealEmbeddableTraits--IsNegative.h b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/RealEmbeddableTraits--IsNegative.h new file mode 100644 index 00000000000..e6b4825a7c5 --- /dev/null +++ b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/RealEmbeddableTraits--IsNegative.h @@ -0,0 +1,43 @@ + +/*! +\ingroup PkgAlgebraicFoundationsConcepts +\cgalconcept + +`AdaptableUnaryFunction`, returns true in case the argument is negative. + +\refines ::AdaptableUnaryFunction + +\sa ::RealEmbeddableTraits + +*/ + +class RealEmbeddableTraits::IsNegative { +public: + +/// \name Types +/// @{ + +/*! +Type convertible to `bool`. +*/ +typedef Hidden_type result_type; + +/*! +Is `RealEmbeddableTraits::Type`. +*/ +typedef Hidden_type argument_type; + +/// @} + +/// \name Operations +/// @{ + +/*! +returns true in case \f$ x\f$ is negative. +*/ +result_type operator()(argument_type x); + +/// @} + +}; /* end RealEmbeddableTraits::IsNegative */ + diff --git a/Algebraic_foundations/doc/Algebraic_foundations/Concepts/RealEmbeddableTraits--IsPositive.h b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/RealEmbeddableTraits--IsPositive.h new file mode 100644 index 00000000000..fba241abd96 --- /dev/null +++ b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/RealEmbeddableTraits--IsPositive.h @@ -0,0 +1,43 @@ + +/*! +\ingroup PkgAlgebraicFoundationsConcepts +\cgalconcept + +`AdaptableUnaryFunction`, returns true in case the argument is positive. + +\refines ::AdaptableUnaryFunction + +\sa ::RealEmbeddableTraits + +*/ + +class RealEmbeddableTraits::IsPositive { +public: + +/// \name Types +/// @{ + +/*! +Type convertible to `bool`. +*/ +typedef Hidden_type result_type; + +/*! +Is `RealEmbeddableTraits::Type`. +*/ +typedef Hidden_type argument_type; + +/// @} + +/// \name Operations +/// @{ + +/*! +returns true in case \f$ x\f$ is positive. +*/ +result_type operator()(argument_type x); + +/// @} + +}; /* end RealEmbeddableTraits::IsPositive */ + diff --git a/Algebraic_foundations/doc/Algebraic_foundations/Concepts/RealEmbeddableTraits--IsZero.h b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/RealEmbeddableTraits--IsZero.h new file mode 100644 index 00000000000..7d642a1375e --- /dev/null +++ b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/RealEmbeddableTraits--IsZero.h @@ -0,0 +1,45 @@ + +/*! +\ingroup PkgAlgebraicFoundationsConcepts +\cgalconcept + +`AdaptableUnaryFunction`, returns true in case the argument is 0. + +\refines ::AdaptableUnaryFunction + +\sa ::RealEmbeddableTraits +\sa ::AlgebraicStructureTraits::IsZero + +*/ + +class RealEmbeddableTraits::IsZero { +public: + +/// \name Types +/// @{ + +/*! +Type convertible to `bool`. +*/ +typedef Hidden_type result_type; + +/*! +Is `RealEmbeddableTraits::Type`. +*/ +typedef Hidden_type argument_type; + +/// @} + +/// \name Operations +/// @{ + +/*! + +returns true in case \f$ x\f$ is the zero element of the ring. +*/ +result_type operator()(argument_type x); + +/// @} + +}; /* end RealEmbeddableTraits::IsZero */ + diff --git a/Algebraic_foundations/doc/Algebraic_foundations/Concepts/RealEmbeddableTraits--Sgn.h b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/RealEmbeddableTraits--Sgn.h new file mode 100644 index 00000000000..85ff4e49861 --- /dev/null +++ b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/RealEmbeddableTraits--Sgn.h @@ -0,0 +1,43 @@ + +/*! +\ingroup PkgAlgebraicFoundationsConcepts +\cgalconcept + +This `AdaptableUnaryFunction` computes the sign of a real embeddable number. + +\refines ::AdaptableUnaryFunction + +\sa ::RealEmbeddableTraits + +*/ + +class RealEmbeddableTraits::Sgn { +public: + +/// \name Types +/// @{ + +/*! +Type convertible to `CGAL::Sign`. +*/ +typedef Hidden_type result_type; + +/*! +Is `RealEmbeddableTraits::Type`. +*/ +typedef Hidden_type argument_type; + +/// @} + +/// \name Operations +/// @{ + +/*! +Computes the sign of \f$ x\f$. +*/ +result_type operator()(argument_type x); + +/// @} + +}; /* end RealEmbeddableTraits::Sgn */ + diff --git a/Algebraic_foundations/doc/Algebraic_foundations/Concepts/RealEmbeddableTraits--ToDouble.h b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/RealEmbeddableTraits--ToDouble.h new file mode 100644 index 00000000000..1be0c737445 --- /dev/null +++ b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/RealEmbeddableTraits--ToDouble.h @@ -0,0 +1,47 @@ + +/*! +\ingroup PkgAlgebraicFoundationsConcepts +\cgalconcept + +`AdaptableUnaryFunction` computes a double approximation of a real +embeddable number. + +Remark: In order to control the quality of approximation one has to resort +to methods that are specific to NT. There are no general guarantees whatsoever. + +\refines ::AdaptableUnaryFunction + +\sa ::RealEmbeddableTraits + +*/ + +class RealEmbeddableTraits::ToDouble { +public: + +/// \name Types +/// @{ + +/*! +Is `double`. +*/ +typedef Hidden_type result_type; + +/*! +Is `RealEmbeddableTraits::Type`. +*/ +typedef Hidden_type argument_type; + +/// @} + +/// \name Operations +/// @{ + +/*! +computes a double approximation of a real embeddable number. +*/ +result_type operator()(argument_type x); + +/// @} + +}; /* end RealEmbeddableTraits::ToDouble */ + diff --git a/Algebraic_foundations/doc/Algebraic_foundations/Concepts/RealEmbeddableTraits--ToInterval.h b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/RealEmbeddableTraits--ToInterval.h new file mode 100644 index 00000000000..e37c80b36cb --- /dev/null +++ b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/RealEmbeddableTraits--ToInterval.h @@ -0,0 +1,45 @@ + +/*! +\ingroup PkgAlgebraicFoundationsConcepts +\cgalconcept + +`AdaptableUnaryFunction` computes for a given real embeddable +number \f$ x\f$ a double interval containing \f$ x\f$. +This interval is represented by `std::pair`. + +\refines ::AdaptableUnaryFunction + +\sa ::RealEmbeddableTraits + +*/ + +class RealEmbeddableTraits::ToInterval { +public: + +/// \name Types +/// @{ + +/*! +Is `std::pair`. +*/ +typedef Hidden_type result_type; + +/*! +Is `RealEmbeddableTraits::Type`. +*/ +typedef Hidden_type argument_type; + +/// @} + +/// \name Operations +/// @{ + +/*! +computes a double interval containing \f$ x\f$. +*/ +result_type operator()(argument_type x); + +/// @} + +}; /* end RealEmbeddableTraits::ToInterval */ + diff --git a/Algebraic_foundations/doc/Algebraic_foundations/Concepts/RealEmbeddableTraits.h b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/RealEmbeddableTraits.h new file mode 100644 index 00000000000..9ee054a53df --- /dev/null +++ b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/RealEmbeddableTraits.h @@ -0,0 +1,117 @@ + +/*! +\ingroup PkgAlgebraicFoundationsConcepts +\cgalconcept + +A model of `RealEmbeddableTraits` is associated to a number type +`Type` and reflects the properties of this type with respect +to the concept `RealEmbeddable`. + +\hasModel `CGAL::Real_embeddable_traits` + +*/ + +class RealEmbeddableTraits { +public: + +/// \name Types +/// A model of `RealEmbeddableTraits` is supposed to provide: +/// @{ + +/*! +The associated number type. +*/ +typedef Hidden_type Type; + +/*! +Tag indicating whether the associated type is real embeddable. + +This is either `CGAL::Tag_true` or `CGAL::Tag_false`. +*/ +typedef Hidden_type Is_real_embeddable; + +/*! +This type specifies the return type of the predicates provided +by this traits. The type must be convertible to `bool` and +typically the type indeed maps to `bool`. However, there are also +cases such as interval arithmetic, in which it is `Uncertain` +or some similar type. + +*/ +typedef Hidden_type Boolean; + +/*! +This type specifies the return type of the `Sgn` functor. +The type must be convertible to `CGAL::Sign` and +typically the type indeed maps to `CGAL::Sign`. However, there are also +cases such as interval arithmetic, in which it is `Uncertain` +or some similar type. + +*/ +typedef Hidden_type Sign; + +/*! +This type specifies the return type of the `Compare` functor. +The type must be convertible to `CGAL::Comparison_result` and +typically the type indeed maps to `CGAL::Comparison_result`. However, there are also +cases such as interval arithmetic, in which it is `Uncertain` +or some similar type. + +*/ +typedef Hidden_type Comparison_result; + +/// @} + +/// \name Functors +/// In case the associated type is `RealEmbeddable` all functors are +/// provided. In case a functor is not provided, it is set to +/// `CGAL::Null_functor`. +/// @{ + +/*! + +A model of `RealEmbeddableTraits::IsZero` +In case `Type` is also model of `IntegralDomainWithoutDivision` +this is a model of `AlgebraicStructureTraits::IsZero`. +*/ +typedef Hidden_type Is_zero; + +/*! +A model of `RealEmbeddableTraits::Abs` +*/ +typedef Hidden_type Abs; + +/*! +A model of `RealEmbeddableTraits::Sgn` +*/ +typedef Hidden_type Sgn; + +/*! +A model of `RealEmbeddableTraits::IsPositive` +*/ +typedef Hidden_type Is_positive; + +/*! +A model of `RealEmbeddableTraits::IsNegative` +*/ +typedef Hidden_type Is_negative; + +/*! +A model of `RealEmbeddableTraits::Compare` +*/ +typedef Hidden_type Compare; + +/*! +A model of `RealEmbeddableTraits::ToDouble` +*/ +typedef Hidden_type To_double; + +/*! +A model of `RealEmbeddableTraits::ToInterval` +*/ +typedef Hidden_type To_interval; + +/// @} + +}; /* end RealEmbeddableTraits */ + diff --git a/Algebraic_foundations/doc/Algebraic_foundations/Concepts/RingNumberType.h b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/RingNumberType.h new file mode 100644 index 00000000000..c31c1755a72 --- /dev/null +++ b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/RingNumberType.h @@ -0,0 +1,38 @@ + +/*! +\ingroup PkgAlgebraicFoundationsConcepts +\cgalconcept + +The concept `RingNumberType` combines the requirements of the concepts +`IntegralDomainWithoutDivision` and `RealEmbeddable`. +A model of `RingNumberType` can be used as a template parameter +for Homogeneous kernels. + +\refines ::IntegralDomainWithoutDivision +\refines ::RealEmbeddable + +\hasModel \cpp built-in number types +\hasModel CGAL::Gmpq +\hasModel CGAL::Gmpz +\hasModel CGAL::Interval_nt +\hasModel CGAL::Interval_nt_advanced +\hasModel CGAL::Lazy_exact_nt +\hasModel CGAL::MP_Float +\hasModel CGAL::Gmpzf +\hasModel CGAL::Quotient +\hasModel leda_integer +\hasModel leda_rational +\hasModel leda_bigfloat +\hasModel leda_real + +\sa `FieldNumberType` + +*/ + +class RingNumberType { +public: + +/// @} + +}; /* end RingNumberType */ + diff --git a/Algebraic_foundations/doc/Algebraic_foundations/Concepts/UniqueFactorizationDomain.h b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/UniqueFactorizationDomain.h new file mode 100644 index 00000000000..0a4be4fa6b0 --- /dev/null +++ b/Algebraic_foundations/doc/Algebraic_foundations/Concepts/UniqueFactorizationDomain.h @@ -0,0 +1,47 @@ + +/*! +\ingroup PkgAlgebraicFoundationsConcepts +\cgalconcept + +A model of `UniqueFactorizationDomain` is an `IntegralDomain` with the +additional property +that the ring it represents is a unique factorization domain +(a.k.a. UFD or factorial ring), meaning that every non-zero non-unit +element has a factorization into irreducible elements that is unique +up to order and up to multiplication by invertible elements (units). +(An irreducible element is a non-unit ring element that cannot be factored +further into two non-unit elements. In a UFD, the irreducible elements +are precisely the prime elements.) + +In a UFD, any two elements, not both zero, possess a greatest common +divisor (gcd). + +Moreover, `CGAL::Algebraic_structure_traits< UniqueFactorizationDomain >` +is a model of `AlgebraicStructureTraits` providing: + +- `CGAL::Algebraic_structure_traits< UniqueFactorizationDomain >::Algebraic_type` +derived from `Unique_factorization_domain_tag` + +- `CGAL::Algebraic_structure_traits< UniqueFactorizationDomain >::Gcd` + +\refines ::IntegralDomain + +\sa ::IntegralDomainWithoutDivision +\sa ::IntegralDomain +\sa ::UniqueFactorizationDomain +\sa ::EuclideanRing +\sa ::Field +\sa ::FieldWithSqrt +\sa ::FieldWithKthRoot +\sa ::FieldWithRootOf +\sa ::AlgebraicStructureTraits + +*/ + +class UniqueFactorizationDomain { +public: + +/// @} + +}; /* end UniqueFactorizationDomain */ + diff --git a/Algebraic_foundations/doc/Algebraic_foundations/PackageDescription.txt b/Algebraic_foundations/doc/Algebraic_foundations/PackageDescription.txt new file mode 100644 index 00000000000..733b839dc50 --- /dev/null +++ b/Algebraic_foundations/doc/Algebraic_foundations/PackageDescription.txt @@ -0,0 +1,16 @@ +/// \defgroup PkgAlgebraicFoundations Algebraic Foundations +/// \defgroup PkgAlgebraicFoundationsConcepts Concepts +/// \ingroup PkgAlgebraicFoundations +/*! +\addtogroup PkgAlgebraicFoundations +\todo check generated documentation +\PkgDescriptionBegin{Algebraic Foundations} +\PkgPicture{Algebraic_foundations2.png} +\PkgAuthor{Michael Hemmer} +\PkgDesc{This package defines what algebra means for \cgal, in terms of concepts, classes and functions. The main features are: (i) explicit concepts for interoperability of types (ii) separation between algebraic types (not necessarily embeddable into the reals), and number types (embeddable into the reals). } +\PkgSince{3.3} +\cgalbib{cgal:h-af} +\license{\ref licensesLGPL "LGPL"} +\PkgDescriptionEnd +*/ + diff --git a/Algebraic_foundations/doc/Algebraic_foundations/fig/AlgebraicConceptHierarchy.gif b/Algebraic_foundations/doc/Algebraic_foundations/fig/AlgebraicConceptHierarchy.gif new file mode 100644 index 00000000000..584eed219b0 Binary files /dev/null and b/Algebraic_foundations/doc/Algebraic_foundations/fig/AlgebraicConceptHierarchy.gif differ diff --git a/Algebraic_foundations/doc/Algebraic_foundations/fig/AlgebraicConceptHierarchy.pdf b/Algebraic_foundations/doc/Algebraic_foundations/fig/AlgebraicConceptHierarchy.pdf new file mode 100644 index 00000000000..bfeddbfe9d8 Binary files /dev/null and b/Algebraic_foundations/doc/Algebraic_foundations/fig/AlgebraicConceptHierarchy.pdf differ diff --git a/Algebraic_foundations/doc/Algebraic_foundations/fig/Algebraic_foundations.png b/Algebraic_foundations/doc/Algebraic_foundations/fig/Algebraic_foundations.png new file mode 100644 index 00000000000..00816befb67 Binary files /dev/null and b/Algebraic_foundations/doc/Algebraic_foundations/fig/Algebraic_foundations.png differ diff --git a/Algebraic_foundations/doc/Algebraic_foundations/fig/Algebraic_foundations2.png b/Algebraic_foundations/doc/Algebraic_foundations/fig/Algebraic_foundations2.png new file mode 100644 index 00000000000..3db899859a5 Binary files /dev/null and b/Algebraic_foundations/doc/Algebraic_foundations/fig/Algebraic_foundations2.png differ