7 releases
0.0.8 | Sep 2, 2024 |
---|---|
0.0.7 |
|
0.0.6 | May 6, 2024 |
0.0.5 | Dec 5, 2023 |
0.0.2 | Feb 10, 2023 |
#35 in Date and time
2,909 downloads per month
Used in 22 crates
(16 directly)
105KB
916 lines
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 and flexible tool that enables developers to manage dates and times with ease. It offers a wide range of functions, macros, and data structures for performing date and time operations, such as creating, parsing, validating, and formatting date-time objects.
The library supports the creation of new DateTime
objects with either UTC or custom timezone specifications, providing accurate and relevant date and time information. Additionally, it offers mechanisms for validating input dates and times, ensuring reliable and precise operations.
Features
The DateTime (DTT)
library offers the following features:
-
Core Fields:
datetime
: The date and time in UTC (PrimitiveDateTime
).offset
: The timezone offset in UTC (UtcOffset
).
-
Core Methods:
new()
: Creates a newDateTime
instance with the current UTC time.new_with_tz(tz: &str)
: Creates a newDateTime
object with the specified timezone.new_with_custom_offset(hours: i8, minutes: i8)
: Creates aDateTime
object with a custom UTC offset.from_components(year: i32, month: u8, day: u8, hour: u8, minute: u8, second: u8, offset: UtcOffset)
: Creates aDateTime
object from individual date and time components.update(&self)
: Updates theDateTime
object to the current date and time.now()
: Returns the currentDateTime
.from_str(s: &str)
: Parses a string into aDateTime
instance (implementation ofFromStr
trait).default()
: Returns the current UTC time as the default value forDateTime
.
-
Parsing and Formatting:
parse(input: &str)
: Parses a date-time string into aDateTime
object.parse_custom_format(input: &str, format: &str)
: Parses a date-time string using a custom format.format(&self, format_str: &str)
: Formats theDateTime
object as a string using the specified format.format_rfc3339(&self)
: Formats theDateTime
as an RFC 3339 string.format_iso8601(&self)
: Formats theDateTime
as an ISO 8601 string.
-
Date-Time Manipulation:
convert_to_tz(&self, new_tz: &str)
: Converts theDateTime
object to a different timezone.unix_timestamp(&self)
: Returns the Unix timestamp of theDateTime
object.add_days(&self, days: i64)
: Adds a specified number of days to theDateTime
.add_months(&self, months: i32)
: Adds a specified number of months to theDateTime
.add_years(&self, years: i32)
: Adds a specified number of years to theDateTime
.sub_months(&self, months: i32)
: Subtracts a specified number of months from theDateTime
.sub_years(&self, years: i32)
: Subtracts a specified number of years from theDateTime
.next_day(&self)
: Returns a newDateTime
instance representing the next day.previous_day(&self)
: Returns a newDateTime
instance representing the previous day.start_of_week(&self)
: Returns a newDateTime
instance at the start of the week.end_of_week(&self)
: Returns a newDateTime
instance at the end of the week.start_of_month(&self)
: Returns a newDateTime
instance at the start of the month.end_of_month(&self)
: Returns a newDateTime
instance at the end of the month.start_of_year(&self)
: Returns a newDateTime
instance at the start of the year.end_of_year(&self)
: Returns a newDateTime
instance at the end of the year.is_within_range(&self, start: &Self, end: &Self)
: Checks if theDateTime
falls within a specific range.duration_since(&self, other: &Self)
: Calculates the duration between twoDateTime
instances.
-
Getters:
year(&self)
: Returns the year.month(&self)
: Returns the month.day(&self)
: Returns the day of the month.hour(&self)
: Returns the hour.minute(&self)
: Returns the minute.second(&self)
: Returns the second.microsecond(&self)
: Returns the microsecond.weekday(&self)
: Returns the weekday.ordinal(&self)
: Returns the day of the year (ordinal).iso_week(&self)
: Returns the ISO week number.offset(&self)
: Returns the UTC offset.
-
Setters:
set_date(&self, year: i32, month: u8, day: u8)
: Sets a new date for theDateTime
instance.set_time(&self, hour: u8, minute: u8, second: u8)
: Sets a new time for theDateTime
instance.
-
Validation:
is_valid_day(day: &str)
: Checks if the input represents a valid day of the month.is_valid_hour(hour: &str)
: Checks if the input represents a valid hour of the day.is_valid_minute(minute: &str)
: Checks if the input represents a valid minute of the hour.is_valid_second(second: &str)
: Checks if the input represents a valid second of the minute.is_valid_month(month: &str)
: Checks if the input represents a valid month of the year.is_valid_year(year: &str)
: Checks if the input represents a valid year.is_valid_microsecond(microsecond: &str)
: Checks if the input represents a valid microsecond.is_valid_ordinal(ordinal: &str)
: Checks if the input represents a valid ordinal day of the year.is_valid_iso_week(week: &str)
: Checks if the input represents a valid ISO week number.is_valid_time(time: &str)
: Checks if the input represents a valid time inHH:MM:SS
format.is_valid_iso_8601(date: &str)
: Checks if the input represents a valid ISO 8601 formatted date.
-
Utility Functions:
format_time_in_timezone(tz: &str, format: &str)
: Formats the current time for a specific timezone.
-
Arithmetic Operations:
Add<Duration>
: Adds aDuration
to theDateTime
instance.Sub<Duration>
: Subtracts aDuration
from theDateTime
instance.
-
Comparison Operations:
PartialOrd
: Allows partial ordering comparisons betweenDateTime
instances.Ord
: Allows total ordering comparisons betweenDateTime
instances.
-
Hashing:
Hash
: AllowsDateTime
instances to be used as keys in hash-based collections.
-
Macros:
dtt_now!()
: Generates the current date and time.dtt_parse!(input)
: Parses a date-time string into aDateTime
object.dtt_print!(datetime)
: Prints aDateTime
object.dtt_vec![]
: Creates a vector.dtt_map!{}
: Creates a map.dtt_assert!
: Asserts conditions during testing.is_valid!
: Checks the validity of various date-time components.dtt_is_valid_function!(func_name)
: Defines a custom validation function.dtt_new_with_tz!(tz)
: Creates a newDateTime
object with a specified timezone.dtt_add_days!(datetime, days)
: Adds days to aDateTime
object.dtt_sub_days!(datetime, days)
: Subtracts days from aDateTime
object.dtt_diff_seconds!(datetime1, datetime2)
: Calculates the difference in seconds between twoDateTime
objects.dtt_diff_days!(datetime1, datetime2)
: Calculates the difference in days between twoDateTime
objects.dtt_clone!
: Creates a deep copy of aDateTime
object.dtt_format!
: Formats aDateTime
object using a provided format string.dtt_create_vec!
: Creates a new vector containing provided elements.dtt_min!
: Returns the minimum of given values.dtt_max!
: Returns the maximum of given values.dtt_join!
: Joins a vector of strings into a single string.dtt_print_vec!
: Prints a vector of elements to the console.
-
Helper Functions:
days_in_month(year: i32, month: u8)
: Determines the number of days in a given month and year.is_leap_year(year: i32)
: Determines if a year is a leap year.
-
Error Handling: The library provides comprehensive error handling through the
DateTimeError
enum, allowing for robust error management in date and time operations. -
Timezone Support: DateTime (DTT) offers extensive timezone support, allowing for creation and manipulation of date-time objects across different timezones.
-
Serialization and Deserialization: The library supports serialization and deserialization of
DateTime
objects usingserde
, facilitating easy integration with various data formats.
Installation
Add this to your Cargo.toml
:
[dependencies]
dtt = "0.0.8"
Add the following to your main.rs
file:
extern crate dtt;
use dtt::*;
Usage
Here are some examples of how to use the DateTime (DTT)
library in your Rust projects.
Basic Usage
use dtt::datetime::DateTime;
use dtt::dtt_print;
fn main() {
// Create a new DateTime object with the current UTC time
let now = DateTime::new();
dtt_print!(now);
// Create a DateTime object with a specific timezone
let ny_time = DateTime::new_with_tz("EST").expect("Valid timezone");
println!("Current time in New York: {}", ny_time);
// Parse a date string
let date = DateTime::parse("2023-05-20T15:30:00Z").expect("Valid date string");
println!("Parsed date: {}", date);
// Add days to a date
let future_date = date.add_days(7).expect("Valid date");
println!("Date after 7 days: {}", future_date);
}
Macro Usage
The DateTime (DTT) library provides a rich set of macros to simplify common operations:
use dtt::{dtt_now, dtt_parse, dtt_add_days, dtt_diff_days};
fn main() {
let now = dtt_now!();
println!("Current time: {}", now);
let parsed_date = dtt_parse!("2023-05-20T15:30:00Z").expect("Valid date string");
println!("Parsed date: {}", parsed_date);
let future_date = dtt_add_days!(parsed_date, 7).expect("Valid date");
println!("Date after 7 days: {}", future_date);
let days_diff = dtt_diff_days!(now, future_date);
println!("Days difference: {}", days_diff);
}
Error Handling
The library uses a custom DateTimeError
type for error handling:
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);
let invalid_date = DateTime::parse("2023-13-20T15:30:00Z");
match invalid_date {
Ok(_) => println!("This shouldn't happen"),
Err(e) => println!("Error parsing invalid date: {}", e),
}
Ok(())
}
Documentation
For full API documentation, please visit https://doc.dttlib.com/ or https://docs.rs/dtt.
Rust Version Compatibility
Compiler support: requires rustc 1.56.0+
Contributing
Contributions are welcome! Please see the contributing instructions for more information.
Contributions in any form (issues, pull requests, etc.) to this project must adhere to Rust's Code of Conduct.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
License
Licensed under either of the Apache License or the MIT license at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
Credits and Acknowledgements
A big thank you to all the awesome contributors of the DateTime (DTT) Library for their help and support.
A special thank you goes to the Rust Reddit community for providing a lot of useful suggestions on how to improve this project.
Dependencies
~3.5–5.5MB
~102K SLoC