circlejerk 0.1.1

A tiny in-memory opinion tracker for measuring group consensus
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

//! Track opinions and measure how strongly a group agrees.
//!
//! [`CircleJerk`] stores submitted opinions and exposes the most common one,
//! the share of submissions supporting it, and whether every submission is
//! identical.
//!
//! # Example
//!
//! ```
//! use circlejerk::CircleJerk;
//!
//! let mut group = CircleJerk::new();
//! group.agree("Rust is great");
//! group.agree("Rust is great");
//! group.agree("Other languages are fine too");
//!
//! assert_eq!(group.participants(), 3);
//! assert_eq!(group.dominant_opinion(), Some("Rust is great"));
//! assert_eq!(group.consensus_ratio(), 2.0 / 3.0);
//! assert!(!group.consensus());
//! ```
#![warn(missing_docs)]

use std::collections::HashMap;

/// An in-memory collection of submitted opinions.
///
/// Each call to [`agree`](Self::agree) counts as one participant. Participant
/// identities are not stored, so the same caller may submit more than once.
#[derive(Debug, Default)]
pub struct CircleJerk {
    opinions: HashMap<String, usize>,
    total: usize,
}

impl CircleJerk {
    /// Creates an empty collection with no participants.
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }

    /// Records one participant's agreement with an opinion.
    ///
    /// Equal strings are grouped as the same opinion.
    pub fn agree(&mut self, opinion: impl Into<String>) {
        *self.opinions.entry(opinion.into()).or_insert(0) += 1;
        self.total += 1;
    }

    /// Returns `true` when every participant submitted the same opinion.
    ///
    /// An empty collection does not have consensus and returns `false`.
    #[must_use]
    pub fn consensus(&self) -> bool {
        if self.total == 0 {
            return false;
        }

        self.opinions
            .values()
            .copied()
            .max()
            .is_some_and(|count| count == self.total)
    }

    /// Returns the fraction of participants supporting the dominant opinion.
    ///
    /// The result is between `0.0` and `1.0`. An empty collection returns
    /// `0.0`.
    #[must_use]
    pub fn consensus_ratio(&self) -> f64 {
        if self.total == 0 {
            return 0.0;
        }

        let max = self.opinions.values().copied().max().unwrap_or(0);
        max as f64 / self.total as f64
    }

    /// Returns an opinion with the most support.
    ///
    /// Returns `None` when the collection is empty. If multiple opinions are
    /// tied for the most support, any one of them may be returned.
    #[must_use]
    pub fn dominant_opinion(&self) -> Option<&str> {
        self.opinions
            .iter()
            .max_by_key(|(_, count)| *count)
            .map(|(opinion, _)| opinion.as_str())
    }

    /// Returns the number of submitted opinions.
    #[must_use]
    pub fn participants(&self) -> usize {
        self.total
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn perfect_circlejerk() {
        let mut cj = CircleJerk::new();

        cj.agree("Rust is the best language");
        cj.agree("Rust is the best language");
        cj.agree("Rust is the best language");

        assert!(cj.consensus());
        assert_eq!(cj.consensus_ratio(), 1.0);
        assert_eq!(cj.dominant_opinion(), Some("Rust is the best language"));
    }

    #[test]
    fn dissent_detected() {
        let mut cj = CircleJerk::new();

        cj.agree("Rust is the best language");
        cj.agree("Rust is the best language");
        cj.agree("C++ is fine actually");

        assert!(!cj.consensus());
        assert_eq!(cj.consensus_ratio(), 2.0 / 3.0);
    }
}