Crate suukon

This library provides support for converting numerals across various numeral systems. For easy and ergonomic usage, the library provides a Numeral trait that is implemented for all types that implement the ToString trait. This allows for easy conversion of numbers from one numeral system to another.

However the Numeral trait is mainly just a wrapper for the convert_num function, which might add unnecessary overhead when converting a large amount of numbers with the same settings. Therefore, the library still provides access to the conversion functions directly from their respective modules.

Supported Numeral systems

The main target of this library is to support any kind of numeral system, with the following numeral systems currently supported:

• Japanese
• Chinese
• Roman
• Egyptian
• Counting Rods

If you find any conversion issues or have any suggestions, please feel free to open an issue on the GitLab repository.

Usage

To use this library, simply use the methods provided by the Numeral trait, Numeral::to_numeral and Numeral::from_numeral.

The Setting enum is used to specify additional settings for the conversion, for convenience a Settings type is provided, which is just a Vec<Setting>. However settings are only supported targeting numeral systems, when converting back to arabic numerals, pattern matching is used to determine the settings automatically.

use suukon::{Numeral, NumeralSystem, Setting};

// Converting into the regular notation of the japanese numeral system
// using the Financial setting.
assert_eq!(
    Some("壱萬弐仟参佰肆拾伍".to_string()),
    "12345".to_numeral(NumeralSystem::Japanese, vec![Setting::Financial])
);

// Converting the same number into the short notation of the japanese numeral system
// using the ShortNotation setting.
assert_eq!(
    Some("1.2345万".to_string()),
    "12345".to_numeral(NumeralSystem::Japanese, vec![Setting::ShortNotation])
);

Alternative Usage

As already mentioned, to avoid the overhead of the Numeral trait, you may use the functions provided by the modules directly. However you will be trading the abstraction provided by the Setting enum for boolean arguments, which may lead to less readable code.

use suukon::roman::num_to_roman;
use suukon::chinese::num_to_hanzi;

// Since the roman numeral system does not support any settings, the signature
// of the function is relatively simple and straight forward.
assert_eq!(
   Some("MMXXIV".to_string()),
   num_to_roman("2024".to_string())
);

// But fast forward to the chinese numeral system, which supports a variety of settings.
// The signature of the function is more complex and less readable.
assert_eq!(
    Some("二千〇二十四".to_string()),
    num_to_hanzi(
        "2024".to_string(),
        false,
        false,
        false,
        false,
        false,
        false,
        true
    )
);

As you can see, the signature of the function is less readable and may lead to confusion about the order of the settings. Therefore, it is recommended to use the Numeral trait for the sake of readability. But ultimately it is up to you to decide which approach to use.

References

• Wikipedia - List of numeral systems
• Wikipedia - Japanese numerals
• Wikipedia - Chinese numerals
• Wikipedia - Roman numerals
• Wikipedia - Egyptian numerals
• Wikipedia - Counting Rods

Re-exports

• pub use japanese::num_to_kanji;
• pub use japanese::kanji_to_num;
• pub use chinese::num_to_hanzi;
• pub use chinese::hanzi_to_num;
• pub use roman::num_to_roman;
• pub use roman::roman_to_num;
• pub use egyptian::num_to_hieroglyph;
• pub use egyptian::hieroglyph_to_num;
• pub use rods::num_to_rods;
• pub use rods::rods_to_num;

Modules

• chinese
  Chinese Numeral System
• egyptian
  Egyptian Numeral System
• japanese
  Japanese Numeral System
• rods
  Counting Rod Numeral System
• roman
  Roman Numeral System

Enums

• NumeralSystem
  Enum containing variants representing numeral systems.
• Setting
  Enum containing settings for the conversion process.

Traits

• Numeral
  Trait for converting numbers across different numeral systems.

Functions

• convert_num
  Converts a number from one numeral system to another.

Type Aliases

• Settings
  Type alias for a vector of Setting values.