feanor_math/rings/fraction/
mod.rs

1use crate::field::Field;
2use crate::ring::*;
3
4/// Contains [`fraction_impl::FractionFieldImpl`], an implementation of the fraction
5/// fields of an arbitrary principal ideal domain.
6pub mod fraction_impl;
7
8/// Trait for fields that are the field of fractions over a base ring.
9///
10/// Note that a field of fractions is usually the field of fractions of
11/// many rings - in particular, every field is technically its own field
12/// of fractions. However, such cases don't add any value, and this trait
13/// is mainly designed and implemented for fields that have a "canonical" or
14/// "natural" subring whose field of fractions they represent. In many
15/// cases, this is the smallest subring whose fractions generate the whole
16/// field, but this trait can also be implemented in other cases where it
17/// makes sense.
18#[stability::unstable(feature = "enable")]
19pub trait FractionField: Field + RingExtension {
20    /// Returns `a, b` such that the given element is `a/b`.
21    ///
22    /// The return value does not have to be reduced, i.e. `gcd(a, b)` is not
23    /// guaranteed to be a unit (for rings that are not [`crate::pid::PrincipalIdealRing`], this
24    /// is not even defined). Hence, when you want to convert the result to the base ring, use
25    /// [`crate::divisibility::DivisibilityRing::checked_div()`] as follows:
26    /// ```rust
27    /// # use feanor_math::ring::*;
28    /// # use feanor_math::divisibility::*;
29    /// # use feanor_math::rings::fraction::*;
30    /// # use feanor_math::rings::rational::*;
31    /// # use feanor_math::primitive_int::*;
32    /// fn to_base_ring<R>(ring: R, el: El<R>) -> Option<El<<R::Type as RingExtension>::BaseRing>>
33    /// where
34    ///     R: RingStore,
35    ///     R::Type: FractionField,
36    ///     <<R::Type as RingExtension>::BaseRing as RingStore>::Type: DivisibilityRing,
37    /// {
38    ///     let (a, b) = ring.as_fraction(el);
39    ///     ring.base_ring().checked_div(&a, &b)
40    /// }
41    /// let QQ = RationalField::new(StaticRing::<i64>::RING);
42    /// assert_eq!(Some(3), to_base_ring(QQ, QQ.from_fraction(6, 2)));
43    /// ```
44    fn as_fraction(&self, el: Self::Element) -> (El<Self::BaseRing>, El<Self::BaseRing>);
45
46    /// Computes `num / den`.
47    ///
48    /// This is functionally equivalent, but may be faster than combining
49    /// [`RingExtension::from()`] and [`Field::div()`].
50    fn from_fraction(&self, num: El<Self::BaseRing>, den: El<Self::BaseRing>) -> Self::Element {
51        self.div(&self.from(num), &self.from(den))
52    }
53}
54
55/// [`RingStore`] corresponding to [`FractionField`]
56#[stability::unstable(feature = "enable")]
57pub trait FractionFieldStore: RingStore
58where
59    Self::Type: FractionField,
60{
61    delegate! { FractionField, fn as_fraction(&self, el: El<Self>) -> (El<<Self::Type as RingExtension>::BaseRing>, El<<Self::Type as RingExtension>::BaseRing>) }
62    delegate! { FractionField, fn from_fraction(&self, num: El<<Self::Type as RingExtension>::BaseRing>, den: El<<Self::Type as RingExtension>::BaseRing>) -> El<Self> }
63}
64
65impl<R: RingStore> FractionFieldStore for R where R::Type: FractionField {}
feanor_math/rings/fraction/mod.rs

feanor_math/rings/fraction/
mod.rs
