8 releases
0.0.9 | Dec 31, 2024 |
---|---|
0.0.8 | Sep 2, 2024 |
0.0.6 | May 6, 2024 |
0.0.5 | Dec 5, 2023 |
0.0.2 | Feb 10, 2023 |
#29 in Date and time
3,741 downloads per month
Used in 22 crates
(16 directly)
110KB
1.5K
SLoC
DateTime
(DTT)
A Rust library for parsing, validating, manipulating, and formatting dates and times.
• Website • Documentation • Report Bug • Request Feature • Contributing Guidelines
Overview
The DateTime
(DTT) library is a comprehensive, flexible toolkit for managing dates and times in Rust. It includes functions, macros, and data structures that enable you to create, parse, validate, and format date-time objects with minimal effort.
You can construct DateTime
objects in UTC or in a fixed offset timezone, ensuring accurate date and time information for varied use cases. The library also offers validation methods, which help maintain precision and correctness in time-critical operations.
Features
The DateTime
(DTT) library provides:
-
Core Fields
datetime
: InternalPrimitiveDateTime
(UTC by default)offset
: AUtcOffset
representing the timezone offset from UTC
-
Core Methods
new()
: Create aDateTime
with the current UTC timenew_with_tz(tz: &str)
: Construct aDateTime
in a specified timezonenew_with_custom_offset(hours: i8, minutes: i8)
: Create aDateTime
with a custom offsetfrom_components(...)
: Build aDateTime
from year, month, day, hour, minute, second, and offsetupdate(&self)
: Refresh theDateTime
to the current instant (preserving offset)now()
: Return the currentDateTime
(an alias fornew()
)from_str(...)
: Parse aDateTime
from a string (implementsFromStr
)default()
: Provide the current UTC time by default
-
Parsing and Formatting
parse(...)
: Parse a date-time string into aDateTime
parse_custom_format(...)
: Use a custom format pattern for parsingformat(...)
: Format aDateTime
with a user-defined patternformat_rfc3339(&self)
: Output RFC 3339 textformat_iso8601(&self)
: Output ISO 8601 text
-
Date-Time Manipulation
convert_to_tz(...)
: Switch to a different timezoneunix_timestamp(&self)
: Retrieve the Unix timestampadd_days(...)
,add_months(...)
,add_years(...)
: Advance the date by days, months, or yearssub_months(...)
,sub_years(...)
: Move the date backwards by months or yearsnext_day()
,previous_day()
: Obtain the following or preceding daystart_of_week()
,end_of_week()
: Jump to the beginning or end of the weekstart_of_month()
,end_of_month()
: Jump to the beginning or end of the monthstart_of_year()
,end_of_year()
: Jump to the beginning or end of the yearis_within_range(&self, start: &Self, end: &Self)
: Check if a date-time is in a specific rangeduration_since(&self, other: &Self)
: Calculate duration between twoDateTime
s
-
Getters
year(...)
,month(...)
,day(...)
,hour(...)
,minute(...)
,second(...)
,microsecond(...)
weekday(...)
,ordinal(...)
,iso_week(...)
,offset(...)
-
Setters
set_date(...)
: Update the year, month, and dayset_time(...)
: Update the hour, minute, and second
-
Validation
is_valid_day(...)
,is_valid_hour(...)
,is_valid_minute(...)
,is_valid_second(...)
is_valid_month(...)
,is_valid_year(...)
,is_valid_microsecond(...)
is_valid_ordinal(...)
,is_valid_iso_week(...)
,is_valid_time(...)
is_valid_iso_8601(date: &str)
: Check if an input is valid ISO 8601
-
Utility Functions
format_time_in_timezone(...)
: Format a date-time for a specified timezone
-
Arithmetic Operations
Add<Duration>
andSub<Duration>
traits for adding or subtracting durations
-
Comparison Operations
PartialOrd
andOrd
for ordering comparisons
-
Hashing
Hash
implementation for use with hash-based collections
-
Macros
- Examples include
dtt_now!()
,dtt_parse!()
,dtt_add_days!()
, and many more, simplifying routine tasks like date parsing or arithmetic
- Examples include
-
Helper Functions
days_in_month(year, month)
: Returns the number of days in a specific month and yearis_leap_year(year)
: Checks if a year is a leap year
-
Error Handling
DateTimeError
: Comprehensive error handling for invalid dates, times, or offsets
-
Timezone Support
- Create or convert
DateTime
objects across multiple named timezones or custom offsets
- Create or convert
-
Serialisation and Deserialisation
serde
-enabled for easy reading and writing ofDateTime
objects
Installation
Add this to your Cargo.toml
:
[dependencies]
dtt = "0.0.9"
Then in your main.rs
or lib crate:
extern crate dtt;
use dtt::*;
Usage
Below are some quick examples showing how to use the core features of the DateTime (DTT)
library.
Basic Usage
use dtt::datetime::DateTime;
use dtt::dtt_print;
// Create a new DateTime in UTC
let now = DateTime::new();
dtt_print!(now);
// Create a DateTime in a specified timezone
let ny_time = DateTime::new_with_tz("EST").expect("Valid timezone");
println!("Current time in New York: {}", ny_time);
// Parse a date-time string
let date = DateTime::parse("2023-05-20T15:30:00Z").expect("Valid date and time");
println!("Parsed date: {}", date);
// Add days to a date-time
let future_date = date.add_days(7).expect("Should be valid");
println!("Date after 7 days: {}", future_date);
Macro Usage
The library includes macros that streamline common operations:
use dtt::{dtt_now, dtt_parse, dtt_add_days};
let now = dtt_now!();
let parsed_date = dtt_parse!("2023-05-20T15:30:00Z").expect("Valid date");
let future_date = dtt_add_days!(parsed_date, 7).expect("Should be valid");
Error Handling
The DateTimeError
enum is used to handle invalid or out-of-range dates and times:
use dtt::datetime::DateTime;
use dtt::error::DateTimeError;
fn example_with_error_handling() -> Result<(), DateTimeError> {
let date = DateTime::parse("2023-05-20T15:30:00Z")?;
println!("Parsed date: {}", date);
// Attempt to parse an invalid date string
let result = DateTime::parse("2023-13-20T15:30:00Z");
match result {
Ok(_) => println!("Unexpected success."),
Err(e) => println!("Failed to parse date-time: {}", e),
}
Ok(())
}
Documentation
Comprehensive API documentation is available at:
Rust Version Compatibility
Requires rustc 1.56.0 or above.
Contributing
All contributions are appreciated! Please follow our contributing instructions for details on reporting issues, requesting features, or submitting pull requests. Contributions are subject to Rust's Code of Conduct.
By submitting any contribution, you agree to license your contribution under the same dual licence chosen by this project.
License
Licensed under either of these:
You may select either licence as needed.
Credits and Acknowledgements
Many thanks to all the contributors of the DateTime (DTT) Library. We also extend our gratitude to the Rust Reddit community for their helpful suggestions and feedback.
Dependencies
~3.5–5.5MB
~101K SLoC