vendor/intl-memoizer-0.5.2/src/lib.rs - toolchain/rustc - Git at Google

 //! This crate contains a memoizer for internationalization formatters. Often it is
 //! expensive (in terms of performance and memory) to construct a formatter, but then
 //! relatively cheap to run the format operation.
 //!
 //! The [IntlMemoizer] is the main struct that creates a per-locale [IntlLangMemoizer].

 use std::cell::RefCell;
 use std::collections::hash_map::Entry;
 use std::collections::HashMap;
 use std::hash::Hash;
 use std::rc::{Rc, Weak};
 use unic_langid::LanguageIdentifier;

 pub mod concurrent;

 /// The trait that needs to be implemented for each intl formatter that needs to be
 /// memoized.
 pub trait Memoizable {
     /// Type of the arguments that are used to construct the formatter.
     type Args: 'static + Eq + Hash + Clone;

     /// Type of any errors that can occur during the construction process.
     type Error;

     /// Construct a formatter. This maps the [`Self::Args`] type to the actual constructor
     /// for an intl formatter.
     fn construct(lang: LanguageIdentifier, args: Self::Args) -> Result<Self, Self::Error>
     where
         Self: std::marker::Sized;
 }

 /// The [`IntlLangMemoizer`] can memoize multiple constructed internationalization
 /// formatters, and their configuration for a single locale. For instance, given "en-US",
 /// a memorizer could retain 3 DateTimeFormat instances, and a PluralRules.
 ///
 /// For memoizing with multiple locales, see [`IntlMemoizer`].
 ///
 /// # Example
 ///
 /// The code example does the following steps:
 ///
 /// 1. Create a static counter
 /// 2. Create an `ExampleFormatter`
 /// 3. Implement [`Memoizable`] for `ExampleFormatter`.
 /// 4. Use `IntlLangMemoizer::with_try_get` to run `ExampleFormatter::format`
 /// 5. Demonstrate the memoization using the static counter
 ///
 /// ```
 /// use intl_memoizer::{IntlLangMemoizer, Memoizable};
 /// use unic_langid::LanguageIdentifier;
 ///
 /// // Create a static counter so that we can demonstrate the side effects of when
 /// // the memoizer re-constructs an API.
 ///
 /// static mut INTL_EXAMPLE_CONSTRUCTS: u32 = 0;
 /// fn increment_constructs() {
 ///     unsafe {
 ///         INTL_EXAMPLE_CONSTRUCTS += 1;
 ///     }
 /// }
 ///
 /// fn get_constructs_count() -> u32 {
 ///     unsafe { INTL_EXAMPLE_CONSTRUCTS }
 /// }
 ///
 /// /// Create an example formatter, that doesn't really do anything useful. In a real
 /// /// implementation, this could be a PluralRules or DateTimeFormat struct.
 /// struct ExampleFormatter {
 ///     lang: LanguageIdentifier,
 ///     /// This is here to show how to initiate the API with an argument.
 ///     prefix: String,
 /// }
 ///
 /// impl ExampleFormatter {
 ///     /// Perform an example format by printing information about the formatter
 ///     /// configuration, and the arguments passed into the individual format operation.
 ///     fn format(&self, example_string: &str) -> String {
 ///         format!(
 ///             "{} lang({}) string({})",
 ///             self.prefix, self.lang, example_string
 ///         )
 ///     }
 /// }
 ///
 /// /// Multiple classes of structs may be add1ed to the memoizer, with the restriction
 /// /// that they must implement the `Memoizable` trait.
 /// impl Memoizable for ExampleFormatter {
 ///     /// The arguments will be passed into the constructor. Here a single `String`
 ///     /// will be used as a prefix to the formatting operation.
 ///     type Args = (String,);
 ///
 ///     /// If the constructor is fallible, than errors can be described here.
 ///     type Error = ();
 ///
 ///     /// This function wires together the `Args` and `Error` type to construct
 ///     /// the intl API. In our example, there is
 ///     fn construct(lang: LanguageIdentifier, args: Self::Args) -> Result<Self, Self::Error> {
 ///         // Keep track for example purposes that this was constructed.
 ///         increment_constructs();
 ///
 ///         Ok(Self {
 ///             lang,
 ///             prefix: args.0,
 ///         })
 ///     }
 /// }
 ///
 /// // The following demonstrates how these structs are actually used with the memoizer.
 ///
 /// // Construct a new memoizer.
 /// let lang = "en-US".parse().expect("Failed to parse.");
 /// let memoizer = IntlLangMemoizer::new(lang);
 ///
 /// // These arguments are passed into the constructor for `ExampleFormatter`.
 /// let construct_args = (String::from("prefix:"),);
 /// let message1 = "The format operation will run";
 /// let message2 = "ExampleFormatter will be re-used, when a second format is run";
 ///
 /// // Run `IntlLangMemoizer::with_try_get`. The name of the method means "with" an
 /// // intl formatter, "try and get" the result. See the method documentation for
 /// // more details.
 ///
 /// let result1 = memoizer
 ///     .with_try_get::<ExampleFormatter, _, _>(construct_args.clone(), |intl_example| {
 ///         intl_example.format(message1)
 ///     });
 ///
 /// // The memoized instance of `ExampleFormatter` will be re-used.
 /// let result2 = memoizer
 ///     .with_try_get::<ExampleFormatter, _, _>(construct_args.clone(), |intl_example| {
 ///         intl_example.format(message2)
 ///     });
 ///
 /// assert_eq!(
 ///     result1.unwrap(),
 ///     "prefix: lang(en-US) string(The format operation will run)"
 /// );
 /// assert_eq!(
 ///     result2.unwrap(),
 ///     "prefix: lang(en-US) string(ExampleFormatter will be re-used, when a second format is run)"
 /// );
 /// assert_eq!(
 ///     get_constructs_count(),
 ///     1,
 ///     "The constructor was only run once."
 /// );
 ///
 /// let construct_args = (String::from("re-init:"),);
 ///
 /// // Since the constructor args changed, `ExampleFormatter` will be re-constructed.
 /// let result1 = memoizer
 ///     .with_try_get::<ExampleFormatter, _, _>(construct_args.clone(), |intl_example| {
 ///         intl_example.format(message1)
 ///     });
 ///
 /// // The memoized instance of `ExampleFormatter` will be re-used.
 /// let result2 = memoizer
 ///     .with_try_get::<ExampleFormatter, _, _>(construct_args.clone(), |intl_example| {
 ///         intl_example.format(message2)
 ///     });
 ///
 /// assert_eq!(
 ///     result1.unwrap(),
 ///     "re-init: lang(en-US) string(The format operation will run)"
 /// );
 /// assert_eq!(
 ///     result2.unwrap(),
 ///     "re-init: lang(en-US) string(ExampleFormatter will be re-used, when a second format is run)"
 /// );
 /// assert_eq!(
 ///     get_constructs_count(),
 ///     2,
 ///     "The constructor was invalidated and ran again."
 /// );
 /// ```
 #[derive(Debug)]
 pub struct IntlLangMemoizer {
     lang: LanguageIdentifier,
     map: RefCell<type_map::TypeMap>,
 }

 impl IntlLangMemoizer {
     /// Create a new [`IntlLangMemoizer`] that is unique to a specific
     /// [`LanguageIdentifier`]
     pub fn new(lang: LanguageIdentifier) -> Self {
         Self {
             lang,
             map: RefCell::new(type_map::TypeMap::new()),
         }
     }

     /// `with_try_get` means `with` an internationalization formatter, `try` and `get` a result.
     /// The (potentially expensive) constructor for the formatter (such as PluralRules or
     /// DateTimeFormat) will be memoized and only constructed once for a given
     /// `construct_args`. After that the format operation can be run multiple times
     /// inexpensively.
     ///
     /// The first generic argument `I` must be provided, but the `R` and `U` will be
     /// deduced by the typing of the `callback` argument that is provided.
     ///
     /// I - The memoizable intl object, for instance a `PluralRules` instance. This
     ///     must implement the Memoizable trait.
     ///
     /// R - The return result from the callback `U`.
     ///
     /// U - The callback function. Takes an instance of `I` as the first parameter and
     ///     returns the R value.
     pub fn with_try_get<I, R, U>(&self, construct_args: I::Args, callback: U) -> Result<R, I::Error>
     where
         Self: Sized,
         I: Memoizable + 'static,
         U: FnOnce(&I) -> R,
     {
         let mut map = self
             .map
             .try_borrow_mut()
             .expect("Cannot use memoizer reentrantly");
         let cache = map
             .entry::<HashMap<I::Args, I>>()
             .or_insert_with(HashMap::new);

         let e = match cache.entry(construct_args.clone()) {
             Entry::Occupied(entry) => entry.into_mut(),
             Entry::Vacant(entry) => {
                 let val = I::construct(self.lang.clone(), construct_args)?;
                 entry.insert(val)
             }
         };
         Ok(callback(e))
     }
 }

 /// [`IntlMemoizer`] is designed to handle lazily-initialized references to
 /// internationalization formatters.
 ///
 /// Constructing a new formatter is often expensive in terms of memory and performance,
 /// and the instance is often read-only during its lifetime. The format operations in
 /// comparison are relatively cheap.
 ///
 /// Because of this relationship, it can be helpful to memoize the constructors, and
 /// re-use them across multiple format operations. This strategy is used where all
 /// instances of intl APIs such as `PluralRules`, `DateTimeFormat` etc. are memoized
 /// between all `FluentBundle` instances.
 ///
 /// # Example
 ///
 /// For a more complete example of the memoization, see the [`IntlLangMemoizer`] documentation.
 /// This example provides a higher-level overview.
 ///
 /// ```
 /// # use intl_memoizer::{IntlMemoizer, IntlLangMemoizer, Memoizable};
 /// # use unic_langid::LanguageIdentifier;
 /// # use std::rc::Rc;
 /// #
 /// # struct ExampleFormatter {
 /// #     lang: LanguageIdentifier,
 /// #     prefix: String,
 /// # }
 /// #
 /// # impl ExampleFormatter {
 /// #     fn format(&self, example_string: &str) -> String {
 /// #         format!(
 /// #             "{} lang({}) string({})",
 /// #             self.prefix, self.lang, example_string
 /// #         )
 /// #     }
 /// # }
 /// #
 /// # impl Memoizable for ExampleFormatter {
 /// #     type Args = (String,);
 /// #     type Error = ();
 /// #     fn construct(lang: LanguageIdentifier, args: Self::Args) -> Result<Self, Self::Error> {
 /// #         Ok(Self {
 /// #             lang,
 /// #             prefix: args.0,
 /// #         })
 /// #     }
 /// # }
 /// #
 /// let mut memoizer = IntlMemoizer::default();
 ///
 /// // The memoziation happens per-locale.
 /// let en_us = "en-US".parse().expect("Failed to parse.");
 /// let en_us_memoizer: Rc<IntlLangMemoizer> = memoizer.get_for_lang(en_us);
 ///
 /// // These arguments are passed into the constructor for `ExampleFormatter`. The
 /// // construct_args will be used for determining the memoization, but the message
 /// // can be different and re-use the constructed instance.
 /// let construct_args = (String::from("prefix:"),);
 /// let message = "The format operation will run";
 ///
 /// // Use the `ExampleFormatter` from the `IntlLangMemoizer` example. It returns a
 /// // string that demonstrates the configuration of the formatter. This step will
 /// // construct a new formatter if needed, and run the format operation.
 /// //
 /// // See `IntlLangMemoizer` for more details on this step.
 /// let en_us_result = en_us_memoizer
 ///     .with_try_get::<ExampleFormatter, _, _>(construct_args.clone(), |intl_example| {
 ///         intl_example.format(message)
 ///     });
 ///
 /// // The example formatter constructs a string with diagnostic information about
 /// // the configuration.
 /// assert_eq!(
 ///     en_us_result.unwrap(),
 ///     "prefix: lang(en-US) string(The format operation will run)"
 /// );
 ///
 /// // The process can be repeated for a new locale.
 ///
 /// let de_de = "de-DE".parse().expect("Failed to parse.");
 /// let de_de_memoizer: Rc<IntlLangMemoizer> = memoizer.get_for_lang(de_de);
 ///
 /// let de_de_result = de_de_memoizer
 ///     .with_try_get::<ExampleFormatter, _, _>(construct_args.clone(), |intl_example| {
 ///         intl_example.format(message)
 ///     });
 ///
 /// assert_eq!(
 ///     de_de_result.unwrap(),
 ///     "prefix: lang(de-DE) string(The format operation will run)"
 /// );
 /// ```
 #[derive(Default)]
 pub struct IntlMemoizer {
     map: HashMap<LanguageIdentifier, Weak<IntlLangMemoizer>>,
 }

 impl IntlMemoizer {
     /// Get a [`IntlLangMemoizer`] for a given language. If one does not exist for
     /// a locale, it will be constructed and weakly retained. See [`IntlLangMemoizer`]
     /// for more detailed documentation how to use it.
     pub fn get_for_lang(&mut self, lang: LanguageIdentifier) -> Rc<IntlLangMemoizer> {
         match self.map.entry(lang.clone()) {
             Entry::Vacant(empty) => {
                 let entry = Rc::new(IntlLangMemoizer::new(lang));
                 empty.insert(Rc::downgrade(&entry));
                 entry
             }
             Entry::Occupied(mut entry) => {
                 if let Some(entry) = entry.get().upgrade() {
                     entry
                 } else {
                     let e = Rc::new(IntlLangMemoizer::new(lang));
                     entry.insert(Rc::downgrade(&e));
                     e
                 }
             }
         }
     }
 }

 #[cfg(test)]
 mod tests {
     use super::*;
     use fluent_langneg::{negotiate_languages, NegotiationStrategy};
     use intl_pluralrules::{PluralCategory, PluralRuleType, PluralRules as IntlPluralRules};
     use std::{sync::Arc, thread};

     struct PluralRules(pub IntlPluralRules);

     impl PluralRules {
         pub fn new(
             lang: LanguageIdentifier,
             pr_type: PluralRuleType,
         ) -> Result<Self, &'static str> {
             let default_lang: LanguageIdentifier = "en".parse().unwrap();
             let pr_lang = negotiate_languages(
                 &[lang],
                 &IntlPluralRules::get_locales(pr_type),
                 Some(&default_lang),
                 NegotiationStrategy::Lookup,
             )[0]
             .clone();

             Ok(Self(IntlPluralRules::create(pr_lang, pr_type)?))
         }
     }

     impl Memoizable for PluralRules {
         type Args = (PluralRuleType,);
         type Error = &'static str;
         fn construct(lang: LanguageIdentifier, args: Self::Args) -> Result<Self, Self::Error> {
             Self::new(lang, args.0)
         }
     }

     #[test]
     fn test_single_thread() {
         let lang: LanguageIdentifier = "en".parse().unwrap();

         let mut memoizer = IntlMemoizer::default();
         {
             let en_memoizer = memoizer.get_for_lang(lang.clone());

             let result = en_memoizer
                 .with_try_get::<PluralRules, _, _>((PluralRuleType::CARDINAL,), |cb| cb.0.select(5))
                 .unwrap();
             assert_eq!(result, Ok(PluralCategory::OTHER));
         }

         {
             let en_memoizer = memoizer.get_for_lang(lang);

             let result = en_memoizer
                 .with_try_get::<PluralRules, _, _>((PluralRuleType::CARDINAL,), |cb| cb.0.select(5))
                 .unwrap();
             assert_eq!(result, Ok(PluralCategory::OTHER));
         }
     }

     #[test]
     fn test_concurrent() {
         let lang: LanguageIdentifier = "en".parse().unwrap();
         let memoizer = Arc::new(concurrent::IntlLangMemoizer::new(lang));
         let mut threads = vec![];

         // Spawn four threads that all use the PluralRules.
         for _ in 0..4 {
             let memoizer = Arc::clone(&memoizer);
             threads.push(thread::spawn(move || {
                 memoizer
                     .with_try_get::<PluralRules, _, _>((PluralRuleType::CARDINAL,), |cb| {
                         cb.0.select(5)
                     })
                     .expect("Failed to get a PluralRules result.")
             }));
         }

         for thread in threads.drain(..) {
             let result = thread.join().expect("Failed to join thread.");
             assert_eq!(result, Ok(PluralCategory::OTHER));
         }
     }
 }
	//! This crate contains a memoizer for internationalization formatters. Often it is
	//! expensive (in terms of performance and memory) to construct a formatter, but then
	//! relatively cheap to run the format operation.
	//!
	//! The [IntlMemoizer] is the main struct that creates a per-locale [IntlLangMemoizer].

	use std::cell::RefCell;
	use std::collections::hash_map::Entry;
	use std::collections::HashMap;
	use std::hash::Hash;
	use std::rc::{Rc, Weak};
	use unic_langid::LanguageIdentifier;

	pub mod concurrent;

	/// The trait that needs to be implemented for each intl formatter that needs to be
	/// memoized.
	pub trait Memoizable {
	/// Type of the arguments that are used to construct the formatter.
	type Args: 'static + Eq + Hash + Clone;

	/// Type of any errors that can occur during the construction process.
	type Error;

	/// Construct a formatter. This maps the [`Self::Args`] type to the actual constructor
	/// for an intl formatter.
	fn construct(lang: LanguageIdentifier, args: Self::Args) -> Result<Self, Self::Error>
	where
	Self: std::marker::Sized;
	}

	/// The [`IntlLangMemoizer`] can memoize multiple constructed internationalization
	/// formatters, and their configuration for a single locale. For instance, given "en-US",
	/// a memorizer could retain 3 DateTimeFormat instances, and a PluralRules.
	///
	/// For memoizing with multiple locales, see [`IntlMemoizer`].
	///
	/// # Example
	///
	/// The code example does the following steps:
	///
	/// 1. Create a static counter
	/// 2. Create an `ExampleFormatter`
	/// 3. Implement [`Memoizable`] for `ExampleFormatter`.
	/// 4. Use `IntlLangMemoizer::with_try_get` to run `ExampleFormatter::format`
	/// 5. Demonstrate the memoization using the static counter
	///
	/// ```
	/// use intl_memoizer::{IntlLangMemoizer, Memoizable};
	/// use unic_langid::LanguageIdentifier;
	///
	/// // Create a static counter so that we can demonstrate the side effects of when
	/// // the memoizer re-constructs an API.
	///
	/// static mut INTL_EXAMPLE_CONSTRUCTS: u32 = 0;
	/// fn increment_constructs() {
	/// unsafe {
	/// INTL_EXAMPLE_CONSTRUCTS += 1;
	/// }
	/// }
	///
	/// fn get_constructs_count() -> u32 {
	/// unsafe { INTL_EXAMPLE_CONSTRUCTS }
	/// }
	///
	/// /// Create an example formatter, that doesn't really do anything useful. In a real
	/// /// implementation, this could be a PluralRules or DateTimeFormat struct.
	/// struct ExampleFormatter {
	/// lang: LanguageIdentifier,
	/// /// This is here to show how to initiate the API with an argument.
	/// prefix: String,
	/// }
	///
	/// impl ExampleFormatter {
	/// /// Perform an example format by printing information about the formatter
	/// /// configuration, and the arguments passed into the individual format operation.
	/// fn format(&self, example_string: &str) -> String {
	/// format!(
	/// "{} lang({}) string({})",
	/// self.prefix, self.lang, example_string
	/// )
	/// }
	/// }
	///
	/// /// Multiple classes of structs may be add1ed to the memoizer, with the restriction
	/// /// that they must implement the `Memoizable` trait.
	/// impl Memoizable for ExampleFormatter {
	/// /// The arguments will be passed into the constructor. Here a single `String`
	/// /// will be used as a prefix to the formatting operation.
	/// type Args = (String,);
	///
	/// /// If the constructor is fallible, than errors can be described here.
	/// type Error = ();
	///
	/// /// This function wires together the `Args` and `Error` type to construct
	/// /// the intl API. In our example, there is
	/// fn construct(lang: LanguageIdentifier, args: Self::Args) -> Result<Self, Self::Error> {
	/// // Keep track for example purposes that this was constructed.
	/// increment_constructs();
	///
	/// Ok(Self {
	/// lang,
	/// prefix: args.0,
	/// })
	/// }
	/// }
	///
	/// // The following demonstrates how these structs are actually used with the memoizer.
	///
	/// // Construct a new memoizer.
	/// let lang = "en-US".parse().expect("Failed to parse.");
	/// let memoizer = IntlLangMemoizer::new(lang);
	///
	/// // These arguments are passed into the constructor for `ExampleFormatter`.
	/// let construct_args = (String::from("prefix:"),);
	/// let message1 = "The format operation will run";
	/// let message2 = "ExampleFormatter will be re-used, when a second format is run";
	///
	/// // Run `IntlLangMemoizer::with_try_get`. The name of the method means "with" an
	/// // intl formatter, "try and get" the result. See the method documentation for
	/// // more details.
	///
	/// let result1 = memoizer
	/// .with_try_get::<ExampleFormatter, _, _>(construct_args.clone(), \|intl_example\| {
	/// intl_example.format(message1)
	/// });
	///
	/// // The memoized instance of `ExampleFormatter` will be re-used.
	/// let result2 = memoizer
	/// .with_try_get::<ExampleFormatter, _, _>(construct_args.clone(), \|intl_example\| {
	/// intl_example.format(message2)
	/// });
	///
	/// assert_eq!(
	/// result1.unwrap(),
	/// "prefix: lang(en-US) string(The format operation will run)"
	/// );
	/// assert_eq!(
	/// result2.unwrap(),
	/// "prefix: lang(en-US) string(ExampleFormatter will be re-used, when a second format is run)"
	/// );
	/// assert_eq!(
	/// get_constructs_count(),
	/// 1,
	/// "The constructor was only run once."
	/// );
	///
	/// let construct_args = (String::from("re-init:"),);
	///
	/// // Since the constructor args changed, `ExampleFormatter` will be re-constructed.
	/// let result1 = memoizer
	/// .with_try_get::<ExampleFormatter, _, _>(construct_args.clone(), \|intl_example\| {
	/// intl_example.format(message1)
	/// });
	///
	/// // The memoized instance of `ExampleFormatter` will be re-used.
	/// let result2 = memoizer
	/// .with_try_get::<ExampleFormatter, _, _>(construct_args.clone(), \|intl_example\| {
	/// intl_example.format(message2)
	/// });
	///
	/// assert_eq!(
	/// result1.unwrap(),
	/// "re-init: lang(en-US) string(The format operation will run)"
	/// );
	/// assert_eq!(
	/// result2.unwrap(),
	/// "re-init: lang(en-US) string(ExampleFormatter will be re-used, when a second format is run)"
	/// );
	/// assert_eq!(
	/// get_constructs_count(),
	/// 2,
	/// "The constructor was invalidated and ran again."
	/// );
	/// ```
	#[derive(Debug)]
	pub struct IntlLangMemoizer {
	lang: LanguageIdentifier,
	map: RefCell<type_map::TypeMap>,
	}

	impl IntlLangMemoizer {
	/// Create a new [`IntlLangMemoizer`] that is unique to a specific
	/// [`LanguageIdentifier`]
	pub fn new(lang: LanguageIdentifier) -> Self {
	Self {
	lang,
	map: RefCell::new(type_map::TypeMap::new()),
	}
	}

	/// `with_try_get` means `with` an internationalization formatter, `try` and `get` a result.
	/// The (potentially expensive) constructor for the formatter (such as PluralRules or
	/// DateTimeFormat) will be memoized and only constructed once for a given
	/// `construct_args`. After that the format operation can be run multiple times
	/// inexpensively.
	///
	/// The first generic argument `I` must be provided, but the `R` and `U` will be
	/// deduced by the typing of the `callback` argument that is provided.
	///
	/// I - The memoizable intl object, for instance a `PluralRules` instance. This
	/// must implement the Memoizable trait.
	///
	/// R - The return result from the callback `U`.
	///
	/// U - The callback function. Takes an instance of `I` as the first parameter and
	/// returns the R value.
	pub fn with_try_get<I, R, U>(&self, construct_args: I::Args, callback: U) -> Result<R, I::Error>
	where
	Self: Sized,
	I: Memoizable + 'static,
	U: FnOnce(&I) -> R,
	{
	let mut map = self
	.map
	.try_borrow_mut()
	.expect("Cannot use memoizer reentrantly");
	let cache = map
	.entry::<HashMap<I::Args, I>>()
	.or_insert_with(HashMap::new);

	let e = match cache.entry(construct_args.clone()) {
	Entry::Occupied(entry) => entry.into_mut(),
	Entry::Vacant(entry) => {
	let val = I::construct(self.lang.clone(), construct_args)?;
	entry.insert(val)
	}
	};
	Ok(callback(e))
	}
	}

	/// [`IntlMemoizer`] is designed to handle lazily-initialized references to
	/// internationalization formatters.
	///
	/// Constructing a new formatter is often expensive in terms of memory and performance,
	/// and the instance is often read-only during its lifetime. The format operations in
	/// comparison are relatively cheap.
	///
	/// Because of this relationship, it can be helpful to memoize the constructors, and
	/// re-use them across multiple format operations. This strategy is used where all
	/// instances of intl APIs such as `PluralRules`, `DateTimeFormat` etc. are memoized
	/// between all `FluentBundle` instances.
	///
	/// # Example
	///
	/// For a more complete example of the memoization, see the [`IntlLangMemoizer`] documentation.
	/// This example provides a higher-level overview.
	///
	/// ```
	/// # use intl_memoizer::{IntlMemoizer, IntlLangMemoizer, Memoizable};
	/// # use unic_langid::LanguageIdentifier;
	/// # use std::rc::Rc;
	/// #
	/// # struct ExampleFormatter {
	/// # lang: LanguageIdentifier,
	/// # prefix: String,
	/// # }
	/// #
	/// # impl ExampleFormatter {
	/// # fn format(&self, example_string: &str) -> String {
	/// # format!(
	/// # "{} lang({}) string({})",
	/// # self.prefix, self.lang, example_string
	/// # )
	/// # }
	/// # }
	/// #
	/// # impl Memoizable for ExampleFormatter {
	/// # type Args = (String,);
	/// # type Error = ();
	/// # fn construct(lang: LanguageIdentifier, args: Self::Args) -> Result<Self, Self::Error> {
	/// # Ok(Self {
	/// # lang,
	/// # prefix: args.0,
	/// # })
	/// # }
	/// # }
	/// #
	/// let mut memoizer = IntlMemoizer::default();
	///
	/// // The memoziation happens per-locale.
	/// let en_us = "en-US".parse().expect("Failed to parse.");
	/// let en_us_memoizer: Rc<IntlLangMemoizer> = memoizer.get_for_lang(en_us);
	///
	/// // These arguments are passed into the constructor for `ExampleFormatter`. The
	/// // construct_args will be used for determining the memoization, but the message
	/// // can be different and re-use the constructed instance.
	/// let construct_args = (String::from("prefix:"),);
	/// let message = "The format operation will run";
	///
	/// // Use the `ExampleFormatter` from the `IntlLangMemoizer` example. It returns a
	/// // string that demonstrates the configuration of the formatter. This step will
	/// // construct a new formatter if needed, and run the format operation.
	/// //
	/// // See `IntlLangMemoizer` for more details on this step.
	/// let en_us_result = en_us_memoizer
	/// .with_try_get::<ExampleFormatter, _, _>(construct_args.clone(), \|intl_example\| {
	/// intl_example.format(message)
	/// });
	///
	/// // The example formatter constructs a string with diagnostic information about
	/// // the configuration.
	/// assert_eq!(
	/// en_us_result.unwrap(),
	/// "prefix: lang(en-US) string(The format operation will run)"
	/// );
	///
	/// // The process can be repeated for a new locale.
	///
	/// let de_de = "de-DE".parse().expect("Failed to parse.");
	/// let de_de_memoizer: Rc<IntlLangMemoizer> = memoizer.get_for_lang(de_de);
	///
	/// let de_de_result = de_de_memoizer
	/// .with_try_get::<ExampleFormatter, _, _>(construct_args.clone(), \|intl_example\| {
	/// intl_example.format(message)
	/// });
	///
	/// assert_eq!(
	/// de_de_result.unwrap(),
	/// "prefix: lang(de-DE) string(The format operation will run)"
	/// );
	/// ```
	#[derive(Default)]
	pub struct IntlMemoizer {
	map: HashMap<LanguageIdentifier, Weak<IntlLangMemoizer>>,
	}

	impl IntlMemoizer {
	/// Get a [`IntlLangMemoizer`] for a given language. If one does not exist for
	/// a locale, it will be constructed and weakly retained. See [`IntlLangMemoizer`]
	/// for more detailed documentation how to use it.
	pub fn get_for_lang(&mut self, lang: LanguageIdentifier) -> Rc<IntlLangMemoizer> {
	match self.map.entry(lang.clone()) {
	Entry::Vacant(empty) => {
	let entry = Rc::new(IntlLangMemoizer::new(lang));
	empty.insert(Rc::downgrade(&entry));
	entry
	}
	Entry::Occupied(mut entry) => {
	if let Some(entry) = entry.get().upgrade() {
	entry
	} else {
	let e = Rc::new(IntlLangMemoizer::new(lang));
	entry.insert(Rc::downgrade(&e));
	e
	}
	}
	}
	}
	}

	#[cfg(test)]
	mod tests {
	use super::*;
	use fluent_langneg::{negotiate_languages, NegotiationStrategy};
	use intl_pluralrules::{PluralCategory, PluralRuleType, PluralRules as IntlPluralRules};
	use std::{sync::Arc, thread};

	struct PluralRules(pub IntlPluralRules);

	impl PluralRules {
	pub fn new(
	lang: LanguageIdentifier,
	pr_type: PluralRuleType,
	) -> Result<Self, &'static str> {
	let default_lang: LanguageIdentifier = "en".parse().unwrap();
	let pr_lang = negotiate_languages(
	&[lang],
	&IntlPluralRules::get_locales(pr_type),
	Some(&default_lang),
	NegotiationStrategy::Lookup,
	)[0]
	.clone();

	Ok(Self(IntlPluralRules::create(pr_lang, pr_type)?))
	}
	}

	impl Memoizable for PluralRules {
	type Args = (PluralRuleType,);
	type Error = &'static str;
	fn construct(lang: LanguageIdentifier, args: Self::Args) -> Result<Self, Self::Error> {
	Self::new(lang, args.0)
	}
	}

	#[test]
	fn test_single_thread() {
	let lang: LanguageIdentifier = "en".parse().unwrap();

	let mut memoizer = IntlMemoizer::default();
	{
	let en_memoizer = memoizer.get_for_lang(lang.clone());

	let result = en_memoizer
	.with_try_get::<PluralRules, _, _>((PluralRuleType::CARDINAL,), \|cb\| cb.0.select(5))
	.unwrap();
	assert_eq!(result, Ok(PluralCategory::OTHER));
	}

	{
	let en_memoizer = memoizer.get_for_lang(lang);

	let result = en_memoizer
	.with_try_get::<PluralRules, _, _>((PluralRuleType::CARDINAL,), \|cb\| cb.0.select(5))
	.unwrap();
	assert_eq!(result, Ok(PluralCategory::OTHER));
	}
	}

	#[test]
	fn test_concurrent() {
	let lang: LanguageIdentifier = "en".parse().unwrap();
	let memoizer = Arc::new(concurrent::IntlLangMemoizer::new(lang));
	let mut threads = vec![];

	// Spawn four threads that all use the PluralRules.
	for _ in 0..4 {
	let memoizer = Arc::clone(&memoizer);
	threads.push(thread::spawn(move \|\| {
	memoizer
	.with_try_get::<PluralRules, _, _>((PluralRuleType::CARDINAL,), \|cb\| {
	cb.0.select(5)
	})
	.expect("Failed to get a PluralRules result.")
	}));
	}

	for thread in threads.drain(..) {
	let result = thread.join().expect("Failed to join thread.");
	assert_eq!(result, Ok(PluralCategory::OTHER));
	}
	}
	}