| Crates.io | parse-frequency |
| lib.rs | parse-frequency |
| version | 2.0.0 |
| created_at | 2025-04-19 16:48:19.620728+00 |
| updated_at | 2025-04-20 23:09:47.372422+00 |
| description | A simple library to parse frequency strings into a frequency in Hz. |
| homepage | https://github.com/Daxanius/parse-frequency |
| repository | https://github.com/Daxanius/parse-frequency |
| max_upload_size | |
| id | 1640795 |
| size | 45,932 |
A simple, no-nonsense Rust library for parsing frequency strings like "1.5GHz" or "100 kHz" into strongly-typed frequency values. Case insensitive, of course.
Supports serialization, deserialization, CLI parsing, and conversions between Hz, kHz, MHz, and GHz.
"1GHz", "2.5 MHz", or "42 kHz" into a Frequency typeDisplay implementation (e.g., "2.50 MHz")std::time::Duration (period)#[derive(Debug, Copy, Clone, ...)] with strong type guaranteesSend + Sync support for thread-safe usage in multithreaded environmentsuse parse_frequency::Frequency;
fn main() {
let cpu_clock = "3.6 GHz".parse::<Frequency>().unwrap();
println!("CPU clock: {}", cpu_clock);
let ns_per_cycle = cpu_clock.as_duration();
println!("One clock cycle takes: {} ns", ns_per_cycle.as_nanos());
}
Add this to your Cargo.toml:
[dependencies]
parse-frequency = "2.0"
Enable optional features:
[dependencies.parse-frequency]
version = "1.0"
features = ["serde", "clap", "num-traits", "schemars", "time", "chrono"]
use parse_frequency::Frequency;
let freq: Frequency = "2.5GHz".parse().unwrap();
assert_eq!(freq.as_hz(), 2_500_000_000);
use parse_frequency::{Frequency, KILOHERTZ};
let f = Frequency::from_khz(2000);
assert_eq!(f.as_mhz(), 2);
assert_eq!(f.as_hz(), 2 * KILOHERTZ * 1000);
Note that due to the 2 digit precision limitation, the result is rounded when displaying.
let f = Frequency::from_mhz(1337);
println!("{f}"); // -> "1.34 GHz"
Durationlet f = Frequency::from_ghz(1);
let duration = f.as_duration();
assert_eq!(duration.as_nanos(), 1); // 1 GHz → 1 nanosecond period
parse-frequency a number of optional features that enable seamless integration with commonly used Rust libraries. Enable these via Cargo features.
Enable the serde feature to serialize and deserialize Frequency as human-readable strings:
parse-frequency = { version = "...", features = ["serde"] }
use parse_frequency::Frequency;
use serde::{Serialize, Deserialize};
#[derive(Serialize, Deserialize)]
struct Config {
clock: Frequency,
}
This allows values like:
{
"clock": "1.00 GHz"
}
Enable the clap feature to use Frequency in CLI arguments:
parse-frequency = { version = "...", features = ["clap"] }
use clap::Parser;
use parse_frequency::Frequency;
#[derive(Parser)]
struct Args {
/// Target frequency (e.g. "2.4GHz")
#[arg(short, long)]
frequency: Frequency,
}
Enable num-traits to use Frequency in generic numeric code (e.g. scientific, DSP, or math contexts):
parse-frequency = { version = "...", features = ["num-traits"] }
Implements:
Zero, OneNum, FromStrRadixMul, Div, RemNote: Arithmetic is defined in terms of absolute frequency values. Multiplying or dividing two
Frequencyvalues may not make semantic sense but is supported for compatibility.
Enable the chrono feature to convert a Frequency into a time period:
parse-frequency = { version = "...", features = ["chrono"] }
use parse_frequency::Frequency;
let freq = Frequency::from_ghz(1);
let period = freq.as_chrono_duration(); // chrono::Duration of 1 ns
Handles both low and high frequencies safely using nanosecond/picosecond precision.
Enable the time feature to convert a Frequency into a time::Duration:
parse-frequency = { version = "...", features = ["time"] }
use parse_frequency::Frequency;
let freq = Frequency::from_mhz(1);
let duration = freq.as_time_duration(); // time::Duration of 1000 ns
Enable the schemars feature to use Frequency with OpenAPI / JSON schema generation:
parse-frequency = { version = "...", features = ["schemars"] }
use parse_frequency::Frequency;
use schemars::JsonSchema;
#[derive(JsonSchema)]
struct Config {
clock: Frequency,
}
Generates schema like:
{
"type": "string",
"format": "frequency",
"description": "A frequency value like \"2.4 GHz\", \"100 kHz\", or \"440Hz\""
}
For convenience, the following constants are available:
use parse_frequency::{KILOHERTZ, MEGAHERTZ, GIGAHERTZ};
assert_eq!(KILOHERTZ, 1_000);
assert_eq!(MEGAHERTZ, 1_000_000);
assert_eq!(GIGAHERTZ, 1_000_000_000);
The Frequency::from_str and parse_frequency functions return a custom error enum:
match "bad input".parse::<Frequency>() {
Ok(freq) => println!("Parsed: {freq}"),
Err(e) => eprintln!("Failed: {e}"),
}
Example error variants:
Error::UnknownUnit("abc")Error::InvalidValue("GHz")