jiff-icu: add crate for converting to-and-from icu_calendar

This adds a new crate, `jiff-icu`, with `ConvertFrom` and `ConvertInto`
traits. These mirror the `TryFrom` and `TryInto` traits from `std`. I
took this approach for conversions specifically because it avoids
needing to define wrapper types for everything. It does means we can't
use the standard traits, but I think just importing one trait and having
that add conversion routines on to the types in `jiff` and
`icu_calendar` is an overall lighter weight solution.

One thing I'm slightly unsure about is whether I want `jiff-icu` to just
encompass _everything_ that makes sense to convert between inside of
`icu`, or whether it should actually be `jiff-icu-calendar`. And then
maybe down the road add `jiff-icu-timezone` or something? I'm partial to
just adding everything in `icu` to `jiff-icu` that makes sense to add,
and perhaps exposing some features (that are turned on by default) to
opt out of `icu` crates that you don't need.

I also think this will set the template for other crates I'd like to
add, like `jiff-chrono`. With that said, I think `jiff-icu` is of
particular importance, because it will enable an easier on-ramp to
locale and non-Gregorian support. That is, presumably, `jiff-chrono` and
`jiff-time` (if I do those) will be things that you wouldn't _ideally_
use, but `jiff-icu` will likely be part of intended and recommended
workflows for users.

Ref #50

Author: BurntSushi

.github/workflows/ci.yml

@@ -59,7 +59,6 @@ jobs:
     - run: cargo build --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.
     - if: matrix.build != 'win-msvc'
       run: cargo test --verbose --lib --profile testrelease
@@ -110,8 +109,14 @@ jobs:
       run: cargo build -p jiff-tzdb-platform --verbose
     - name: Build docs
       run: cargo doc --features serde --verbose
-    # We don't really care much about adding dev dependencies, and they can
-    # move quite a bit faster. So unfortunately don't run tests on MSRV. We
+    # NOTE: We currently don't track some ecosystem integration crates
+    # like `jiff-icu`. They don't support Jiff's MSRV at time of writing
+    # (2025-02-02), and I think these sorts of integration crates are at very
+    # low risk of being more aggressive with respect to MSRV than the crates
+    # they depend on. So for now, we just don't test them here.
+    #
+    # NOTE: We don't really care much about adding dev dependencies, and they
+    # can move quite a bit faster. So unfortunately don't run tests on MSRV. We
     # could fix this by adding a `Carg.msrv.lock` or some such, but it doesn't
     # seem worth it.
     # - name: Run library tests

Cargo.toml

@@ -31,6 +31,7 @@ include = [
 [workspace]
 members = [
   "crates/jiff-cli",
+  "crates/jiff-icu",
   "crates/jiff-tzdb",
   "crates/jiff-tzdb-platform",
   "examples/*",

crates/jiff-icu/COPYING

@@ -0,0 +1,3 @@
+This project is dual-licensed under the Unlicense and MIT licenses.
+
+You may use this code under the terms of either license.

crates/jiff-icu/Cargo.toml

@@ -0,0 +1,33 @@
+[package]
+name = "jiff-icu"
+version = "0.0.1"  #:version
+authors = ["Andrew Gallant <[email protected]>"]
+license = "Unlicense OR MIT"
+homepage = "https://github.com/BurntSushi/jiff/tree/master/crates/jiff-icu"
+repository = "https://github.com/BurntSushi/jiff"
+documentation = "https://docs.rs/jiff-icu"
+description = "The entire Time Zone Database embedded into your binary."
+categories = ["date-and-time"]
+keywords = ["date", "time", "temporal", "zone", "iana"]
+workspace = "../.."
+edition = "2021"
+rust-version = "1.70"
+include = ["/*.rs", "/*.dat", "COPYING", "LICENSE-MIT", "UNLICENSE"]
+
+[lib]
+name = "jiff_icu"
+bench = false
+path = "src/lib.rs"
+
+[features]
+default = ["std"]
+std = ["alloc", "icu_calendar/std", "jiff/std"]
+alloc = ["jiff/alloc"]
+
+[dependencies]
+jiff = { path = "../..", default-features = false }
+icu_calendar = { version = "1.5.2", default-features = false }
+
+[dev-dependencies]
+jiff = { path = "../..", default-features = true }
+icu = { version = "1.5.0", features = ["std"] }

crates/jiff-icu/LICENSE-MIT

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Andrew Gallant
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

crates/jiff-icu/README.md

@@ -0,0 +1,7 @@
+jiff-icu
+========
+WIP
+
+### Documentation
+
+https://docs.rs/jiff-icu

crates/jiff-icu/UNLICENSE

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <http://unlicense.org/>

crates/jiff-icu/src/error.rs

@@ -0,0 +1,99 @@
+/// Creates a new ad hoc error via `format_args!`.
+macro_rules! err {
+    ($($tt:tt)*) => {{
+        crate::error::Error::adhoc_from_args(format_args!($($tt)*))
+    }}
+}
+
+pub(crate) use err;
+
+/// An error that can occur when converting between types in this crate.
+#[derive(Clone, Debug)]
+pub struct Error {
+    kind: ErrorKind,
+}
+
+impl Error {
+    /// Creates an error from an arbitrary `core::fmt::Arguments`.
+    ///
+    /// When `alloc` isn't enabled, then `Arguments::as_str()` is used to
+    /// find an error message. Otherwise, a generic error message is emitted.
+    pub(crate) fn adhoc_from_args<'a>(
+        message: core::fmt::Arguments<'a>,
+    ) -> Error {
+        let kind = ErrorKind::Adhoc(AdhocError::from_args(message));
+        Error { kind }
+    }
+}
+
+#[derive(Clone, Debug)]
+enum ErrorKind {
+    Adhoc(AdhocError),
+    Jiff(jiff::Error),
+}
+
+impl core::fmt::Display for Error {
+    fn fmt(&self, f: &mut core::fmt::Formatter) -> core::fmt::Result {
+        match self.kind {
+            ErrorKind::Adhoc(ref err) => {
+                core::fmt::Display::fmt(&err.message, f)
+            }
+            ErrorKind::Jiff(ref err) => err.fmt(f),
+        }
+    }
+}
+
+#[cfg(feature = "std")]
+impl std::error::Error for Error {
+    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+        match self.kind {
+            ErrorKind::Adhoc(_) => None,
+            ErrorKind::Jiff(ref err) => Some(err),
+        }
+    }
+}
+
+impl From<jiff::Error> for Error {
+    fn from(e: jiff::Error) -> Error {
+        Error { kind: ErrorKind::Jiff(e) }
+    }
+}
+
+/// A generic error message.
+#[derive(Clone, Debug)]
+struct AdhocError {
+    #[cfg(feature = "alloc")]
+    message: alloc::boxed::Box<str>,
+    #[cfg(not(feature = "alloc"))]
+    message: &'static str,
+}
+
+impl AdhocError {
+    fn from_args<'a>(message: core::fmt::Arguments<'a>) -> AdhocError {
+        #[cfg(feature = "alloc")]
+        {
+            AdhocError::from_display(message)
+        }
+        #[cfg(not(feature = "alloc"))]
+        {
+            let message = message.as_str().unwrap_or(
+                "unknown `jiff-icu` error (better error messages require \
+                 enabling the `alloc` feature for the `jiff-icu` crate)",
+            );
+            AdhocError::from_static_str(message)
+        }
+    }
+
+    #[cfg(feature = "alloc")]
+    fn from_display<'a>(message: impl core::fmt::Display + 'a) -> AdhocError {
+        use alloc::string::ToString;
+
+        let message = message.to_string().into_boxed_str();
+        AdhocError { message }
+    }
+
+    #[cfg(not(feature = "alloc"))]
+    fn from_static_str(message: &'static str) -> AdhocError {
+        AdhocError { message }
+    }
+}