Update tutorials (#6590)

They are not currently working with 2.0 code

Author: robertbastian

tutorials/date-picker-data.md

@@ -11,8 +11,8 @@ Data generation is done using the `icu4x-datagen` tool, which pulls data from [U
 Verify that Rust is installed. If it's not, you can install it in a few seconds from [https://rustup.rs/](https://rustup.rs/).
 
 ```console
-$ cargo --version
-cargo 1.81.0 (2dbb1af80 2024-08-20)
+cargo --version
+# cargo 1.86.0 (adf9b6ad1 2025-02-28)
 ```
 
 Now you can run
@@ -26,7 +26,7 @@ cargo install icu4x-datagen
 We're ready to generate the data. We will use the blob format, and create a blob that will contain just Chakma data. At runtime we can then load it as needed.
 
 ```console
-$ icu4x-datagen --markers all --locales ccp --format blob --out ccp.blob
+icu4x-datagen --markers all --locales ccp --format blob --out ccp.blob
 ```
 
 This will generate a `ccp.blob` file containing data for Chakma.
@@ -41,7 +41,7 @@ This will generate a `ccp.blob` file containing data for Chakma.
 To use blob data, we will need to add the `icu_provider_blob` crate to our project:
 
 ```console
-cargo add icu_provider_blob
+cargo add icu_provider_blob --features alloc
 ```
 
 We also need to enable the `serde` feature on the `icu` crate to enable deserialization support:
@@ -58,29 +58,23 @@ locale is Chakma:
 use icu::locale::locale;
 use icu_provider_blob::BlobDataProvider;
 
-// Just below the imports (fill in the path):
-const CCP_BLOB_PATH: &str = "<absolute path to ccp.blob>";
-
-let datetime_formatter = if locale == locale!("ccp") {
+// replace the date_formatter creation
+let date_formatter = if locale == locale!("ccp") {
     println!("Using buffer provider");
 
-    let blob = std::fs::read(CCP_BLOB_PATH)
+    let blob = std::fs::read("ccp.blob")
         .expect("blob should read successfully")
         .into();
 
     let provider =
         BlobDataProvider::try_new_from_blob(blob).expect("deserialization should succeed");
 
-    DateTimeFormatter::try_new_with_buffer_provider(
-        &provider,
-        &(&locale).into(),
-        Default::default(),
-    )
-    .expect("should have data for selected locale")
+    DateTimeFormatter::try_new_with_buffer_provider(&provider, locale.into(), YMD::medium())
+        .expect("should have data for selected locale")
 } else {
     // As before
-    DateTimeFormatter::try_new(&(&locale).into(), Default::default())
-        .expect("should have data for selected locale")
+    DateTimeFormatter::try_new(locale.into(), YMD::medium())
+        .expect("should have data for specified locale")
 };
 ```
 
@@ -106,22 +100,19 @@ function load_blob(url, callback) {
 
 if (localeStr == "ccp") {
     load_blob("https://storage.googleapis.com/static-493776/icu4x_2023-11-03/ccp.blob", (blob) => {
-        let dateTimeFormatter = ICU4XDateTimeFormatter.create_with_lengths(
-            ICU4XDataProvider.create_from_byte_slice(blob),
+        let dateTimeFormatter = DateTimeFormatter.createYmdtWithProvider(
+            DataProvider.createFromBlob(blob),
             locale,
-            ICU4XDateLength.Medium,
-            ICU4XTimeLength.Medium,
+            DateTimeLength.Long,
         );
-        document.getElementById("output").innerText = dateFormatter.format_iso_datetime(isoDateTime);
+        document.getElementById("output").innerText = dateTimeFormatter.formatIso(isoDate, time);
     })
 } else {
-    let dateTimeFormatter = ICU4XDateTimeFormatter.create_with_lengths(
-        ICU4XDataProvider.create_compiled(),
-        locale,
-        ICU4XDateLength.Medium,
-        ICU4XTimeLength.Medium,
+    let dateTimeFormatter = DateTimeFormatter.createYmdt(
+            locale,
+            DateTimeLength.Long,
     );
-    document.getElementById("output").innerText = dateFormatter.format_iso_datetime(isoDateTime);
+    document.getElementById("output").innerText = dateTimeFormatter.formatIso(isoDate, time);
 }
 ```
 
@@ -134,67 +125,62 @@ Note: the following steps are currently only possible in Rust. 🤷
 When we ran `icu4x-datagen`, we passed `--markers all`, which make it generate *all* data for the Chakma locale, even though we only need date formatting. We can make `icu4x-datagen` analyze our binary to figure out which markers are needed:
 
 ```console
-$ icu4x-datagen --markers-for-bin target/debug/tutorial --locales ccp --format blob --out ccp_smaller.blob
+cargo build --release
+icu4x-datagen --markers-for-bin target/release/tutorial --locales ccp --format blob --out ccp_smaller.blob
 ```
 
-Note: you usually want to build with the `--release` flag, and analyze that binary, but we don't have all day.
+Note: you usually want to build with the `--release` flag, and analyze that binary.
 
 This should generate a lot fewer markers!
 
 Let's look at the sizes:
 
 ```console
-$ wc -c *.blob
-656767 ccp.blob
- 45471 ccp_smaller.blob
+wc -c *.blob
+# 5448603 ccp.blob
+#   13711 ccp_smaller.blob
 ```
 
 This is much better! Rerun your app with `ccp_smaller.blob` to make sure it still works!
 
 ## 5. Slimming the data pack ... again
 
-The last datagen invocation still produced a lot of markers, as you saw in its output. This is because we used the `DateFormatter` API, which can format dates for a lot of different calendars. However, if we are only using it with an Gregorian calendar date, so we don't need Coptic, Indian, etc. date formatting data.
+The last datagen invocation still produced a lot of markers, as you saw in its output. This is because we used the `DateTimeFormatter` API, which can format dates for a lot of different calendars (remember `en-u-ca-hebrew`). However, if we were only using it with a Gregorian calendar date, we wouldn't need Coptic, Indian, etc. date formatting data. Now, how do we communicate this to `--markers-for-bin`? Turns out, `icu::datetime` also exposes a `FixedCalendarDateTimeFormatter`, which is generic in a single calendar type. If you use this API instead, `--markers-for-bin` will only include the markers for that one calendar type.
 
-We've seen that `DateFormatter` pulls in a lot of data. It would be nice if we could tell it that we'll only ever use it with Gregorian dates. Turns out we can! `icu::datetime` also exposes a `TypedDateFormatter<C>`, which is generic in a single calendar type. If you use this API instead (instantiated as `TypedDateFormatter<Gregorian>`), `--markers-for-bin` will give you exactly the markers we manually selected in the last section. However, now you can be sure that you didn't make a mistake selecting the markers (which would be an awkward runtime error), and that you will never accidentally pass a non-Gregorian date into the formatter (which would an awkward runtime error with `DateFormatter`, but is a compile-time error with `TypeDateFormatter`).
+Replace the `DateTimeFormatter::try_new` calls with `FixedCalendarDateTimeFormatter::try_new`, and change the `format` invocation to convert the input to the Gregorian calendar:
 
 ```rust
-let date_formatter = TypedDateFormatter::<Gregorian>::try_new_with_length(
-    &(&locale).into(),
-    length::Date::Medium,
-)
-.expect("should have data for selected locale");
-
-println!(
-    "Date: {}",
-    // We need to convert to the explicit calendar via `.to_calendar()`. 
-    date_formatter.format(&iso_date.to_calendar(Gregorian)),
-);
+    println!("Date: {}", date_formatter.format(&iso_date.to_calendar(Gregorian)));
 ```
 
+The generic type of `FixedCalendarDateTimeFormatter` will be inferred from the input, which now has type `&Date<Gregorian>` now. Unlike `DateTimeFormatter`, `FixedCalendarDateTimeFormatter` never applies calendar conversions on its input, so it will be a `FixedCalendarDateTimeFormatter<Gregorian, ...>`.
+
 Now we can run datagen with `--markers-for-bin` again:
 
 ```console
-$ cargo build
-$ icu4x-datagen --markers-for-bin target/debug/tutorial --locales ccp --format blob --out ccp_smallest.blob
+cargo build --release
+icu4x-datagen --markers-for-bin target/release/tutorial --locales ccp --format blob --out ccp_smallest.blob
 ```
 
 The output will be much shorter:
 
 ```console
-INFO  [icu_provider_export::export_impl] Generating marker datetime/gregory/datelengths@1
-INFO  [icu_provider_export::export_impl] Generating marker datetime/gregory/datesymbols@1
-INFO  [icu_provider_export::export_impl] Generating marker datetime/week_data@1
-INFO  [icu_provider_export::export_impl] Generating marker decimal/symbols@2
-INFO  [icu_provider_export::export_impl] Generating marker plurals/ordinal@1
+2025-05-14T14:26:52.306Z INFO  [icu_provider_export::export_impl] Generated marker DatetimeNamesMonthGregorianV1
+2025-05-14T14:26:52.308Z INFO  [icu_provider_export::export_impl] Generated marker DatetimeNamesYearGregorianV1
+2025-05-14T14:26:52.312Z INFO  [icu_provider_export::export_impl] Generated marker DatetimePatternsDateGregorianV1
+2025-05-14T14:26:52.324Z INFO  [icu_provider_export::export_impl] Generated marker DecimalDigitsV1
+2025-05-14T14:26:52.325Z INFO  [icu_provider_export::export_impl] Generated marker DecimalSymbolsV1
 ```
 
 And the blob will also be much smaller at the sizes:
 
 ```console
-$ wc -c *.blob
-656767 ccp.blob
- 45471 ccp_smaller.blob
-  4639 ccp_smallest.blob
+wc -c *.blob
+# 5448603 ccp.blob
+#   13711 ccp_smaller.blob
+#    4711 ccp_smallest.blob
 ```
 
 Rerun your app with `ccp_smallest.blob` to make sure it still works!
+
+Does the locale `en-u-ca-hebrew` still use the Hebrew calendar? Why is that?

tutorials/date-picker.md

@@ -14,7 +14,7 @@ Verify that Rust is installed. If it's not, you can install it in a few seconds
 
 ```console
 cargo --version
-# cargo 1.81.0 (2dbb1af80 2024-08-20)
+# cargo 1.86.0 (adf9b6ad1 2025-02-28)
 ```
 
 Create a new Rust binary crate with icu4x as a dependency:
@@ -30,7 +30,7 @@ cargo add icu
 We recommend using [CodePen](https://codepen.io/pen/?editors=1011) to follow along. To load ICU4X into CodePen, you can use this snippet in the JavaScript editor:
 
 ```javascript
-import { ICU4XLocale, ICU4XDataProvider, ICU4XDateFormatter, ICU4XDateTimeFormatter, ICU4XDateLength, ICU4XIsoDate, ICU4XIsoDateTime, ICU4XTimeLength } from "https://storage.googleapis.com/static-493776/icu4x_2023-11-03/js/index.js";
+import { Locale, DateFormatter, IsoDate, DateTimeLength } from "https://storage.googleapis.com/static-493776/2_0/npm/lib/index.mjs";
 ```
 
 This loads the full development ICU4X WebAssembly file. Since it may take some time to load on slow connections, we'll create a loading div. In future tutorials you will learn how to build an optimized WebAssembly file, reducing the size of the WASM file by 99% or more. Add this to your HTML:
@@ -86,8 +86,8 @@ let locale = match locale_str.trim().parse::<Locale>() {
 Try inputting locales in non-canonical syntax and see them normalized!
 
 ```bash
-$ cargo run
-Enter your locale: DE_CH
+cargo run
+Enter your locale: DE-CH
 You entered: de-CH
 ```
 
@@ -108,10 +108,13 @@ And in JavaScript:
 function update() {
     try {
         let localeStr = document.getElementById("localeinput").value;
-        let locale = ICU4XLocale.create_from_string(localeStr);
-        document.getElementById("output").innerText = locale.to_string();
+
+        let locale = Locale.fromString(localeStr);
+        let output = locale.toString();
+
+        document.getElementById("output").innerText = output;
     } catch(e) {
-        document.getElementById("output").innerText = e + ": " + e.error_value;
+        document.getElementById("output").innerText = e;
     }
 }
 
@@ -124,7 +127,7 @@ update();
 
 Try inputting locales in non-canonical syntax and see them normalized!
 
-> Locale: ES_419\
+> Locale: ES-419
 > Output: es-419
 
 ## 3. Formatting a Date
@@ -136,35 +139,31 @@ Now we will use built-in locale data to produce a formatted date.
 We would like to format today's date. We will get this from the `time` crate, which you need to add:
 
 ```console
-$ cargo add time --features local-offset
+cargo add time --features local-offset
 ```
 
 Now we can write the Rust code:
 
 ```rust
 // At the top of the file:
-use icu::calendar::{Date, Iso};
-use icu::datetime::{DateTimeFormatter, fieldsets::YMD};
+use icu::datetime::{DateTimeFormatter, fieldsets::YMD, input::Date};
 
 let locale = icu::locale::Locale::UNKNOWN; // to make this example compile
 
-/// Helper function to create an ICU4X DateTime for the current local time:
-fn get_current_date() -> Date<Iso> {
+// Put the following in the main() function:
+let iso_date = {
     let current_offset_date_time = time::OffsetDateTime::now_local().unwrap();
     Date::try_new_iso(
         current_offset_date_time.year(),
         current_offset_date_time.month() as u8,
         current_offset_date_time.day(),
     )
     .unwrap()
-}
-
-// Put the following in the main() function:
-let iso_date = get_current_date();
+};
 
 // Create and use an ICU4X date formatter:
 let date_formatter = DateTimeFormatter::try_new(
-    (&locale).into(),
+    locale.into(),
     YMD::medium(),
 )
 .expect("should have data for specified locale");
@@ -194,25 +193,15 @@ And this to JavaScript:
 // Run the function whenever the date input changes:
 document.getElementById("dateinput").addEventListener("input", update, false);
 
-/// Helper function to convert the date input to an ICU4X Date:
-function getDateFromInput() {
-    let dateStr = document.getElementById("dateinput").value;
-    let dateObj = dateStr ? new Date(dateStr) : new Date();
-    return ICU4XIsoDate.create(
-        dateObj.getYear() + 1900,
-        dateObj.getMonth() + 1,
-        dateObj.getDate(),
-    );
-}
-
 // Put the following in the update() function, inside the try block:
-let isoDate = getDateFromInput();
-let dateFormatter = ICU4XDateFormatter.create_with_length(
-    ICU4XDataProvider.create_compiled(), // we will learn what this means later
-    locale,
-    ICU4XDateLength.Medium,
-);
-document.getElementById("output").innerText = dateFormatter.format_iso_date(isoDate);
+let dateStr = document.getElementById("dateinput").value;
+
+let dateObj = dateStr ? new Date(dateStr) : new Date();
+let isoDate = new IsoDate(dateObj.getFullYear(), dateObj.getMonth() + 1, dateObj.getDate());
+let dateFormatter = DateFormatter.createYmd(locale, DateTimeLength.Long);
+let output = dateFormatter.formatIso(isoDate);
+
+document.getElementById("output").innerText = output;
 ```
 
 Try this in several locales, like `en` (English), `en-GB` (British English), and `th` (Thai). Observe how differently dates are represented in locales around the world! You can explicitly specify arbitrary calendar systems using the `u-ca` Unicode extension keyword in the locale. Try `en-u-ca-hebrew`!
@@ -223,22 +212,22 @@ Now we would also like to format the current time.
 
 ### Rust Part 4
 
-Use the API documentation for [`icu::time::DateTime`](https://docs.rs/icu/latest/icu/timezone/struct.DateTime.html) and [`icu::datetime::DateTimeFormatter`](https://docs.rs/icu/latest/icu/datetime/struct.DateTimeFormatter.html) to expand your app to format both date and time.
-
-Hint: You can use `Default::default()` for the `DateTimeFormatterOptions` argument.
+Use the API documentation for [`icu::time::DateTime`](https://docs.rs/icu/latest/icu/time/struct.DateTime.html) and [`icu::datetime::fieldsets`](https://docs.rs/icu/latest/icu/datetime/fieldsets/index.html) to expand your app to format both date and time.
 
 ### JavaScript Part 4
 
-Use the API documentation for [`ICU4XDateTime`](https://unicode-org.github.io/icu4x/tsdoc/classes/ICU4XDateTime.html) and [`ICU4XDateTimeFormatter`](https://unicode-org.github.io/icu4x/tsdoc/classes/ICU4XDateTimeFormatter.html) to expand your app to format both a date and a time.
+Use the API documentation for [`Time`](https://icu4x.unicode.org/2_0/tsdoc/classes/Time.html) and [`DateTimeFormatter`](https://icu4x.unicode.org/2_0/tsdoc/classes/DateTimeFormatter.html) to expand your app to format both a date and a time.
 
 Hint: You can create an HTML time picker with
 
 ```html
-<input type="time" id="timeinput" value="10:10"/>
+<p><label>Time: <input type="time" id="timeinput" value="10:10"/></label></p>
 ```
 
 Hint: You can create a `Date` from `dateStr` and `timeStr` with
 
 ```javascript
 let dateObj = dateStr && timeStr ? new Date(dateStr + " " + timeStr) : new Date();
 ```
+
+Note that Dates constructed this way will be in UTC.

tutorials/quickstart.md

@@ -17,7 +17,7 @@ To verify that, open a terminal and check that the results are similar to:
 
 ```console
 cargo --version
-cargo 1.81.0 (2dbb1af80 2024-08-20)
+# cargo 1.86.0 (adf9b6ad1 2025-02-28)
 ```
 
 ## 2. Creating an app with ICU4X as a dependency