"zone" vs "time zone"

[robertbastian]

We're not very consistent with when we use "zone" and when we spell out "time zone".

For types, we have TimeZoneBcp47Id, TimeZoneInfo, TimeZoneModel, but ZoneVariant, ZoneOffsets, and ZoneOffsetCalculator.

For methods, datetime uses .with_zone_{location,offset,...}, but also load_time_zone_{essentials, locations,...}.

ZonedDateTime has a field zone: TimeZoneInfo, but the we use time_zone: TimeZoneInfo on FFI.

[robertbastian]

Time type and subtypes at icu::time root. Remove Iso prefix from HMS because NanoSecond doesn't have it either, and the ISO model is not very special.

Current Name	Proposed Name
icu::timezone::Time	icu::time::Time
icu::timezone::types::IsoHour	icu::time::Hour
icu::timezone::types::IsoMinute	icu::time::Minute
icu::timezone::types::IsoSecond	icu::time::Second
icu::timezone::types::NanoSecond	icu::time::Nanosecond

TimeZoneInfo, composite types and parser at icu::time root.

Current Name	Proposed Name
icu::timezone::DateTime<A>	icu::time::DateTime<A>
icu::timezone::TimeZoneInfo<M>	icu::time::TimeZoneInfo<M>
icu::timezone::ZonedDateTime<A>	icu::time::ZonedDateTime<A>
icu::timezone::IxdtfParser	icu::time::ZonedDateTimeParser
icu::timezone::InvalidOffsetError	icu::time::InvalidOffsetError
icu::timezone::ParseError	icu::time::ParseError

Time zones things in a icu::time::zone module, using TimeZone and not just Zone:

Current Name	Proposed Name
icu::timezone::TimeZoneBcp47Id	icu::time::zone::TimeZoneId
icu::timezone::ZoneVariant	icu::time::zone::TimeZoneVariant
icu::timezone::UtcOffset	icu::time::zone::UtcOffset
icu::timezone::ZoneOffsets	icu::time::zone::UtcOffsets
icu::timezone::ZoneOffsetCalculator	icu::time::zone::UtcOffsetCalculator

Time zone info models also in icu::time::zone because there isn't really a better place:

Current Name	Proposed Name
icu::timezone::TimeZoneModel	icu::time::zone::TimeZoneInfoModel
icu::timezone::models::AtTime	icu::time::zone::models::AtTime
icu::timezone::models::Base	icu::time::zone::models::Base
icu::timezone::models::Full	icu::time::zone::models::Full

IANA conversions in icu::time::zone::iana:

Current Name	Proposed Name
icu::timezone::TimeZoneIdMapper[Borrowed,...]	icu::time::zone::iana::IanaMapper[Borrowed,...]
icu::timezone::TimeZoneBcp47Iter	icu::time::zone::iana::TimeZoneIdIter
icu::timezone::TimeZoneCanonicalIanaIter	icu::time::zone::iana::CanonicalIanaIter

Windows conversions in icu::time::zone::windows:

Current Name	Proposed Name
icu::timezone::WindowsTimeZoneMapper[Borrowed]	icu::time::zone::windows::WindowsMapper[Borrowed]

[robertbastian]

Also the field ZonedDateTime::zone and the FFI argument time_zone: TimeZoneInfo should probably be called zone_info to drive home that this is an enriched time zone.

[sffc]

Now that we have thin DateTime, we should also change TimeZoneModel::LocalTime to be DateTime<Iso>.

[sffc]

I think NanoSecond should be Nanosecond

Not sure about icu_time crate name. icu_clock has a nice ring and is the closest parallel to calendar (you read dates from a calendar and times from a clock). icu_chrono is fine too.

If we put the time zone fields like TimeZoneId in a sub-module, then maybe Hour and friends should go in a sub-module. icu::clock::time::Hour?

All the rest of the names in the table are LGTM.

[robertbastian]

icu_clock is bad, because it's the physical object that tells you the time, not the system of time calculations (like a calendar is). I much prefer icu_time over icu_chrono, nobody knows what chrono means, it's just a weird synonym for time that C++ started using because the time name was already taken.

[robertbastian]

icu_temporal would actually be more aligned with icu_calendar; it's a crate about things related to time, temporal things.

[sffc]

@Manishearth @zbraniecki Feedback?

[Manishearth]

I don't like icu_clock, it feels like an API for system time (in a way that "calendar" is not). "calendar" can mean calendar systems, "clock" doesn't have an easy parallel.

icu_time sounds great to me, I don't see a reason to work around it.

As far as Zone vs TimeZone, I don't feel like it's a problem we must solve, but it's a problem we could solve

Time type and subtypes at icu::time root. Remove Iso prefix from HMS because NanoSecond doesn't have it either, and the ISO model is not very special.

Strongly in favor, I think the reason behind these names (consistency with IsoYear / etc) is not relevant anymore)

TimeZoneInfo, composite types and parser at icu::time root.

In favor of the changes here, but unsure on renaming IxdtfParser. It might be nice to be specific about what format it parses. OTOH people mostly haven't heard of ixdtf.

Time zones things in a icu::time::zone module, using TimeZone and not just Zone:

I like this, and I like Zone -> Utc where it matters.

IANA conversions in icu::time::zone::iana:

Windows conversions in icu::time::zone::windows:

I don't love four levels of modules but it's not that big a deal for these less common types. Otherwise like the naming here

[nekevss]

FWIW, I'd agree that icu_clock sounds like a system time crate.

Both icu_time and icu_temporal sounds fine with a slight preference towards icu_temporal because having a DateTime<A> and ZonedDateTime<A> in icu_time seems slightly surprising to me.

[sffc]

Sounds like people are okay with icu_temporal. I am, too, though I should flag @justingrant who may worry that this would further the confusion about icu_temporal::DateTime looking like it is some official DateTime for the Rust ecosystem when it is only a thin interface for formatting.

[Manishearth]

I'm not OK with icu_temporal; I'd rather not have confusion between ECMA Temporal and ICU Temporal. I think icu_time is fine. Time zones are a part of dealing with time.

[sffc]

I'm somewhat opposed to icu_time. It sounds like it is "ICU4X's time formatting crate", which is not true. I think it is confusing with icu_datetime, which is actually a formatting utility. This is a crate that is barely a component crate and is only categorized as such because it depends on another component crate (icu_calendar, which is a good name). I'm also somewhat opposed to icu_timezone since it now does more than time zones, although time zones are still the primary ICU4X data in the crate, so for me icu_timezone probably is slightly above icu_time.

My favorite is still icu_clock. I think the parallel between a Calendar for dates and a Clock for times is compelling. I am not distracted by the analogy to the "system clock", but I acknowledge that it is a possible source of confusion. The other names are all fine.

So, sounds like we're headed toward a bikeshed ballot. Any more to add to the list?

1. icu_timezone
2. icu_time
3. icu_clock
4. icu_chrono
5. icu_temporal

Here are some from Gemini. Any we want to promote?

• icu_chronos (Greek for "time")
• icu_chronometry
• icu_tempo
• icu_tempus (Latin for "time")
• icu_timekit and similar things like timewarp and timecraft
• icu_meridian
• icu_nexus
• icu_tick
• icu_span
• icu_chron
• icu_phase
• icu_sundial
• icu_hourglass

I kind-of like icu_chronos; doesn't have the name conflict with "chrono" but it is still clearly about chronology. icu_tempo is also curious.

[Manishearth]

I am also fine with icu_timezone. I don't like icu_temporal or icu_clock.

I don't think any of those other names are good: I think clever names work well for utils crates but in the icu_* universe they stand out and feel like they're interoperating with some other fancily named thing: e.g. icu_chrono and icu_temporal sound like they interoperate with those things. Even if such a project does not exist, the fancy name makes me think such a project does. (The utils crates don't have this problem, they are the fancily named other project. But icu_foo means "icu crate for dealing with foo" and if foo is a fancy word then it sounds like some 3p integration)

Tbh I'm not sure we need a vote, I don't see how this issue became an issue for discussing the crate name. It's unclear to me if anyone has provided a reason for disliking icu_timezone.

But my vote is 1 ~> 2 >> 5 ~> 3 > 4, I'm rather strongly against any of the more clever names.

[sffc]

I don't see how this issue became an issue for discussing the crate name.

The first line of @robertbastian's proposal in comment#2 is the new crate name. I think it's the most important and probably most controversial proposal in that post.

But icu_foo means "icu crate for dealing with foo"

This is the crux. Is it the crate for "dealing with" the name? Maybe so. I think "processing" might be a better term. icu_calendar processes calendars, producing dates. icu_datetime processes dates, producing strings. icu_clock would process clocks, producing times.

I don't think any of those other names are good: I think clever names work well for utils crates

I don't see these as "clever" names. Some of them, sure. But there is nothing clever about "temporal" or "clock" or "chronos" referring to a crate dealing with times.

It's unclear to me if anyone has provided a reason for disliking icu_timezone.

Because the crate does more than time zones now?

It's weird to import icu::timezone::DateTime, a requirement to format a datetime without a time zone.

[robertbastian]

I think "chrono" and "chronos" are fancy names, the average developer will not know that it means timey-things.

[Manishearth]

This is the crux. Is it the crate for "dealing with" the name? Maybe so. I think "processing" might be a better term. icu_calendar processes calendars, producing dates. icu_datetime processes dates, producing strings. icu_clock would process clocks, producing times.

My choice of language there was vague. Regardless of whether it is for dealing with or processing or whatever, putting a fancy name there makes it sound like "the ICU crate for verbing with FancyName", which makes it sound like an external project.But there is nothing clever about "temporal" or "clock" or "chronos" referring to a crate dealing with times.

I think "processing" might be a better term. icu_calendar processes calendars, producing dates. icu_datetime processes dates, producing strings. icu_clock would process clocks, producing times.

I'm not convinced by this. Firstly, the usage of clock doesn't match what I think of as a clock in this context. A timestamp is not a clock, a clock is something that changes, and this crate does not interoperate with system time APIs.

We do not have a Clock type. This crate does not process clocks.

Secondly, this falls down for crates like segmenter, casemapper, etc. We have a variety of naming conventions here from different constraints, I don't think we are beholden to backsolving a justification for the datetime constraint and applying it here.

But there is nothing clever about "temporal" or "clock" or "chronos" referring to a crate dealing with times.

Okay, whatever, some of them are not "clever", but they still sound like library names to me: they're using a word that is a bit removed from the usual vocabulary and not shared with any of the types it contains.

The only one that doesn't have this property, to me, is "clock", which has a different problem.

General rule of thumb: if the component crate is called icu_foo, it should have a type called Foo, FooBar (e.g. PluralRules), or some grammatical inflection thereof. If not, we risk misleading people about the purpose of the crate, either by telling them that the crate processes a type of thing that it does not contain, or that the crate interoperates with some other library named Foo.

[Manishearth]

Because the crate does more than time zones now?

It's weird to import icu::timezone::DateTime, a requirement to format a datetime without a time zone.

Okay, this is the first time this argument has been put forth here. I'm not super swayed by it, the type can be reexported if we want. I think we've ended up with a crate split that's got some issues but is also the best we can do, and it's fine if the name doesn't cover everything the crate does. DateTime is a simple wrapper type, it isn't the focus of the crate, I'm okay with it living wherever and having appropriate signposting/reexports.

This crate is still very much a timezones crate.

Also, never actually responded to this:

I'm somewhat opposed to icu_time. It sounds like it is "ICU4X's time formatting crate", which is not true. I think it is confusing with icu_datetime, which is actually a formatting utility.

I still think icu_time is fine. icu_calendar doesn't format calendars, and it performs a similar task: processing related to calendars. I think if people don't like icu_time then we should revisit icu_calendar.

[sffc]

icu_calendar doesn't format calendars

I'll push back on this. It "verbs" calendars in many other ways. And when (not if) we add calendar display names, they should probably go in icu_calendar.

My ranking is roughly: 3 > 5 ~> 4 ~>> 1 ~>> 2

Another idea: icu_datetime_timezone and re-export all the stuff from icu_datetime which is close to the only use case for these things.

[Manishearth]

I'll push back on this. It "verbs" calendars in many other ways

That's not pushback, that's in concordance with my opinion: this crate primarily "verbs" times/timezones, even though it doesn't format them. I mentioned formatting as a response to the idea that icu_time or icu_timezone makes it sound like it formats times/timezones, with an example of a similar crate that doesn't format.

icu_datetime_timezone is also fine

[Manishearth]

observation: our rankings are incompatible with the vetos

[justingrant]

I have no opinion about most of these renames because I don't have enough context, but here's feedback on a few of them:

icu::timezone::TimeZoneBcp47Id icu::time::zone::TimeZoneId

Although we may wish it were otherwise, the vast majority of computing platforms consider time zone IDs to be IANA names. So most developers will at first expect an API called TimeZoneId to return an IANA ID.

If an API exposes a non-IANA ID format then I think it'd be helpful to clarify this fact in the API name. So I'd suggest leaving this API name as-is for clarity, or using some other qualifier like TimeZoneUnicodeId, TimeZoneUts35Id, TimeZoneCldrId, etc. to clarify that this is NOT an IANA name. I don't think it matters very much what qualifier is used, as long as it's clear that this isn't an IANA ID.

In favor of the changes here, but unsure on renaming IxdtfParser. It might be nice to be specific about what format it parses. OTOH people mostly haven't heard of ixdtf.

If a format-specific name is retained, then Rfc9557Parser is probably the right name. Now that the RFC has been approved, it seems unlikely that IXDTF will ever be popularized as an acronym. Developers will just call them "RFC 9557 strings" like they do for ISO 8601 strings.

I also don't mind ZonedDateTimeParser because it makes it clear what's gonna come out the other end. And also what makes the parser different than, say, a parser for an ISO 8601 timestamp without annotations.

I am also fine with icu_timezone. I don't like icu_temporal or icu_clock.

Is this library only focused on timezones? If not then I'd avoid icu_timezone as false advertising.

Unless this is the Rust port of the JS Temporal API, I'd also vote against icu_temporal as needlessly confusing with another widely-used API.

Also, honestly, most people who've given feedback about the name "Temporal" in JS don't like the name. It was chosen to avoid confusion with the existing Date API. Had there been no legacy it would probably have been called Time or Date or DateTime. It's hard to imagine someone choosing it except as a last resort if all other better names were excluded.

re: icu_clock: after interacting with programmers during the design of Temporal, I don't think most developers understand the subtle differences between "clock time" vs. just "time". That isn't a reason to avoid icu_clock, but IMO "clock" doesn't add much (if any) additional meaning for most users over other synonyms like "time".

I think icu_chrono is OK but kinda obscure.

TL;DR - If icu_time is available that'd be my recommendation, followed by icu_clock and icu_chrono. I would avoid the other two. Sorry, I wasn't sure how to translate this into voting syntax!

[Manishearth]

Is this library only focused on timezones? If not then I'd avoid icu_timezone as false advertising.

That's part of the disagreement here, potentially.

Here are the current docs: https://unicode-org.github.io/icu4x/rustdoc/icu_timezone/index.html

All of the complex types are timezone related. However it also contains a simple Time, DateTime, and ZonedDateTime type.

(My opinion is that it's fine for icu_timezone to contain those types and they can be reexported from icu_datetime if the location feels confusing to people)

[BurntSushi]

I got linked here by @Manishearth and invited to offer an opinion. While I've perused the icu APIs a bit, I definitely don't have a ton of context.

With respect to the crate name, I think if I saw icu_chrono or icu_temporal, I would, absent other information, assume they are somehow related to the chrono Rust crate or the Temporal JS project, respectively. I think this goes toward's Manish's "fancy" name argument. They're just obscure enough that I would assume some kind of connection. Conversely, I would not assume that icu_time is related to the time crate.

Otherwise, I don't think I have enough context to levy an opinion. Mostly just going by the docs linked, the first line says that it's about time zones. But that makes me confused when I see types like DateTime defined in the crate, as I would expect that type to be in the icu_datetime crate. Which I think just leads me to believe that I don't really understand the API design philosophy, and probably makes me under-equipped to have an opinion here. But I think it's worth sharing that I am confused by the APIs here (even though I simultaneously believe that y'all have considered all of this and there's probably a very good reason for why things are the way they are).

I would also agree with @justingrant that if I see "time zone ID," then I'm probably going to assume that's an IANA time zone id. I don't think any other identifier has a lot of mindshare.

One other thing I'd point out is a potential incongruity with how Nanosecond is named. It matches the names of other units like Hour, Minute and Second, but its actual value is more like, "fractional seconds, to nanosecond precision." This becomes potentially confusable in contexts where you want to represent or expose milliseconds, microseconds and nanoseconds as distinct units. For example, std::time::Duration uses the subsec_ prefix to disambiguate between these concepts on the std::time::Duration type. I do the same in Jiff for its civil::Time type.

[Manishearth]

Otherwise, I don't think I have enough context to levy an opinion. Mostly just going by the docs linked, the first line says that it's about time zones. But that makes me confused when I see types like DateTime defined in the crate, as I would expect that type to be in the icu_datetime crate. Which I think just leads me to believe that I don't really understand the API design philosophy, and probably makes me under-equipped to have an opinion here.

Some background here: icu_datetime is date time formatting, and most of our formatter crates don't say "formatter" in them since it's a mouthful. The DateTime type is a thin wrapper around Date and Time which is occasionally needed for timezone stuff and of course one of the types you can feed to the datetime formatter. As such it needs to exist in icu_timezone or a dependency of it (icu_datetime depends on icu_timezone, since it can format zoned stuff). It feels weird to have a whole crate for a very small type, and then you need to figure out what to do with ZonedDateTime, so it ended up in this crate.

I generally feel that the decision to do so was done more out of expediency rather than some vision of what the icu_timezone crate should be about, so having it be named after times or timezones whilst containing one out-of-place type seems fine by me.

[Manishearth]

Anyway, thanks for the feedback. Yeah there's a lot of context here that's tricky to get across but the perspective of someone from the outside is super useful!

[robertbastian]

Although we may wish it were otherwise, the vast majority of computing platforms consider time zone IDs to be IANA names. So most developers will at first expect an API called TimeZoneId to return an IANA ID.

TimeZoneId represents an IANA time zone. It may use a different internal string representation, and different canonicalization equivalence classes, but it is inherently an IANA time zone (unlike, for example, Windows time zones) that can be parsed and serialized into IANA strings.

Maybe TimeZone would be a more correct name, its purpose is to represent a time zone, and we shouldn't get too hung up on how it represents a time zone.

[sffc]

My expectation of a type named TimeZone is that it has machinery for doing things with the time zone, such as Temporal.TimeZone had, like getting the next and previous transition.

However, given that DateTime in ICU4X does not have any extra functionality, instead serving as a bare input type to DateTimeFormatter, maybe I could see an argument about naming this type TimeZone.

[justingrant]

Although we may wish it were otherwise, the vast majority of computing platforms consider time zone IDs to be IANA names. So most developers will at first expect an API called TimeZoneId to return an IANA ID.

TimeZoneId represents an IANA time zone. It may use a different internal string representation, and different canonicalization equivalence classes, but it is inherently an IANA time zone (unlike, for example, Windows time zones) that can be parsed and serialized into IANA strings.

If I call as_str() on a TimeZoneId, is that output an IANA string? If not, then I'd suggest giving the type a name that hints that the default string representation won't be IANA. Otherwise most developers will reasonably assume that the result is going to be an IANA name.

If it's named TimeZone then it seems less of a big deal because that sounds like an object that does stuff as opposed to a string ID. I'd still love to see properties or methods exposed like Bcp47Id and IanaId to make it clear that there are different representations available.

Also, if a time zone instance uses inccu internally, what will it output when converting to IANA: "Asia/Calcutta" or "Asia/Kolkata"?

[robertbastian]

There doesn't necessarily need to be an as_str. It could be TimeZoneId::as_bcp47 which could return an icu::locale::subtags::Subtag (which in turn has an as_str).

Also, if a time zone instance uses inccu internally, what will it output when converting to IANA: "Asia/Calcutta" or "Asia/Kolkata"?

#5610 (comment)

[justingrant]

There doesn't necessarily need to be an as_str. It could be TimeZoneId::as_bcp47 which could return an icu::locale::subtags::Subtag (which in turn has an as_str).

This sounds like a good idea. More discoverable.

[sffc]

In #5610, we have a few definitions floating around for "time zone." ICU4X uses the definition based on CLDR, which defines BCP-47, which is derived from TZDB zone.tab, which is consistent with ECMA-262. (Let's not get into that here: see #5610.) But, this may not be the definition all users expect.

So, maybe instead of TimeZone, the original name Bcp47TimeZoneId was actually more accurate. We could also consider CldrTimeZone or similar, to emphasize that this is from that specific reckoning of time zones.

[Manishearth]

My expectation of a type named TimeZone is that it has machinery for doing things with the time zone, such as Temporal.TimeZone had, like getting the next and previous transition.

I don't think this is a useful litmus test: ICU4X's data-driven design means that most types with data from the user will have limited functionality, with most interesting functionality being on types wrapping ICU4X data. This is a choice driven by the language of implementation and API design.

But I think calling it ID is fine as well.

[Manishearth]

Decided to write down some facts to base the discussion off of:

• icu_timezone currently contains the following classes of types:
  • tools for mapping between different formats of time zone ids, like TimeZoneIdMapper
  • ZonedDateTimeParser for performing timezone-aware IXDTF parsing.
  • ZoneOffsetCalculator
  • Types for representing different time zone models, used by the other APIs
  • Different time zone id types, like TimeZoneBcp47Id
  • A bunch of types. The types themselves are overall rather simple:
    • ZoneVariant and UtcOffset
    • a simple Time type, that wraps IsoHour, IsoMinute, IsoSecond etc. I believe there is some desire to remove the typed time unit types and use integers instead
    • DateTime, a thin wrapper around an icu_calendar::Date that interoperates with icu_datetime::DatetimeFormatter. The main additional functionality it provides is parsing from an ixdtf string, otherwise it's similar to a (Date, Time)
    • ZonedDateTime, like DateTime but with a zone. Can be parsed with a ZonedDateTimeParser
• icu_calendar contains various Calendars, and a Date type, alongside a bunch of helper types like YearInfo etc
• Our formatter crates tend to be named after the thing they format
  • icu_datetime contains DatetimeFormatter, which is able to format Dates (from icu_calendar), Times, DateTimes, and ZonedDateTimes (from icu_timezone`).
  • icu_decimal contains DecimalFormatter, which formats fixed_decimal::Decimals
• We have non-formatter crates that are named after the thing they handle: icu_plurals classifies plurals (but doesn't format them), icu_casemap does casemapping, etc.
• Time and DateTime were moved into icu_timezone from icu_calendar since we wanted icu_calendar to have a very narrow purpose: handling dates. This also meant that we could remove the fancy date-wrapping APIs on DateTime.
• Time pretty clearly needs to be in icu_timezone or a dependency thereof, it cannot live in icu_datetime.
• Less clearly: DateTime also needs to live in icu_timezone or a dependency thereof, as icu_timezone lets you compute what a timezone resolves to at a particular date (TimeZoneInfo::at_time()). This means that DateTime cannot live in icu_datetime, since icu_datetime needs to depend on icu_timezone and not the other way around.