feat(electosim): first commit

feat(electosim): first commit

First commit with the base code, docs, and workflows

force

ci(tests): add cargo install tarpaulin

force

ci(tests): add cargo install tarpaulin

force

add cache

e

.github/workflows/publish.yml

@@ -0,0 +1,24 @@
+on:
+  push:
+    tags:
+      - "v*"
+
+name: Cargo Publish
+
+jobs:
+  publish:
+    name: Publish
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Set up Rust
+        uses: actions-rs/toolchain@v1
+        with:
+          toolchain: stable
+
+      - name: Publish
+        run: cargo publish --token ${{ secrets.CARGO_TOKEN }}
+        env:
+          CARGO_INCREMENTAL: 0

.github/workflows/tests.yml

@@ -0,0 +1,48 @@
+on:
+  push:
+    branches:
+      - dev
+  pull_request:
+    branches:
+      - dev
+
+name: Rust Testing and coverage
+
+jobs:
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v2
+
+      - name: Cache cargo registry
+        uses: actions/cache@v2
+        with:
+          path: ~/.cargo
+          key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-cargo-
+
+      - name: Install stable toolchain
+        uses: actions-rs/toolchain@v1
+        with:
+          toolchain: stable
+          override: true
+
+      - name: Install tarpaulin
+        run: cargo install cargo-tarpaulin
+
+      - name: Run cargo-tarpaulin
+        uses: actions-rs/cargo@v1
+        with:
+          command: tarpaulin
+          args: --all --all-features --out Xml
+        env:
+          CARGO_INCREMENTAL: 0
+
+      - name: Upload to codecov.io
+        uses: codecov/codecov-action@v4.0.1
+        with:
+          token: ${{secrets.CODECOV_TOKEN}}

.gitignore

@@ -0,0 +1 @@
+/target

Cargo.toml

@@ -0,0 +1,7 @@
+[package]
+name = "electosim"
+version = "0.1.0"
+edition = "2021"
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]

LICENSE

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2024 Eduardo González Vaquero
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

src/interface.rs

@@ -0,0 +1,23 @@
+/// Trait representing an entity that has votes.
+pub trait WithVotes {
+    /// Returns the number of votes.
+    fn get_votes(&self) -> u32;
+
+    /// Sets the number of votes.
+    fn set_votes(&mut self, votes: u32);
+}
+
+/// A trait for objects that have seats.
+pub trait WithSeats {
+    /// Returns the number of seats.
+    fn get_seats(&self) -> u16;
+
+    /// Sets the number of seats.
+    fn set_seats(&mut self, seats: u16);
+
+    /// Increases the number of seats by a given amount.
+    fn increase_seats(&mut self, n: u16) {
+        let actual_seats = self.get_seats();
+        self.set_seats(actual_seats + n);
+    }
+}

src/lib.rs

@@ -0,0 +1,122 @@
+//! # ElectoSIM
+//! ElectoSIM is a library that allows you to simulate simple elections using different methods.
+//! ## Methods
+//! The following methods are available:
+//! - D'Hondt
+//! - Webster/Sainte-Laguë
+//! - Adams
+//! - Imperiali
+//! - Huntington-Hill
+//! - Danish
+//! - Hare-Niemeyer
+//! - Hagenbach-Bischoff
+//! - Imperiali - Quotient
+//! - Droop
+//! - Winner Takes All
+//!
+//! ## Usage
+//!
+//! ```rust
+//! use electosim::methods::Method;
+//! use electosim::models::Candidacy;
+//!
+//! use electosim::SimpleElection;
+//!
+//! fn main() {
+//!    let mut election = SimpleElection {
+//!         results: vec![
+//!             Candidacy::new(2010, 9),
+//!             Candidacy::new(1018, 4),
+//!             Candidacy::new(86, 0),
+//!             Candidacy::new(77, 0),
+//!         ],
+//!         seats: 13,
+//!         method: Method::HAGENBASCHBISCHOFF,
+//!    };
+//!
+//!     election.compute().expect("Can not compute method");
+//!     election.results.iter().for_each(|c| println!("{:?}", c));
+//! }
+//! ```
+//!
+//! The first statement in the `main` function creates a new [SimpleElection] with the candidates, the number of seats available, and the method to be used. The `compute` method is then called to compute the election results. Finally, the results are printed to the console.
+//!
+//! # `compute_` functions
+//! A method is a function with type `fn(&mut Vec<T>, u16) -> Result<(), &str>` where `T` is a type that implements the [`WithVotes`][interface::WithVotes] and [`WithSeats`][interface::WithSeats] traits.
+//! You can use the `compute_` functions directly if you want to compute the election results without using the [SimpleElection] struct. For example:
+//! ```rust
+//! use electosim::methods::divisor::compute_dhondt;
+//! use electosim::models::Candidacy;
+//!
+//! fn main() {
+//!    let mut candidacies = vec![
+//!         Candidacy::new(2010, 0),
+//!         Candidacy::new(1018, 0),
+//!         Candidacy::new(86, 0),
+//!         Candidacy::new(77, 0),
+//!     ];
+//!
+//!    compute_dhondt(&mut candidacies, 13).unwrap();
+//!
+//!    candidacies.iter().for_each(|c| println!("{:?}", c));
+//! }
+//! ```
+//!
+//! There are some implementations of the `compute_` functions in the [methods::divisor] (ex: D'hondt) and [methods::remainder] (ex: Hare) modules.
+
+pub mod interface;
+pub mod methods;
+pub mod models;
+pub mod utils;
+
+use methods::{get_method_function, Method};
+use models::Candidacy;
+
+/// Represents a simple election.
+pub struct SimpleElection {
+    /// The results of the election.
+    pub results: Vec<Candidacy>,
+    /// The number of seats available in the election.
+    pub seats: u16,
+    /// The method used for the election.
+    pub method: Method,
+}
+
+impl SimpleElection {
+    /// Computes the election results using the specified method.
+    ///
+    /// # Arguments
+    ///
+    /// * `self` - A mutable reference to the `SimpleElection` struct.
+    ///
+    /// # Returns
+    ///
+    /// Returns `Ok(())` if the computation is successful, otherwise returns an `Err` with an error message.
+    pub fn compute(&mut self) -> Result<(), &str> {
+        let fun = get_method_function(self.method);
+        fun(&mut self.results, self.seats)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::models::Candidacy;
+
+    #[test]
+    fn test_simple_election() {
+        let mut election = SimpleElection {
+            results: vec![
+                Candidacy::new(2010, 9),
+                Candidacy::new(1018, 4),
+                Candidacy::new(86, 0),
+                Candidacy::new(77, 0),
+            ],
+            seats: 13,
+            method: Method::DHONDT,
+        };
+
+        election.compute().unwrap();
+        election.results.iter().for_each(|c| println!("{:?}", c));
+    }
+}

src/methods/divisor/mod.rs

@@ -0,0 +1,135 @@
+//! # Divisor methods
+//! Each seat is assigned to the candidate with the highest result of the division of the number of votes by a divisor.
+//! The divisor is a function that takes the number of seats won by the candidate and returns a float number.
+//!
+//! All divisor methods are implemented based on the [compute_divisor_method] function.
+
+use crate::{
+    interface::{WithSeats, WithVotes},
+    utils::clear_results,
+};
+
+/// A factory for divisor methods.
+///
+///
+/// # Arguments
+///
+/// * `results` - A mutable reference to a vector of candidates.
+/// * `seats` - The number of seats available in the election.
+/// * `divisor` - A function that takes the number of seats won by the candidate and returns a float number.
+///
+/// # Example (D'Hondt method)
+///
+/// ```rust
+/// use electosim::methods::divisor::compute_divisor_method;
+/// use electosim::models::Candidacy;
+///
+/// let mut candidacies = vec![
+///    Candidacy::new(2010, 0),
+///    Candidacy::new(1018, 0),
+///    Candidacy::new(86, 0),
+///    Candidacy::new(77, 0),
+/// ];
+///
+/// compute_divisor_method(&mut candidacies, 13, |s| (s + 1) as f32).unwrap();
+/// ```
+pub fn compute_divisor_method<'a, T>(
+    results: &'a mut Vec<T>,
+    seats: u16,
+    divisor: impl Fn(u16) -> f32,
+) -> Result<(), &'a str>
+where
+    T: WithSeats + WithVotes,
+{
+    clear_results(results);
+
+    for _ in 0..seats {
+        let better_idx = results
+            .iter()
+            .map(|c| {
+                let votes = c.get_votes() as f32;
+                let seats = c.get_seats();
+                let div = divisor(seats);
+
+                votes / div
+            })
+            .enumerate()
+            .max_by(|(_, a), (_, b)| a.total_cmp(b));
+
+        match better_idx {
+            Some((idx, _)) => results[idx].increase_seats(1),
+            None => return Err("EMPTY_RESULTS"),
+        }
+    }
+
+    Ok(())
+}
+
+#[allow(dead_code)]
+pub fn compute_dhondt<T>(results: &mut Vec<T>, seats: u16) -> Result<(), &str>
+where
+    T: WithSeats + WithVotes,
+{
+    compute_divisor_method(results, seats, |s| (s + 1) as f32)
+}
+
+#[allow(dead_code)]
+pub fn compute_sainte_lague<T>(results: &mut Vec<T>, seats: u16) -> Result<(), &str>
+where
+    T: WithSeats + WithVotes,
+{
+    compute_divisor_method(results, seats, |s| (2 * s + 1) as f32)
+}
+
+#[allow(dead_code)]
+pub fn compute_adams<T>(results: &mut Vec<T>, seats: u16) -> Result<(), &str>
+where
+    T: WithSeats + WithVotes,
+{
+    compute_divisor_method(results, seats, |s| s as f32)
+}
+
+#[allow(dead_code)]
+pub fn compute_imperiali<T>(results: &mut Vec<T>, seats: u16) -> Result<(), &str>
+where
+    T: WithSeats + WithVotes,
+{
+    compute_divisor_method(results, seats, |s| (s + 2) as f32)
+}
+
+#[allow(dead_code)]
+pub fn compute_huntington_hill<T>(results: &mut Vec<T>, seats: u16) -> Result<(), &str>
+where
+    T: WithSeats + WithVotes,
+{
+    compute_divisor_method(results, seats, |s| ((s * (s + 1)) as f32).sqrt())
+}
+
+#[allow(dead_code)]
+pub fn compute_danish<T>(results: &mut Vec<T>, seats: u16) -> Result<(), &str>
+where
+    T: WithSeats + WithVotes,
+{
+    compute_divisor_method(results, seats, |s| (3 * s + 1) as f32)
+}
+
+#[allow(dead_code)]
+pub fn compute_wta<T>(results: &mut Vec<T>, seats: u16) -> Result<(), &str>
+where
+    T: WithSeats + WithVotes,
+{
+    clear_results(results);
+
+    let better_idx = results
+        .iter()
+        .map(|c| c.get_votes())
+        .enumerate()
+        .max_by(|(_, a), (_, b)| a.cmp(b));
+
+    match better_idx {
+        Some((idx, _)) => results[idx].set_seats(seats),
+        None => return Err("EMPTY_RESULTS"),
+    }
+
+    Ok(())
+}