jiff README

项目的 README,来自 github.com/BurntSushi/jiff。合并为一个 markdown 文件:README.md。

Jiff

Jiff is a datetime library for Rust that encourages you to jump into the pit of success. The focus of this library is providing high level datetime primitives that are difficult to misuse and have reasonable performance. Jiff supports automatic and seamless integration with the Time Zone Database, DST aware arithmetic and rounding, formatting and parsing zone aware datetimes losslessly, opt-in Serde support and a whole lot more.

Jiff takes enormous inspiration from Temporal, which is a TC39 proposal to improve datetime handling in JavaScript.

Build status Crates.io Docs.rs

Dual-licensed under MIT or the UNLICENSE.

Documentation

Example

Here is a quick example that shows how to parse a typical RFC 3339 instant, convert it to a zone aware datetime, add a span of time and losslessly print it:

use jiff::{Timestamp, ToSpan};

fn main() -> Result<(), jiff::Error> {
    let time: Timestamp = "2024-07-11T01:14:00Z".parse()?;
    let zoned = time.in_tz("America/New_York")?.checked_add(1.month().hours(2))?;
    assert_eq!(zoned.to_string(), "2024-08-10T23:14:00-04:00[America/New_York]");
    // Or, if you want an RFC3339 formatted string:
    assert_eq!(zoned.timestamp().to_string(), "2024-08-11T03:14:00Z");
    Ok(())
}

There are many more examples in the documentation.

Usage

Jiff is on crates.io and can be used by adding jiff to your dependencies in your project's Cargo.toml. Or more simply, just run cargo add jiff.

Here is a complete example that creates a new Rust project, adds a dependency on jiff, creates the source code for a simple datetime program and then runs it.

First, create the project in a new directory:

$ cargo new jiff-example
$ cd jiff-example

Second, add a dependency on jiff:

$ cargo add jiff

Third, edit src/main.rs. Delete what's there and replace it with this:

use jiff::{Unit, ZonedDateTime};

fn main() -> Result<(), jiff::Error> {
    let now = ZonedDateTime::now().round(Unit::Second)?;
    println!("{now}");
    Ok(())
}

Fourth, run it with cargo run:

$ cargo run
   Compiling jiff v0.2.0 (/home/andrew/rust/jiff)
   Compiling jiff-play v0.2.0 (/home/andrew/tmp/scratch/rust/jiff-play)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 1.37s
     Running `target/debug/jiff-play`
2024-07-10T19:54:20-04:00[America/New_York]

The first time you run the program will show more output like above. But subsequent runs shouldn't have to re-compile the dependencies.

Crate features

Jiff has several crate features for customizing support for Rust's standard library, serde support and whether to embed a copy of the Time Zone Database into your binary.

The "crate features" section of the documentation lists the full set of supported features.

Performance

The most important design goal of Jiff is to be a high level datetime library that makes it hard to do the wrong thing. Second to that is performance. Jiff should have reasonable performance, but there are likely areas in which it could improve. See the bench directory for benchmarks.

Note that performance is still an important goal. Some aspects of Jiff have had optimization attention paid to them, but many still have not. It is a goal to improve where we can, but performance will generally come second to API comprehension and correctness.

The submodules in Jiff, especially jiff::fmt, often work as an escape hatch for more complicated APIs that provide more control. For example, using the std::fmt::Display implementation of ZonedDateTime makes it difficult to write the data into a reusable buffer. Conversely, jiff::fmt::temporal::DateTimePrinter::print_zoned_datetime provides a way to write a ZonedDateTime into an existing String or even a Vec<u8>.

Platform support

The question of platform support in the context of datetime libraries comes up primarily in relation to time zone support. Specifically:

Both of these require some level of platform interaction.

For discovering time zone transition data, Jiff relies on the IANA Time Zone Database. On Unix systems, this is usually found at /usr/share/zoneinfo, although it can be configured via the TZDIR environment variable (which Jiff respects). On Windows, Jiff will automatically embed a copy of the time zone database into the compiled library.

For discovering the system time zone, Jiff reads /etc/localtime on Unix. On Windows, Jiff reads the Windows-specific time zone identifier via GetDynamicTimeZoneInformation and then maps it to an IANA time zone identifier via Unicode's CLDR XML data.

I expect Jiff to grow more support for other platforms over time. Please file issues, although I will likely be reliant on contributor pull requests for more obscure platforms that aren't easy for me to test.

For more on platform support, see PLATFORM.md.

Dependencies

At time of writing, it is no accident that Jiff has one required dependency on Unix. In general, my philosophy on adding new dependencies in an ecosystem crate like Jiff is very conservative. I consider there to be two primary use cases for adding new dependencies:

  1. When a dependency is practically required in order to interact with a platform.
  2. When a dependency is necessary for interoperability. For example, serde. But even here, I expect to be conservative, where I'm generally only willing to depend on things that have fewer breaking change releases than Jiff.

A secondary use case for new dependencies is if Jiff gets split into multiple crates. This is exactly what happened with the introduction of jiff-core. This helps reuse code between jiff and jiff-static, and also provides some fundamental datetime conversions to consumers who don't need the full footprint of jiff.

Minimum Rust version policy

This crate's minimum supported rustc version (MSRV) is 1.85.0. Jiff itself, and any dependencies of Jiff within this repository, will never use a Rust version that requires a Rust compiler released in the previous 1 year. (Dependents of Jiff in this repository, e.g., jiff-icu, may use a newer MSRV, but never one that is newer than the crate it is trying to integrate with.)

Jiff does have other dependencies whose MSRV is outside the control of Jiff (for example, windows-sys and portable-atomic), and it's possible there may be a choice between "upgrade and increase the MSRV for those targets where the dependency is used" and "don't upgrade, retain the MSRV but potentially introduce additional copies of crates into downstream dependency trees." While such instances should be quite rare because of Jiff's conservative dependency philosophy, it's possible it could happen. In which case, I reserve the right to make a judgment call that may, in practice, result in a newer-than-1-year Rust compiler for targets where that dependency is used.

As is standard in the Rust ecosystem, Jiff does not consider an increase in its MSRV to be a semver incompatible change. However, Jiff will limit MSRV increases to minor version updates. For example, if Jiff 1.0 requires Rust 1.20.0, then Jiff 1.0.z for all values of z will also require Rust 1.20.0 or newer. However, Jiff 1.y for y > 0 may require a newer minimum version of Rust.

jiff (BurntSushi/jiff)

正在搜索数据库…

3.2K ·GitHub
这是什么?Jiff 是一个 Rust 日期时间库,设计目标是尽量不让人误用。它提供带时区感知的日期时间、考虑夏令时的运算和取整,以及无损的解析和格式化。
它是应用程序,还是我要添加到代码里的库?它是一个 Rust crate,你需要把它作为依赖添加到项目中。它不是独立的应用程序,也不是命令行工具。
怎样把它添加到项目里?在项目目录中运行 'cargo add jiff',或者把 jiff 添加到 Cargo.toml 中。该 crate 发布在 crates.io 上,README 中有一个完整示例,演示如何创建新项目并运行它。
使用它之前需要准备什么?你需要一个带有 cargo 的 Rust 工具链。支持的最低 rustc 版本是 1.85.0。Serde 支持和嵌入时区数据库都是可选的 crate 功能。
时区处理在所有操作系统上的表现都一样吗?并不完全一样。在 Unix 上,Jiff 从 /usr/share/zoneinfo(或 TZDIR 指定的路径)读取 IANA 数据库,并从 /etc/localtime 读取系统时区。在 Windows 上,它会嵌入数据库,并通过 CLDR 把 Windows 时区映射到 IANA 时区。其他平台则依赖贡献者提交的拉取请求。
它是否借鉴了某个现有的标准或库?是的。它的设计主要借鉴了 JavaScript 的 TC39 Temporal 提案。README 还将它与 chrono、time、hifitime 和 icu 进行了对比。
它支持 Serde 序列化吗?支持。Serde 支持通过 crate 功能按需开启,只有启用时才会产生相应开销。
我能把时区数据库嵌入到二进制文件中吗?可以,通过一个 crate 功能实现。在 Windows 上数据库会自动嵌入,而在 Unix 上 Jiff 使用系统的 IANA 数据库,即 /usr/share/zoneinfo,或 TZDIR 中设置的路径。
我能在不做额外内存分配的情况下写入日期时间吗?README 指出,std::fmt::Display 的实现不适合用于可复用的缓冲区。DateTimePrinter::printzoneddatetime 则可以把 ZonedDateTime 直接写入已有的 String 或 Vec 中。
不同版本之间 API 有多稳定?README 表示,提高 MSRV(最低支持的 Rust 版本)不被视为 semver 不兼容的变更,但这类提高仅限于次版本号更新。
大小
4.5 MB
星标
3.2K
更新
提交Nov 17
时长
2年
提交 · 90 天