ICU timezone data

This document describes Fuchsia's support for loading ICU timezone data from ICU data files (icudtl.dat). Programs load timezone data dynamically based on the resources most appropriate for their application.

For more details on the general use of ICU APIs in Fuchsia, see International Components for Unicode use in Fuchsia

Make the ICU data available

In order for the system default ICU data files to be visible to a program in Fuchsia, you must include the resource dependency in your package:

"//src/intl:icudtl",

Timezone configuration data

To provide a specific version of the timezone data files to your package as configuration data, use the icu_tzdata_config_data() template in your BUILD.gn file and include it as a dependency in your package declaration:

# Build rule to provide system TZData for the given package
icu_tzdata_config_data("icu_tz_data_for_tz_version_parrot") {
  for_pkg = "tz_version_parrot"
}

Then, request the config-data capability in your component to map the subdirectory for your package into the component's namespace:

// Capabilities used by this component.
use: [
    // Map config-data for this package into namespace
    {
        directory: "config-data",
        rights: [ "r*" ],
        path: "/config/data",
        subdir: "tz_version_parrot",
    },
],

Load the default ICU data

You must load the ICU data in your program to make the locale data available. Otherwise, no locale data will be available and your ICU code will behave as if the set of i18n data is empty.

Include the ICU data library dependency in your BUILD.gn file:
C++
```
"//third_party/icu",
```
Note: You can find the C++ library source at //src/lib/icu_data/cpp
Rust
```
"//src/lib/icu_data/rust/icu_data",
```
Note: You can find the Rust library source at //src/lib/icu_data/rust

Import the ICU data library into your source files:

C++

#include "src/lib/icu_data/cpp/icu_data.h"

Rust

use icu_data::Loader;

Initialize the ICU data loader:
C++
```
const auto result = icu_data::Initialize();
ASSERT_EQ(result, ZX_OK) << "icu_data::Initialize failed";
```
Rust
```
// Load the ICU data
let _loader = Loader::new().expect("loader constructed successfully");
```
Note: At least one instance of icu_data::Loader must be kept alive for as long as your code needs ICU data. To simplify things, consider keeping a reference to the instance for the lifetime of the program.

You are now ready to use ICU data in your program.

Load from the product configuration

To load the specific version of the ICU data provided by icu_tzdata_config_data(), initialize the loader with the path to the data directory and revision file:

C++

// Default directory for timezone .res files
constexpr char kDefaultTzdataDir[] = "/config/data/tzdata/icu/44/le";
// Path to file containing the expected time zone database revision ID.
constexpr char kDefaultTzRevisionFilePath[] = "/config/data/tzdata/revision.txt";
ASSERT_TRUE(files::IsDirectory(kDefaultTzdataDir))
    << "Error: tzdata directory \"" << kDefaultTzdataDir << "\" doesn't exist.";

const auto result = icu_data::InitializeWithTzResourceDirAndValidate(kDefaultTzdataDir,
                                                                     kDefaultTzRevisionFilePath);
ASSERT_EQ(result, ZX_OK) << "icu_data::InitializeWithTzResourceDirAndValidate failed";

Rust

const DEFAULT_TZDATA_DIR: &str = "/config/data/tzdata/icu/44/le";
const DEFAULT_TZREVISION_FILE_PATH: &str = "/config/data/tzdata/revision.txt";

// Load the ICU data
let _loader = Loader::new_with_tz_resources_and_validation(
    DEFAULT_TZDATA_DIR,
    DEFAULT_TZREVISION_FILE_PATH,
)
.expect("loader constructed successfully");

Appendices

Modifying the system time zone information

During development, use the setui_client program to check or set the current time zone ID on a Fuchsia target. For more information about the available options, run the following commands:

ffx config set setui true // only need to run once
ffx setui intl --help