xsum 0.1.3

Fast Exact Summation of Floating-Point Numbers
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
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136

use crate::{constants::XSUM_THRESHOLD, traits::Xsum, XsumLarge, XsumSmall};

#[derive(Debug)]
enum XsumKind {
    XSmall(XsumSmall),
    XLarge(XsumLarge),
}

/// XsumAuto is efficient if vector or array size is unknown
///
/// It automatically select either XsumSmall or XsumLarge based on the number of added value
///
/// If the size if less than or equal to 1,000, use XsumSmall, otherwise, use XsumLarge
///
/// # Example
///
/// ```
/// use xsum::{Xsum, XsumAuto};
///
/// let mut xauto = XsumAuto::new();
/// xauto.add_list(&vec![1.0; 10]);
/// assert_eq!(xauto.sum(), 10.0); // use XsumSmall because input size is 10
///
/// xauto.add_list(&vec![1.0; 1_000]);
/// assert_eq!(xauto.sum(), 1_010.0); // use XsumLarge because input size is 1,010 in total
/// ```
#[derive(Debug)]
pub struct XsumAuto {
    m_xsum: XsumKind,
}

impl Default for XsumAuto {
    fn default() -> Self {
        Self::new()
    }
}

impl XsumAuto {
    #[inline(always)]
    fn transform_to_large(&mut self) {
        let should_transform = match &self.m_xsum {
            XsumKind::XSmall(xsmall) => xsmall.get_size_count() > XSUM_THRESHOLD,
            XsumKind::XLarge(_) => false,
        };
        if !should_transform {
            return;
        }

        let old_xsum = std::mem::replace(&mut self.m_xsum, XsumKind::XSmall(XsumSmall::default()));

        self.m_xsum = match old_xsum {
            XsumKind::XSmall(xsmall) => XsumKind::XLarge(XsumLarge::from_xsum_small(xsmall)),
            other @ XsumKind::XLarge(_) => other,
        };
    }
}

impl Xsum for XsumAuto {
    fn new() -> Self {
        Self {
            m_xsum: XsumKind::XSmall(XsumSmall::new()),
        }
    }

    /// ```
    /// use xsum::{Xsum, XsumAuto};
    ///
    /// let mut xauto = XsumAuto::new();
    /// xauto.add_list(&vec![1.0; 10]);
    /// assert_eq!(xauto.sum(), 10.0);
    /// ```
    fn add_list(&mut self, vec: &[f64]) {
        match &mut self.m_xsum {
            XsumKind::XSmall(xsmal) => {
                xsmal.add_list(vec);
                self.transform_to_large();
            }
            XsumKind::XLarge(xlarge) => {
                xlarge.add_list(vec);
            }
        }
    }

    /// ```
    /// use xsum::{Xsum, XsumAuto};
    ///
    /// let mut xauto = XsumAuto::new();
    /// let vec = vec![1.0; 1_000];
    /// for v in vec {
    ///     xauto.add(v);
    /// }
    /// assert_eq!(xauto.sum(), 1_000.0);
    /// ```
    #[inline(always)]
    fn add(&mut self, value: f64) {
        match &mut self.m_xsum {
            XsumKind::XSmall(xsmal) => {
                xsmal.add(value);
                self.transform_to_large();
            }
            XsumKind::XLarge(xlarge) => {
                xlarge.add(value);
            }
        }
    }

    /// ```
    /// use xsum::{Xsum, XsumAuto};
    ///
    /// let mut xauto = XsumAuto::new();
    /// xauto.add_list(&vec![1.0; 10]);
    /// assert_eq!(xauto.sum(), 10.0);
    /// ```
    fn sum(&mut self) -> f64 {
        match &mut self.m_xsum {
            XsumKind::XSmall(xsmall) => xsmall.sum(),
            XsumKind::XLarge(xlarge) => xlarge.sum(),
        }
    }

    /// ```
    /// use xsum::{Xsum, XsumAuto};
    ///
    /// let mut xauto = XsumAuto::new();
    /// xauto.add_list(&vec![1.0; 10]);
    /// assert_eq!(xauto.sum(), 10.0);
    ///
    /// xauto.clear();
    /// let res = xauto.sum(); // -0.0
    /// assert_eq!(res, -0.0);
    /// assert!(res.is_sign_negative());
    /// ```
    fn clear(&mut self) {
        *self = Self::default();
    }
}