Struct tallystick::plurality::PluralityTally

pub struct PluralityTally<T, C = u64> where
    T: Eq + Clone + Hash,
    C: Copy + PartialOrd + AddAssign + Num + NumCast,  { /* fields omitted */ }

A generic plurality tally.

Generics:

• T: The candidate type.
• C: The count type. u64 is recommended, but can be modified to use a different type for counting votes (eg f64 for fractional vote weights).

Example:

   use tallystick::plurality::PluralityTally;

   // A tally with string candidates, `f64` counting, and a single winner.
   // f64 counting lets us use fractional vote weights.
   let mut tally = PluralityTally::<&str, f64>::new(1);
   tally.add_weighted("Alice", 5.25); // A vote for Alice with a weight of `5.25`
   tally.add_weighted("Bob", 0.25);   // A vote for Bob with a weight of `0.25`
   tally.add("Carol");                // A vote for Carol with an implicit weight of `1.0`
   let winners = tally.winners();

Methods

impl<T, C> PluralityTally<T, C> where
    T: Eq + Clone + Hash,
    C: Copy + PartialOrd + AddAssign + Num + NumCast, 

pub fn new(num_winners: u32) -> Self

Create a new PluralityTally with the given number of winners.

If there is a tie, the number of winners might be more than num_winners. (See winners() for more information on ties.)

pub fn with_capacity(num_winners: u32, expected_candidates: usize) -> Self

Create a new PluralityTally with the given number of winners, and number of expected candidates.

pub fn add(&mut self, vote: T)

Add a new vote

pub fn add_ref(&mut self, vote: &T)

Add a vote by reference.

pub fn add_weighted(&mut self, vote: T, weight: C)

Add a weighted vote. By default takes a weight as a usize integer, but can be customized by using PluralityTally with a custom vote type.

pub fn add_weighted_ref(&mut self, vote: &T, weight: C)

Add a weighted vote by reference.

pub fn candidates(&self) -> Vec<T>

Get a list of all candidates seen by this tally. Candidates are returned in no particular order.

pub fn winners(&self) -> RankedWinners<T>

Get a ranked list of winners. Winners with the same rank are tied. The number of winners might be greater than the requested num_winners if there is a tie.

Example

   use tallystick::plurality::DefaultPluralityTally;

   let mut tally = DefaultPluralityTally::new(2); // We ideally want only 2 winnners
   tally.add_weighted("Alice", 3);
   tally.add_weighted("Cir", 2);
   tally.add_weighted("Bob", 2);
   tally.add("Dave"); // implicit weight of 1

   let winners = tally.winners();

   println!("We have {} winners", winners.len());
   // Prints: "We have 3 winners" (due to Cir and Bob being tied)

   for (winner, rank) in winners.iter() {
      println!("{} has a rank of {}", winner, rank);
   }
   // Prints:
   //   Alice has a rank of 0
   //   Bob has a rank of 1
   //   Cir has a rank of 1

pub fn totals(&self) -> Vec<(T, C)>

Get vote totals for this tally.

Example

   use tallystick::plurality::DefaultPluralityTally;

   let mut tally = DefaultPluralityTally::new(1);
   for _ in 0..30 { tally.add("Alice") }
   for _ in 0..10 { tally.add("Bob") }

   for (candidate, num_votes) in tally.totals().iter() {
      println!("{} got {} votes", candidate, num_votes);
   }
   // Prints:
   //   Alice got 30 votes
   //   Bob got 10 votes

pub fn ranked(&self) -> Vec<(T, u32)>

Get a ranked list of all candidates. Candidates with the same rank are tied. Candidates are ranked in ascending order. The highest ranked candidate has a rank of 0.

Example

   use tallystick::plurality::DefaultPluralityTally;

   let mut tally = DefaultPluralityTally::new(1);
   for _ in 0..50 { tally.add("Alice") }
   for _ in 0..40 { tally.add("Bob") }
   for _ in 0..30 { tally.add("Carlos") }
    
   for (candidate, rank) in tally.ranked().iter() {
      println!("{} has a rank of {}", candidate, rank);
   }
   // Prints:
   //   Alice has a rank of 0
   //   Bob has a rank of 1
   //   Carlos has a rank of 2