feanor-math 3.5.18

A library for number theory, providing implementations for arithmetic in various rings and algorithms working on them.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65

use crate::field::Field;
use crate::ring::*;

/// Contains [`fraction_impl::FractionFieldImpl`], an implementation of the fraction
/// fields of an arbitrary principal ideal domain.
pub mod fraction_impl;

/// Trait for fields that are the field of fractions over a base ring.
///
/// Note that a field of fractions is usually the field of fractions of
/// many rings - in particular, every field is technically its own field
/// of fractions. However, such cases don't add any value, and this trait
/// is mainly designed and implemented for fields that have a "canonical" or
/// "natural" subring whose field of fractions they represent. In many
/// cases, this is the smallest subring whose fractions generate the whole
/// field, but this trait can also be implemented in other cases where it
/// makes sense.
#[stability::unstable(feature = "enable")]
pub trait FractionField: Field + RingExtension {
    /// Returns `a, b` such that the given element is `a/b`.
    ///
    /// The return value does not have to be reduced, i.e. `gcd(a, b)` is not
    /// guaranteed to be a unit (for rings that are not [`crate::pid::PrincipalIdealRing`], this
    /// is not even defined). Hence, when you want to convert the result to the base ring, use
    /// [`crate::divisibility::DivisibilityRing::checked_div()`] as follows:
    /// ```rust
    /// # use feanor_math::ring::*;
    /// # use feanor_math::divisibility::*;
    /// # use feanor_math::rings::fraction::*;
    /// # use feanor_math::rings::rational::*;
    /// # use feanor_math::primitive_int::*;
    /// fn to_base_ring<R>(ring: R, el: El<R>) -> Option<El<<R::Type as RingExtension>::BaseRing>>
    /// where
    ///     R: RingStore,
    ///     R::Type: FractionField,
    ///     <<R::Type as RingExtension>::BaseRing as RingStore>::Type: DivisibilityRing,
    /// {
    ///     let (a, b) = ring.as_fraction(el);
    ///     ring.base_ring().checked_div(&a, &b)
    /// }
    /// let QQ = RationalField::new(StaticRing::<i64>::RING);
    /// assert_eq!(Some(3), to_base_ring(QQ, QQ.from_fraction(6, 2)));
    /// ```
    fn as_fraction(&self, el: Self::Element) -> (El<Self::BaseRing>, El<Self::BaseRing>);

    /// Computes `num / den`.
    ///
    /// This is functionally equivalent, but may be faster than combining
    /// [`RingExtension::from()`] and [`Field::div()`].
    fn from_fraction(&self, num: El<Self::BaseRing>, den: El<Self::BaseRing>) -> Self::Element {
        self.div(&self.from(num), &self.from(den))
    }
}

/// [`RingStore`] corresponding to [`FractionField`]
#[stability::unstable(feature = "enable")]
pub trait FractionFieldStore: RingStore
where
    Self::Type: FractionField,
{
    delegate! { FractionField, fn as_fraction(&self, el: El<Self>) -> (El<<Self::Type as RingExtension>::BaseRing>, El<<Self::Type as RingExtension>::BaseRing>) }
    delegate! { FractionField, fn from_fraction(&self, num: El<<Self::Type as RingExtension>::BaseRing>, den: El<<Self::Type as RingExtension>::BaseRing>) -> El<Self> }
}

impl<R: RingStore> FractionFieldStore for R where R::Type: FractionField {}