devela/num/int/wrapper/
impl_stats.rs

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
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
// devela::math::ops::fns::stats
//
//! Implements statistics-related methods for [`Int`].
//
// TOC
// - generic:
//   - median_vec
// - sint|uint:
//   - midpoint
//   - average IMPROVE (harmonic, etc…?)
//   - median WIP
//   ...

#![allow(unused, reason = "WIP")]

use super::*;
use crate::{fsize, isize_up, paste, usize_up};
// #[cfg(feature = "alloc")]
// use ::_alloc::vec::Vec;

// TODO
// /// Returns the median
// ///
// /// The median is the middle value of a sorted dataset.
// /// If the dataset length is even, the median is the average of the two middle numbers.
// #[cfg(feature = "alloc")]
// #[cfg_attr(feature = "nightly", doc(cfg(feature = "alloc")))]
// pub fn median_vec<T: Ord>(mut data: Vec<T>) -> Option<f32> {
//     data.sort_unstable();
//     let len = data.len();
//     let mid = len / 2;
//
//     if len % 2 == 0 {
//         Some((data[mid - 1] + data[mid]) as f32 / 2.0)
//     } else {
//         Some(data[mid] as f32)
//     }
// }

/// Implements statistics-related methods for [`Int`].
///
/// # Args
/// $t:   the input/output type
/// $cap: the capability feature that enables the given implementation. E.g "_int_i8".
/// $ut:  the corresponding unsigned type of the same size as $t (for midpoint).
/// $up:  the upcasted type to do the operations on (the ones that can overflow).
/// $ft:  the corresponding floating-point type for some operations.
///
/// $d:   the doclink suffix for the method name.
macro_rules! impl_stats {
    () => {
        impl_stats![signed
            i8    :"_int_i8"    :u8    |i16      :f32   |"",
            i16   :"_int_i16"   :u16   |i32      :f32   |"-1",
            i32   :"_int_i32"   :u32   |i64      :f32   |"-2",
            i64   :"_int_i64"   :u64   |i128     :f64   |"-3",
            i128  :"_int_i128"  :u128  |i128     :f64   |"-4",
            isize :"_int_isize" :usize |isize_up :fsize |"-5"
        ];
        impl_stats![unsigned
            u8    :"_int_u8"    :u8    |u16      :f32   |"-6",
            u16   :"_int_u16"   :u16   |u32      :f32   |"-7",
            u32   :"_int_u32"   :u32   |u64      :f32   |"-8",
            u64   :"_int_u64"   :u64   |u128     :f64   |"-9",
            u128  :"_int_u128"  :u128  |u128     :f64   |"-10",
            usize :"_int_usize" :usize |usize_up :fsize |"-11"
        ];

        // impl_stats![unsigned
        //     u8:u16:u8:f32,
        //     u16:u32:u16:f32,
        //     u32:u64:u32:f32,
        //     u64:u128:u64:f64,
        //     u128:u128:u128:f64,
        //     usize:usize:usize:fsize
        // ];
    };
    (signed $( $t:ty : $cap:literal : $ut:ty | $up:ty : $ft:ty | $d:literal ),+) => {
        $( impl_stats![@signed   $t:$cap:$ut|$up:$ft |$d]; )+
    };
    (unsigned $( $t:ty : $cap:literal : $ut:ty | $up:ty : $ft:ty | $d:literal ),+) => {
        $( impl_stats![@unsigned $t:$cap:$ut|$up:$ft |$d]; )+
    };
    (
    // implements signed ops
    @signed $t:ty : $cap:literal : $ut:ty | $up:ty : $ft:ty | $d:literal ) => { paste! {
        #[doc = crate::doc_availability!(feature = $cap)]
        ///
        #[doc = "# Integer statistics related methods for `" $t "`\n\n"]
        #[doc = "- [midpoint](#method.midpoint" $d ")"]
        #[cfg(feature = $cap )]
        impl Int<$t> {
        }

        /*
        /* signed midpoint */
        #[doc="Returns the middle point between two [`" $t "`]."]
        ///
        /// The result is always rounded towards negative infinity.
        ///
        /// # Examples
        /// ```
        #[doc ="use devela::math::ops::midpoint_" $t ";\n\n"]
        #[doc = "assert_eq![midpoint_" $t "(64, 36), 50];"]
        #[doc = "assert_eq![midpoint_" $t "(36, 64), 50];"]
        #[doc ="assert_eq![midpoint_" $t "(-64, 36), -14];"]
        #[doc ="assert_eq![midpoint_" $t "(64, -36), 14];"]
        /// ```
        // Impl based on rust's std `midpoint` unstable impl.
        #[inline] #[must_use]
        pub const fn [<midpoint_ $t >](a: $t, b: $t) -> $t {
            const U: $ut = <$t>::MIN.unsigned_abs();
            // Map $t to $ut. e.g.: i8 [-128; 127] to [0; 255]
            #[inline]
            const fn map(a: $t) -> $ut { (a as $ut) ^ U }
            // Map $ut to $t. e.g.: u8 [0; 255] to [-128; 127]
            #[inline]
            const fn demap(a: $ut) -> $t { (a ^ U) as $t }

            demap([<midpoint_ $ut >](map(a), map(b)))
        }

        /* */

        #[doc = "Returns the average of `N` [`" $t "`]s as an [`" $ft "`]."]
        #[inline]
        #[must_use]
        pub fn [<average_float_ $t>]<const N: usize>(arr: [$t; N]) -> $ft {
            let (mut sum, mut i) = (0, 0);
            while i < N { sum += arr[i]; i += 1; }
            sum as $ft / (N as $ft)
        }

        #[doc = "Returns the median of (ordered) `N` [`" $t "`]s as an [`" $ft "`]."]
        pub fn [<median_float_ $t>]<const N: usize>(arr: [$t; N]) -> Option<$ft> {
            let mid = N / 2;

            if N % 2 == 0 {
                Some((arr[mid - 1] + arr[mid]) as $ft / 2.0)
            } else {
                Some(arr[mid] as $ft)
            }
        }

        /* ... */

        // TODO: return the sum, avoid making a div version per each…

        // pub const fn standard_deviation<const N: usize>(arr: [f64; N]) -> f64 {
        //     variance::<N>(arr).sqrt()
        // }

        ///
        #[inline]
        #[must_use]
        pub const fn [<average_floor_ $t>]<const LEN: usize>(arr: [$t; LEN]) -> $t {
            let (mut sum, mut i) = (0, 0);
            while i < LEN { sum += arr[i]; i += 1; }
            sum / (LEN as $t)
        }

        ///
        #[inline]
        #[must_use]
        pub const fn [<average_ceil_ $t>]<const LEN: usize>(arr: [$t; LEN]) -> $t {
            let (mut sum, mut i) = (0, 0);
            while i < LEN { sum += arr[i]; i += 1; }
            [<div_ceil_ $t>](sum, LEN as $t)
        }
        */
    }};
    // implements unsigned ops
    (@unsigned $t:ty : $cap:literal : $ut:ty | $up:ty : $ft:ty | $d:literal ) => { paste! {
        // /* unsigned midpoint */
        //
        // #[doc="Returns the middle point between two [`" $t "`]."]
        // ///
        // /// The result is always rounded towards negative infinity.
        // ///
        // /// # Examples
        // /// ```
        // #[doc ="use devela::math::ops::midpoint_" $t ";\n\n"]
        // #[doc = "assert_eq![midpoint_" $t "(64, 36), 50];"]
        // #[doc = "assert_eq![midpoint_" $t "(64, 36), 50];"]
        // /// ```
        // // Impl based on rust's std `midpoint` unstable impl.
        // #[inline]
        // #[must_use]
        // pub const fn [<midpoint_ $t >](a: $t, b: $t) -> $t {
        //     // Use the well known branchless algorithm from Hacker's Delight to compute
        //     // `(a + b) / 2` without overflowing: `((a ^ b) >> 1) + (a & b)`.
        //     ((a ^ b) >> 1) + (a & b)
        // }

        /* unsigned stats */
    }};
}
impl_stats!();