Add some docs

This commit is contained in:
Nathan Fisher 2024-02-09 00:24:04 -05:00
parent e2910695d2
commit 559cfa3cb3
2 changed files with 27 additions and 0 deletions

19
README.md Normal file
View File

@ -0,0 +1,19 @@
Contents
========
- [Summary](#summary)
- [Usage](#usage)
## Summary
Epoch is a small library for converting Unix timestamps to human readable datetime
and vice versa. It includes functionality for displaying a DateTime as a human
readable string, parsing from string, and comparison for equality or ordering.
This crate is ideal when you want a lighter and simpler date/time library than the
excellent and very complete [chrono](https://crates.io/crates/chrono), which is
likely overkill for many use cases.
## Usage
Add epoch to your Cargo.toml
```Toml
epoch = { git = "http://git.hitchhiker-linux.org/jeang3nie/epoch-rs.git" }
```

View File

@ -62,6 +62,7 @@ impl DateTime {
seconds seconds
} }
#[allow(clippy::missing_panics_doc)]
/// Converts a Unix timestamp to a `DateTime` struct /// Converts a Unix timestamp to a `DateTime` struct
pub fn from_timestamp(ts: i64) -> Self { pub fn from_timestamp(ts: i64) -> Self {
if ts < 0 { if ts < 0 {
@ -149,14 +150,21 @@ impl DateTime {
} }
} }
#[allow(clippy::missing_panics_doc)]
/// Gets the day of the week for this `DateTime`
pub fn weekday(&self) -> Weekday { pub fn weekday(&self) -> Weekday {
let ts = self.timestamp_naive(); let ts = self.timestamp_naive();
let mut days = ts / SECONDS_PER_DAY; let mut days = ts / SECONDS_PER_DAY;
// For negative timestamps this number is actually the following day
if ts < 0 { days -= 1 } if ts < 0 { days -= 1 }
// Rusts `%` operator is modulo, not modulus. We have to use the
// operation which will gove the correct answer for either positive
// or negative remainders
let rem = days.rem_euclid(7); let rem = days.rem_euclid(7);
rem.try_into().unwrap() rem.try_into().unwrap()
} }
/// Returns a string representing this date and time in human readable format
pub fn display(&self) -> String { pub fn display(&self) -> String {
format!( format!(
"{} {} {} {:0>2}:{:0>2}:{:0>2} {} {}", "{} {} {} {:0>2}:{:0>2}:{:0>2} {} {}",