locale_match/lib.rs
1// locale-match is a small library for matching user's preferred locales to available locales.
2// Copyright (C) © 2024 Petr Aleksandrovich Sabanov
3//
4// This program is free software: you can redistribute it and/or modify
5// it under the terms of the GNU Lesser General Public License as published by
6// the Free Software Foundation, either version 3 of the License, or
7// (at your option) any later version.
8//
9// This program is distributed in the hope that it will be useful,
10// but WITHOUT ANY WARRANTY; without even the implied warranty of
11// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12// GNU Lesser General Public License for more details.
13//
14// You should have received a copy of the GNU Lesser General Public License
15// along with this program. If not, see <https://www.gnu.org/licenses/>.
16
17//! A small library for selecting the best match for user's preferred locales from available locales.
18//!
19//! The library consists of two modules:
20//! * [`bcp47`] — for matching locales in the [BCP 47](https://www.ietf.org/rfc/bcp/bcp47.html) format.
21//! * [`posix`] — for matching locales in the [POSIX](https://pubs.opengroup.org/onlinepubs/9799919799/basedefs/V1_chap08.html) format.
22//!
23//! Both modules provide the `best_matching_locale` function.
24//!
25//! ## Examples
26//!
27//! ### BCP 47
28//!
29//! ```
30//! use locale_match::bcp47::best_matching_locale;
31//!
32//! let available_locales = ["en-US", "ru-BY"];
33//! let user_locales = ["ru-RU", "ru", "en-US", "en"];
34//!
35//! let best_match = best_matching_locale(available_locales, user_locales);
36//!
37//! assert_eq!(best_match, Some("ru-BY"));
38//! ```
39//!
40//! ### POSIX
41//!
42//! ```
43//! use locale_match::posix::best_matching_locale;
44//!
45//! let available_locales = ["en_US.UTF-8", "ru_BY.UTF-8"];
46//! let user_locales = ["ru_RU.UTF-8", "ru", "en_US.UTF-8", "en"];
47//!
48//! let best_match = best_matching_locale(available_locales, user_locales);
49//!
50//! assert_eq!(best_match, Some("ru_BY.UTF-8"));
51//! ```
52
53#[cfg(feature = "bcp47")]
54pub mod bcp47;
55
56#[cfg(feature = "posix")]
57pub mod posix;