#duration #time #time-formatting #arithmetic-operations #format-time #api

bin+lib time_duration_api

This crate provides a time and duration manipulation API for Rust projects

10 releases

0.1.9 Dec 30, 2024
0.1.8 Dec 30, 2024
0.1.6 May 25, 2024
0.1.5 Apr 14, 2024
0.1.4 Feb 29, 2024

#99 in Date and time

Download history 2/week @ 2024-09-25 3/week @ 2024-10-02 1/week @ 2024-12-04 3/week @ 2024-12-11 265/week @ 2024-12-25 39/week @ 2025-01-01

308 downloads per month

MIT license

31KB
338 lines

time_duration_api

crates.io docs.rs License: MIT

This crate provides a time and duration manipulation API for Rust projects. It aims to simplify common time-related tasks by offering a set of easy-to-use structs and methods.

Overview

The time_duration_api crate provides utilities to handle time and duration operations in Rust. It includes two key structures:

  • Time: A struct for working with time, offering methods for getting the current time, formatting, manipulating time, and converting between timezones.
  • CustomDuration: A struct for representing durations in a human-readable format, with support for arithmetic operations like addition, subtraction, multiplication, and division.

Features

1. Time Struct

The Time struct represents a specific point in time. It provides the following functionalities:

  • Get the current time.
  • Format the time into a string using custom formats.
  • Add or subtract durations.
  • Convert to different timezones.
  • Convert from string.

Methods

  • now(): Returns the current time.
  • format(format: &str): Formats the time using the provided format string.
  • timestamp(): Returns the time as a Unix timestamp (seconds since Jan 1, 1970).
  • add_duration(duration: &CustomDuration): Adds the specified duration to the current time.
  • sub_duration(duration: &CustomDuration): Subtracts the specified duration from the current time.
  • to_timezone(tz: &str): Converts the time to the specified timezone.
  • from_str(time_str: &str, format: &str): Parses a string into a Time object using the provided format.

Example Usage

use time_duration_api::time_utils::{CustomDuration, Time};

fn main() {
    let mut now = Time::now();
    println!("Current Time: {}", now);
    
    // Format time
    println!(
        "Formatted Time: {}",
        now.format("%Y-%m-%d %H:%M:%S").unwrap()
    );

    // Get Unix timestamp
    println!("Timestamp: {}", now.timestamp().unwrap());

    // Add 1 hour to current time
    let future_time = now.add_duration(&CustomDuration::from_secs(3600));
    println!(
        "Time after 1 hour: {}",
        future_time.format("%Y-%m-%d %H:%M:%S").unwrap()
    );

    // Subtract 1 hour from current time
    let past_time = now.sub_duration(&CustomDuration::from_secs(3600));
    println!(
        "Time before 1 hour: {}",
        past_time.format("%Y-%m-%d %H:%M:%S").unwrap()
    );

    // Convert to a different timezone
    let ist_time = now.to_timezone("+05:30").unwrap();
    println!("Time in IST: {}", ist_time);

    // Parse time from string
    let time_from_str = Time::from_str("2023-10-27 12:00:00+05:30", "%Y-%m-%d %H:%M:%S%z").unwrap();
    println!("Time from string: {}", time_from_str);
}

2. CustomDuration Struct

The CustomDuration struct allows you to represent durations and perform arithmetic operations. It can be initialized using seconds or parsed from a human-readable format (e.g., "1h 30m").

Methods

  • from_secs(secs: u64): Creates a CustomDuration from the specified number of seconds.
  • format_human_readable(): Returns the duration in a human-readable format (e.g., "1 hour 1 minute").
  • from_str(duration_str: &str): Parses a human-readable duration string into a CustomDuration.
  • Arithmetic operations:
    • + : Adds durations.
    • - : Subtracts durations.
    • * : Multiplies the duration by a scalar.
    • / : Divides the duration by a scalar.

Example Usage

use time_duration_api::time_utils::{CustomDuration, Time};

fn main() {
    // Create a duration of 3661 seconds (1 hour, 1 minute)
    let duration = CustomDuration::from_secs(3661);
    println!("Duration: {}", duration);
    println!(
        "Human-readable Duration: {}",
        duration.format_human_readable()
    );

    // Parse duration from string
    let duration_from_str = CustomDuration::from_str("1h 30m").unwrap();
    println!(
        "Duration from str: {}",
        duration_from_str.format_human_readable()
    );

    // Arithmetic operations on durations
    let duration_add = duration + CustomDuration::from_secs(60);
    println!("Duration add: {}", duration_add.format_human_readable());

    let duration_sub = duration - CustomDuration::from_secs(60);
    println!("Duration sub: {}", duration_sub.format_human_readable());

    let duration_mul = duration * 2;
    println!("Duration mul: {}", duration_mul.format_human_readable());

    let duration_div = duration / 2;
    println!("Duration div: {}", duration_div.format_human_readable());

    // Duration in seconds
    println!("Duration in seconds: {}", duration.as_secs());
}

How to Use

To use the time_duration_api crate in your Rust project, add it as a dependency in your Cargo.toml:

[dependencies]
time_duration_api = "0.1.9"
chrono = "0.4"
humantime = "2.1"
serde = { version = "1.0", features = ["derive"] }

Example: Using time_duration_api in main.rs

Your main.rs file should include the following imports:

use time_duration_api::time_utils::{CustomDuration, Time};

After that, you can use the provided methods and structs as shown in the examples above.


Error Handling

The crate uses a custom TimeError enum for error reporting:

#[derive(Debug, Clone)]
pub enum TimeError {
    InvalidTime,
    InvalidTimeFormat(String),
    InvalidTimezoneFormat(String),
    ParseError(String),
}
  • You should use the custom Result type alias to handle these errors gracefully.
pub type Result<T> = std::result::Result<T, TimeError>;

Example:

use time_duration_api::time_utils::Time;

fn main() {
    let time = Time::from_str("invalid_time", "%Y-%m-%d %H:%M:%S");
    match time {
        Ok(t) => println!("Parsed time: {}", t),
        Err(e) => println!("Error: {}", e),
    }
}

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Dependencies

~1.3–2.1MB
~40K SLoC