tktax-year-comparison

tktax-year-comparison is a Rust crate focused on performing comparative accounting between multiple fiscal years for the TKTAX ecosystem. It provides tools to compute cross-year differentials and construct multi-year summaries. This library is especially helpful for uncovering changes in total monetary amounts and extracting year-by-year data across diverse sets of transactions.

Features

1. Differential Analysis

   • Compare totals between two distinct Account instances.
   • Obtain a YearComparison struct containing each year’s identifier and the total difference in amounts.

2. Multi-Year Aggregation

   • Consolidate data across any number of Accounts.
   • Produce a MultiYearSummary that maps each TrackedYear to a summed MonetaryAmount.
   • Facilitates high-level audits of various yearly totals.

3. Extensibility

   • Straightforward to integrate additional fields or metrics (e.g., totals of certain transaction types).
   • Built to interoperate with other TKTAX libraries, such as tktax_money and tktax_transaction.

Usage Example

Below is a minimal code sample illustrating how to compare two years and then aggregate a set of Accounts:

use tktax_year_comparison::{
    DifferentialAnalysis,
    aggregate_multi_year,
    YearComparison,
    MultiYearSummary,
};

// Suppose we have two `Account` instances from different years: `acct_2021` and `acct_2022`.
// Both satisfy `DifferentialAnalysis` from this crate.

if let Some(diff) = acct_2021.compare_years(&acct_2022) {
    println!("Year A: {:?}", diff.year_a);
    println!("Year B: {:?}", diff.year_b);
    println!("Difference: {:?}", diff.total_difference);
} else {
    println!("Unable to perform cross-year comparison.");
}

// To aggregate a slice of `Account`s spanning different years:
let accounts = vec![acct_2021, acct_2022, /* possibly more */];
let summary = aggregate_multi_year(&accounts);
for (year, total) in &summary.yearly_totals {
    println!("Year: {:?}, Summed Amount: {:?}", year, total);
}

Data Structures

• YearComparison
  - Tracks the two compared years (year_a and year_b).
  - Stores the total_difference (year_b - year_a).

• MultiYearSummary
  - Maintains a HashMap<TrackedYear, MonetaryAmount>, mapping each TrackedYear to its aggregated total.

Crate Integration

To incorporate tktax-year-comparison into your project, add it to your Cargo.toml:

[dependencies]
tktax-year-comparison = "0.1"

Then import it in your Rust code:

use tktax_year_comparison::*;

License

Licensed under either of

• Apache License, Version 2.0,
• MIT license

at your option.

For advanced or specialized usage (e.g., computing nuanced debits/credits breakdowns), consider extending YearComparison or MultiYearSummary. Their internal fields remain amenable to expansions to capture more thorough financial data (Latin: data pecuniaria, Greek: δεδομένα λογιστικά).

Contributions and feedback welcome via the project repository.