fmt: add new serde sub-module for integer timestamp integration

This adds a new `jiff::fmt::serde` sub-module that contains helper
sub-modules that work with Serde's `with` attribute. For example:

```rust
use jiff::Timestamp;

struct Record {
    #[serde(with = "jiff::fmt::serde::timestamp::second::required")]
    timestamp: Timestamp,
}

let json = r#"{"timestamp":1517644800}"#;
let got: Record = serde_json::from_str(&json)?;
assert_eq!(got.timestamp, Timestamp::from_second(1517644800)?);
assert_eq!(serde_json::to_string(&got)?, json);
```

This is inspired in part by how Chrono supports a similar use case.
It is expected that the behavior should be the same, although this
implementation does support the full gamut of integer types (including
a 128-bit integer number of nanoseconds). Moreover, the naming is
different. Chrono uses a flatter namespace, where as here, we bury
everything into sub-modules. The idea is to leave some room for future
expansion, although I'm not sure there is much else to add. I also feel
like spelling out `timestamp` instead of `ts` is a bit clearer.

The module paths are quite long, e.g.,
`jiff::fmt::serde::timestamp::second::required` and
`jiff::fmt::serde::timestamp::second::optional`. But they are
predictable. And to mitigate users needing to click around through a
deep module tree, we include the full tree in the `jiff::fmt::serde`
module documentation.

Ref #100, Closes #101

.github/workflows/ci.yml

@@ -57,7 +57,7 @@ jobs:
       with:
         toolchain: ${{ matrix.rust }}
     - run: cargo build --verbose
-    - run: cargo doc --verbose
+    - run: cargo doc --features serde --verbose
     - run: cargo test --verbose --all
     - run: cargo test --verbose -p jiff-cli
     # Skip on Windows because it takes freaking forever.
@@ -82,7 +82,7 @@ jobs:
       with:
         toolchain: stable-x86_64-gnu
     - run: cargo build --verbose
-    - run: cargo doc --verbose
+    - run: cargo doc --features serde --verbose
     - run: cargo test --verbose --lib
     - run: cargo test --verbose --test integration
 
@@ -109,7 +109,7 @@ jobs:
     - name: Build jiff-tzdb-platform
       run: cargo build -p jiff-tzdb-platform --verbose
     - name: Build docs
-      run: cargo doc --verbose
+      run: cargo doc --features serde --verbose
     - name: Run library tests
       run: cargo test --lib
     - name: Run integration tests

CHANGELOG.md

@@ -9,6 +9,8 @@ Add `BrokenDownTime::set_{offset,iana_time_zone}` APIs.
 * [#93](https://github.com/BurntSushi/jiff/issues/93):
 Add note about using `Timestamp::now().to_zoned()` instead of
 `Zoned::now().with_time_zone()`.
+* [#101](https://github.com/BurntSushi/jiff/issues/101):
+Add new `jiff::fmt::serde` module for integration with integer timestamps.
 * [#117](https://github.com/BurntSushi/jiff/pull/117):
 Remove `unsafe` usage in `libm` functions (applicable only to no-std users).
 

Cargo.toml

@@ -101,7 +101,7 @@ anyhow = "1.0.81"
 chrono = { version = "0.4.38", features = ["serde"] }
 chrono-tz = "0.9.0"
 insta = "1.39.0"
-# We force `serde` to be enable in dev mode so that the docs render and test
+# We force `serde` to be enabled in dev mode so that the docs render and test
 # correctly. This is highly suspicious.
 jiff = { path = "./", features = ["serde"] }
 quickcheck = { version = "1.0.3", default-features = false }

src/fmt/mod.rs

@@ -19,6 +19,8 @@ use self::util::{Decimal, DecimalFormatter, Fractional, FractionalFormatter};
 mod offset;
 pub mod rfc2822;
 mod rfc9557;
+#[cfg(feature = "serde")]
+pub mod serde;
 pub mod strtime;
 pub mod temporal;
 mod util;