71 lines
9.5 KiB
HTML
71 lines
9.5 KiB
HTML
<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><meta name="generator" content="rustdoc"><meta name="description" content="📚 This module documents ICU4X constructor signatures."><title>icu_provider::constructors - Rust</title><script>if(window.location.protocol!=="file:")document.head.insertAdjacentHTML("beforeend","SourceSerif4-Regular-6b053e98.ttf.woff2,FiraSans-Italic-81dc35de.woff2,FiraSans-Regular-0fe48ade.woff2,FiraSans-MediumItalic-ccf7e434.woff2,FiraSans-Medium-e1aa3f0a.woff2,SourceCodePro-Regular-8badfe75.ttf.woff2,SourceCodePro-Semibold-aa29a496.ttf.woff2".split(",").map(f=>`<link rel="preload" as="font" type="font/woff2"href="../../static.files/${f}">`).join(""))</script><link rel="stylesheet" href="../../static.files/normalize-9960930a.css"><link rel="stylesheet" href="../../static.files/rustdoc-ca0dd0c4.css"><meta name="rustdoc-vars" data-root-path="../../" data-static-root-path="../../static.files/" data-current-crate="icu_provider" data-themes="" data-resource-suffix="" data-rustdoc-version="1.93.1 (01f6ddf75 2026-02-11) (Arch Linux rust 1:1.93.1-1)" data-channel="1.93.1" data-search-js="search-9e2438ea.js" data-stringdex-js="stringdex-a3946164.js" data-settings-js="settings-c38705f0.js" ><script src="../../static.files/storage-e2aeef58.js"></script><script defer src="../sidebar-items.js"></script><script defer src="../../static.files/main-a410ff4d.js"></script><noscript><link rel="stylesheet" href="../../static.files/noscript-263c88ec.css"></noscript><link rel="alternate icon" type="image/png" href="../../static.files/favicon-32x32-eab170b8.png"><link rel="icon" type="image/svg+xml" href="../../static.files/favicon-044be391.svg"></head><body class="rustdoc mod"><!--[if lte IE 11]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><rustdoc-topbar><h2><a href="#">Module constructors</a></h2></rustdoc-topbar><nav class="sidebar"><div class="sidebar-crate"><h2><a href="../../icu_provider/index.html">icu_<wbr>provider</a><span class="version">2.1.1</span></h2></div><div class="sidebar-elems"><section id="rustdoc-toc"><h2 class="location"><a href="#">Module constructors</a></h2><h3><a href="#">Sections</a></h3><ul class="block top-toc"><li><a href="#which-constructor-should-i-use" title="Which constructor should I use?">Which constructor should I use?</a><ul><li><a href="#when-to-use-" title="When to use `*`">When to use <code>*</code></a></li><li><a href="#when-to-use-_unstable" title="When to use `*_unstable`">When to use <code>*_unstable</code></a></li><li><a href="#when-to-use-_with_buffer_provider" title="When to use `*_with_buffer_provider`">When to use <code>*_with_buffer_provider</code></a></li></ul></li><li><a href="#data-versioning-policy" title="Data Versioning Policy">Data Versioning Policy</a></li><li><a href="#data-providers-over-ffi" title="Data Providers Over FFI">Data Providers Over FFI</a></li></ul></section><div id="rustdoc-modnav"><h2 class="in-crate"><a href="../index.html">In crate icu_<wbr>provider</a></h2></div></div></nav><div class="sidebar-resizer" title="Drag to resize sidebar"></div><main><div class="width-limiter"><section id="main-content" class="content"><div class="main-heading"><div class="rustdoc-breadcrumbs"><a href="../index.html">icu_provider</a></div><h1>Module <span>constructors</span> <button id="copy-path" title="Copy item path to clipboard">Copy item path</button></h1><rustdoc-toolbar></rustdoc-toolbar><span class="sub-heading"><a class="src" href="../../src/icu_provider/constructors.rs.html#5-226">Source</a> </span></div><details class="toggle top-doc" open><summary class="hideme"><span>Expand description</span></summary><div class="docblock"><p>📚 <em>This module documents ICU4X constructor signatures.</em></p>
|
||
<p>One of the key differences between ICU4X and its parent projects, ICU4C and ICU4J, is in how
|
||
it deals with locale data.</p>
|
||
<p>In ICU4X, data can always be explicitly passed to any function that requires data.
|
||
This enables ICU4X to achieve the following value propositions:</p>
|
||
<ol>
|
||
<li>Configurable data sources (machine-readable data file, baked into code, JSON, etc).</li>
|
||
<li>Dynamic data loading at runtime (load data on demand).</li>
|
||
<li>Reduced overhead and code size (data is resolved locally at each call site).</li>
|
||
<li>Explicit support for multiple ICU4X instances sharing data.</li>
|
||
</ol>
|
||
<p>However, as manual data management can be tedious, ICU4X also has a <code>compiled_data</code>
|
||
default Cargo feature that includes data and makes ICU4X work out-of-the box.</p>
|
||
<p>Subsequently, there are 3 versions of all Rust ICU4X functions that use data:</p>
|
||
<ol>
|
||
<li><code>*</code></li>
|
||
<li><code>*_unstable</code></li>
|
||
<li><code>*_with_buffer_provider</code></li>
|
||
</ol>
|
||
<h2 id="which-constructor-should-i-use"><a class="doc-anchor" href="#which-constructor-should-i-use">§</a>Which constructor should I use?</h2><h3 id="when-to-use-"><a class="doc-anchor" href="#when-to-use-">§</a>When to use <code>*</code></h3>
|
||
<p>If you don’t want to customize data at runtime (i.e. if you don’t care about code size,
|
||
updating your data, etc.) you can use the <code>compiled_data</code> Cargo feature and don’t have to think
|
||
about where your data comes from.</p>
|
||
<p>These constructors are sometimes <code>const</code> functions, this way Rust can most effectively optimize
|
||
your usage of ICU4X.</p>
|
||
<h3 id="when-to-use-_unstable"><a class="doc-anchor" href="#when-to-use-_unstable">§</a>When to use <code>*_unstable</code></h3>
|
||
<p>Use this constructor if your data provider implements the <a href="../trait.DataProvider.html" title="trait icu_provider::DataProvider"><code>DataProvider</code></a> trait for all
|
||
data structs in <em>current and future</em> ICU4X versions. Examples:</p>
|
||
<ol>
|
||
<li><code>BakedDataProvider</code> generated for the specific ICU4X minor version</li>
|
||
<li>Anything with a <em>blanket</em> <a href="../trait.DataProvider.html" title="trait icu_provider::DataProvider"><code>DataProvider</code></a> impl</li>
|
||
</ol>
|
||
<p>Since the exact set of bounds may change at any time, including in minor SemVer releases,
|
||
it is the client’s responsibility to guarantee that the requirement is upheld.</p>
|
||
<h3 id="when-to-use-_with_buffer_provider"><a class="doc-anchor" href="#when-to-use-_with_buffer_provider">§</a>When to use <code>*_with_buffer_provider</code></h3>
|
||
<p>Use this constructor if your data originates as byte buffers that need to be deserialized.
|
||
All such providers should implement <a href="../buf/trait.BufferProvider.html" title="trait icu_provider::buf::BufferProvider"><code>BufferProvider</code></a>. Examples:</p>
|
||
<ol>
|
||
<li><a href="../../icu_provider_blob/struct.BlobDataProvider.html"><code>BlobDataProvider</code></a></li>
|
||
<li><a href="../../icu_provider_blob/struct.FsDataProvider.html"><code>FsDataProvider</code></a></li>
|
||
<li><a href="../../icu_provider_adapters/fork/struct.ForkByMarkerProvider.html"><code>ForkByMarkerProvider</code></a> between two providers implementing <a href="../buf/trait.BufferProvider.html" title="trait icu_provider::buf::BufferProvider"><code>BufferProvider</code></a></li>
|
||
</ol>
|
||
<p>Please note that you must enable the <code>serde</code> Cargo feature on each crate in which you use the
|
||
<code>*_with_buffer_provider</code> constructor.</p>
|
||
<h2 id="data-versioning-policy"><a class="doc-anchor" href="#data-versioning-policy">§</a>Data Versioning Policy</h2>
|
||
<p>The <code>*_with_buffer_provider</code> functions will succeed to compile and
|
||
run if given a data provider supporting all of the markers required for the object being
|
||
constructed, either the current or any previous version within the same SemVer major release.
|
||
For example, if a data file is built to support FooFormatter version 1.1, then FooFormatter
|
||
version 1.2 will be able to read the same data file. Likewise, backwards-compatible markers can
|
||
always be included by <code>icu_provider_export</code> to support older library versions.</p>
|
||
<p>The <code>*_unstable</code> functions are only guaranteed to work on data built for the exact same minor version
|
||
of ICU4X. The advantage of the <code>*_unstable</code> functions is that they result in the smallest code
|
||
size and allow for automatic data slicing when <code>BakedDataProvider</code> is used. However, the type
|
||
bounds of this function may change over time, breaking SemVer guarantees. These functions
|
||
should therefore only be used when you have full control over your data lifecycle at compile
|
||
time.</p>
|
||
<h2 id="data-providers-over-ffi"><a class="doc-anchor" href="#data-providers-over-ffi">§</a>Data Providers Over FFI</h2>
|
||
<p>Over FFI, there is only one data provider type: <a href="../../icu_capi/provider/ffi/struct.ICU4XDataProvider.html"><code>ICU4XDataProvider</code></a>. Internally, it is an
|
||
<code>enum</code> between<code>dyn </code><a href="../buf/trait.BufferProvider.html" title="trait icu_provider::buf::BufferProvider"><code>BufferProvider</code></a> and a unit compiled data variant.</p>
|
||
<p>To control for code size, there are two Cargo features, <code>compiled_data</code> and <code>buffer_provider</code>,
|
||
that enable the corresponding items in the enum.</p>
|
||
<p>In Rust ICU4X, a similar enum approach was not taken because:</p>
|
||
<ol>
|
||
<li>Feature-gating the enum branches gets complex across crates.</li>
|
||
<li>Without feature gating, users need to carry Serde code even if they’re not using it,
|
||
violating one of the core value propositions of ICU4X.</li>
|
||
<li>We could reduce the number of constructors from 4 to 2 but not to 1, so the educational
|
||
benefit is limited.</li>
|
||
</ol>
|
||
</div></details></section></div></main></body></html> |