Migration¶

0.1.x to 0.2.0¶

All comparisons and examples here are compiled with the following imports:

#import "@preview/icu-datetime:0.2.0" as icu02
#import "@preview/icu-datetime:0.1.2" as icu01

The replacement for all fmt-* functions is fmt. The old documentation is available at nerixyz.github.io/icu-typ/v0.1.2.

`fmt-date`¶

let fmt-date(
  dt,
  locale: "en",
  length: "full"
)

Changing fmt-date to fmt will most likely result in the same output. There are a few differences, though:

"full" is no longer available as a length option. To get the equivalent of the full length, pass date-fields: "YMDE" to fmt.
If the passed date has time fields, then the time would be shown in addition to the date. To only show the date, specify date-fields: "YMD" explicitly. See defaults for more information.

Comparison

#let date = (day: 12, month: 8, year: 2024)
#table(
  columns: 2,
  [*0.1.2*], [*0.2.0*],

  icu01.fmt-date(date),
  icu02.fmt(date, length: "long", date-fields: "YMDE"),

  icu01.fmt-date(date, length: "long"),
  icu02.fmt(date, length: "long"),

  icu01.fmt-date(date, length: "medium"),
  icu02.fmt(date, length: "medium"),

  icu01.fmt-date(date, length: "short"),
  icu02.fmt(date, length: "short"),
)

`fmt-time`¶

let fmt-time(
  dt,
  locale: "en",
  length: "short"
)

Change fmt-time to fmt. In the new fmt, length won't affect the precision. Instead, time-precision is used. If length was "short" (default), specify time-precision: "minute". Otherwise, specify time-precision: "second".

Similar to fmt-date: If the passed datetime has date fields and time-precision isn't specified, the date would be displayed as well. See defaults for more information.

Comparison

#let time = (hour: 13, minute: 5, second: 0)
#table(
  columns: 2,
  [*0.1.2*], [*0.2.0*],

  icu01.fmt-time(time), icu02.fmt(time),
  icu01.fmt-time(time, length: "medium"), icu02.fmt(time, time-precision: "second"),
  icu01.fmt-time(time, length: "short"), icu02.fmt(time),
)

`fmt-datetime`¶

let fmt-datetime(
  dt,
  locale: "en",
  date-length: "long",
  time-length: "short"
)

Change fmt-datetime to [fmt] and update the parameters:

When using default parameters (date: long, time: short), specify length: "long".
date-length
- "full": specify date-fields: "YMDE", length: "long"
- "long" (old default): specify date-fields: "YMD", length: "long"
- "medium": specify date-fields: "YMD", length: "medium"
- "short": specify date-fields: "YMD", length: "short"
time-length:
- "medium": specify time-precision: "second"
- "short" (old default): specify time-precision: "minute"
Make sure that either both of date-fields and time-precision or neither are specified (see defaults for more information).

Comparison

#let dt = (
  year: 2024, month: 6, day: 30,
  hour: 18, minute: 2, second: 23,
)
#table(
  columns: 2, stroke: 0.5pt,
  [*0.1.2*], [*0.2.0*],
  table.hline(stroke: 2pt),

  icu01.fmt-datetime(dt), icu02.fmt(dt, length: "long"),

  icu01.fmt-datetime(dt, date-length: "full", time-length: "short"),
  icu02.fmt(dt, date-fields: "YMDE", length: "long", time-precision: "minute"),

  icu01.fmt-datetime(dt, date-length: "long", time-length: "short"),
  icu02.fmt(dt, date-fields: "YMD", length: "long", time-precision: "minute"),

  icu01.fmt-datetime(dt, date-length: "medium", time-length: "short"),
  icu02.fmt(dt, date-fields: "YMD", length: "medium", time-precision: "minute"),

  icu01.fmt-datetime(dt, date-length: "short", time-length: "short"),
  icu02.fmt(dt, date-fields: "YMD", length: "short", time-precision: "minute"),

  table.hline(stroke: 2pt),

  icu01.fmt-datetime(dt, date-length: "full", time-length: "medium"),
  icu02.fmt(dt, date-fields: "YMDE", length: "long", time-precision: "second"),

  icu01.fmt-datetime(dt, date-length: "long", time-length: "medium"),
  icu02.fmt(dt, date-fields: "YMD", length: "long", time-precision: "second"),

  icu01.fmt-datetime(dt, date-length: "medium", time-length: "medium"),
  icu02.fmt(dt, date-fields: "YMD", length: "medium", time-precision: "second"),

  icu01.fmt-datetime(dt, date-length: "short", time-length: "medium"),
  icu02.fmt(dt, date-fields: "YMD", length: "short", time-precision: "second"),
)

`fmt-timezone`¶

let fmt-timezone(
  offset: none, // required

  iana: none,
  bcp47: none,

  local-date: none,
  metazone-id: none,

  zone-variant: none,

  locale: "en",
  fallback: "localized-gmt",
  format: none
)

As with the other functions, this is replaced by fmt. Specify zone (dictionary with offset, iana/bcp47) and zone-style to output just the zone. Zone variants are now automatically resolved if a date is given. Otherwise, the standard variant is always used. The fallback is no longer customizable.

Comparison

// from the examples
#table(
  columns: 2,
  [*0.1.2*], [*0.2.0*],

  icu01.experimental.fmt-timezone(
    offset: "-07",
    iana: "America/Los_Angeles",
    zone-variant: "st",
    local-date: datetime.today(),
    format: "specific-non-location-long",
  ),
  // We didn't specify a date, so the standard variant will be used.
  icu02.fmt(
    (:), // empty dictionary
    zone: (offset: "-07", iana: "America/Los_Angeles"),
    zone-style: "specific-long",
  ),

  icu01.experimental.fmt-timezone(
    offset: "-07",
    iana: "America/Los_Angeles",
    zone-variant: "st",
    format: (
      iso8601: (
        format: "utc-extended",
        minutes: "required",
        seconds: "optional",
      ),
    ),
  ),
  icu02.fmt(
    (:), // empty dictionary
    zone: (offset: "-07", iana: "America/Los_Angeles"),
    zone-style: "localized-offset-long", // GMT is always included
  ),
)

`fmt-zoned-datetime`¶

let fmt-zoned-datetime(
  dt,
  zone,

  locale: "en",
  fallback: "localized-gmt",
  date-length: "long",
  time-length: "long"
)

This is most similar to the new fmt. After changing the call itself, consider the following changes to the arguments:

zone: This was previously a positional argument. In fmt, it's now a named one (see zone). In the dictionary itself, metazone-id and zone-variant have been removed. The zone variant is now automatically inferred from the date.
fallback: This argument was removed. The fallback is always localized-gmt (i.e. GMT±hh:mm).
date-length: Same changes as for fmt-datetime are required. For none, pass none to date-fields.
time-length: This mostly corresponds to time-precision.
- "full": Pass time-precision: "second", zone-style: "specific-long"
- "long": Pass time-precision: "second", zone-style: "specific-short"
- "medium": Pass time-precision: "second"
- "short": Pass time-precision: "minute"
- none: Pass time-precision: none

Comparison

Note: This only shows a comparison for time-length, as the changes to date-length are equivalent to fmt-datetime.

#let dt = (
  year: 2024, month: 6, day: 30,
  hour: 18, minute: 2, second: 23,
)
#let zone01 = (
  offset: "-07",
  iana: "America/Los_Angeles",
  // in 0.1.2, we had to specify the variant explcicitly
  zone-variant: "dt",
)
#let zone02 = (offset: "-07", iana: "US/Pacific")

#let fmt-zoned-dt01 = icu01.experimental.fmt-zoned-datetime
#table(
  columns: 3,
  [`time-length` (0.1.2)], [*0.1.2*], [*0.2.0*],

  [full],
  fmt-zoned-dt01(dt, zone01, time-length: "full", date-length: none),
  icu02.fmt(
    dt,
    zone: zone02,
    time-precision: "second",
    zone-style: "specific-long",
  ),

  [long (default)],
  fmt-zoned-dt01(dt, zone01, time-length: "long", date-length: none),
  icu02.fmt(
    dt,
    zone: zone02,
    time-precision: "second",
    zone-style: "specific-short",
  ),

  [medium],
  fmt-zoned-dt01(dt, zone01, time-length: "medium", date-length: none),
  icu02.fmt(dt, zone: zone02, time-precision: "second"),

  [short],
  fmt-zoned-dt01(dt, zone01, time-length: "short", date-length: none),
  icu02.fmt(dt, zone: zone02, time-precision: "minute"),
)

Migration¶

0.1.x to 0.2.0¶

fmt-date¶

fmt-time¶

fmt-datetime¶

fmt-timezone¶

fmt-zoned-datetime¶

`fmt-date`¶

`fmt-time`¶

`fmt-datetime`¶

`fmt-timezone`¶

`fmt-zoned-datetime`¶