Expose BCP-47 locale variant APIs over FFI (unicode-org#7519)

This PR adds FFI support for accessing and mutating BCP-47 locale
variants so that non-Rust consumers (C/C++/JS/Dart) can work with
variant subtags in a safe and consistent way.
It exposes a small and focused set of Locale APIs to query, add, remove,
and clear variants. Mutation operations are implemented by operating on
a temporary collection, followed by sorting and deduplication before
reconstructing the internal representation, ensuring canonical BCP-47
ordering is preserved.
The change is intentionally scoped only to locale variants and does not
alter existing Locale semantics. Unit tests are included to cover
add/remove behavior, duplicate handling, canonical sorting, invalid
variant input, and bounds checking.
This work is intended to improve feature parity for FFI consumers while
keeping the API surface minimal and maintainable.

Closes unicode-org#6671.

Co-authored-by: Robert Bastian <4706271+robertbastian@users.noreply.github.com>

Author: afrdbaig7

components/locale_core/src/subtags/variants.rs

@@ -119,6 +119,58 @@ impl Variants {
         self.0.is_empty()
     }
 
+    /// Adds a variant to the list, maintaining sorted order.
+    ///
+    /// Returns `true` if the variant was added, `false` if it was already present.
+    ///
+    /// ✨ *Enabled with the `alloc` Cargo feature.*
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use icu::locale::subtags::{variant, Variants};
+    ///
+    /// let mut variants = Variants::new();
+    /// assert!(variants.push(variant!("posix")));
+    /// assert!(!variants.push(variant!("posix"))); // Already present
+    /// assert!(variants.push(variant!("macos")));
+    /// assert_eq!(variants.to_string(), "macos-posix");
+    /// ```
+    #[cfg(feature = "alloc")]
+    pub fn push(&mut self, variant: Variant) -> bool {
+        match self.binary_search(&variant) {
+            Ok(_) => false, // Already present
+            Err(i) => {
+                self.0.insert(i, variant);
+                true
+            }
+        }
+    }
+
+    /// Removes a variant from the list.
+    ///
+    /// Returns `true` if the variant was removed, `false` if it was not present.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use icu::locale::subtags::{variant, Variants};
+    ///
+    /// let mut variants = Variants::from_variant(variant!("posix"));
+    /// assert!(variants.remove(&variant!("posix")));
+    /// assert!(!variants.remove(&variant!("posix"))); // Already removed
+    /// assert!(variants.is_empty());
+    /// ```
+    pub fn remove(&mut self, variant: &Variant) -> bool {
+        match self.binary_search(variant) {
+            Ok(i) => {
+                self.0.remove(i);
+                true
+            }
+            Err(_) => false,
+        }
+    }
+
     pub(crate) fn for_each_subtag_str<E, F>(&self, f: &mut F) -> Result<(), E>
     where
         F: FnMut(&str) -> Result<(), E>,

examples/cpp/locale.cpp

@@ -105,5 +105,60 @@ int main() {
     return 1;
   }
 
+  // --- Variant Tests ---
+  locale = Locale::from_string("en-US-valencia").ok().value();
+  if (locale->variant_count() != 1) {
+    std::cout << "Expected 1 variant, got " << locale->variant_count() << std::endl;
+    return 1;
+  }
+  if (!locale->has_variant("valencia")) {
+    std::cout << "Expected locale to have 'valencia' variant" << std::endl;
+    return 1;
+  }
+
+  // Add a variant (returns Result<bool, Error>)
+  auto added = locale->add_variant("posix").ok().value();
+  if (!added) {
+    std::cout << "Expected add_variant to return true for new variant" << std::endl;
+    return 1;
+  }
+  if (locale->variant_count() != 2) {
+    std::cout << "After add, expected 2 variants, got " << locale->variant_count() << std::endl;
+    return 1;
+  }
+
+  // Add duplicate (should return false)
+  auto addedDup = locale->add_variant("posix").ok().value();
+  if (addedDup) {
+    std::cout << "Expected add_variant to return false for duplicate" << std::endl;
+    return 1;
+  }
+
+  // Remove a variant (returns bool)
+  auto removed = locale->remove_variant("posix");
+  if (!removed) {
+    std::cout << "Expected remove_variant to return true" << std::endl;
+    return 1;
+  }
+  if (locale->variant_count() != 1) {
+    std::cout << "After remove, expected 1 variant" << std::endl;
+    return 1;
+  }
+
+  // Remove non-existent (returns false)
+  auto removedNone = locale->remove_variant("posix");
+  if (removedNone) {
+    std::cout << "Expected remove_variant to return false for non-existent" << std::endl;
+    return 1;
+  }
+
+  // Clear variants
+  locale->clear_variants();
+  if (locale->variant_count() != 0) {
+    std::cout << "After clear, expected 0 variants" << std::endl;
+    return 1;
+  }
+  std::cout << "Variant tests passed!" << std::endl;
+
   return 0;
 }

ffi/capi/bindings/c/Locale.h

@@ -159,6 +159,69 @@ pub mod ffi {
             Ok(())
         }
 
+        // --- Variants ---
+
+        /// Returns a string representation of the [`Locale`] variants.
+        #[diplomat::rust_link(icu::locale::Variants, Struct)]
+        pub fn variants(&self, write: &mut diplomat_runtime::DiplomatWrite) {
+            let _infallible = self.0.id.variants.write_to(write);
+        }
+
+        /// Returns the number of variants in this [`Locale`].
+        #[diplomat::rust_link(icu::locale::Variants, Struct)]
+        #[diplomat::attr(auto, getter)]
+        pub fn variant_count(&self) -> usize {
+            self.0.id.variants.len()
+        }
+
+        /// Returns the variant at the given index, or nothing if the index is out of bounds.
+        #[diplomat::rust_link(icu::locale::Variants, Struct)]
+        pub fn variant_at(
+            &self,
+            index: usize,
+            write: &mut diplomat_runtime::DiplomatWrite,
+        ) -> Option<()> {
+            let _infallible = self.0.id.variants.get(index)?.write_to(write);
+            Some(())
+        }
+
+        /// Returns whether the [`Locale`] has a specific variant.
+        #[diplomat::rust_link(icu::locale::Variants, Struct)]
+        pub fn has_variant(&self, s: &DiplomatStr) -> bool {
+            icu_locale_core::subtags::Variant::try_from_utf8(s)
+                .map(|v| self.0.id.variants.contains(&v))
+                .unwrap_or(false)
+        }
+
+        /// Adds a variant to the [`Locale`].
+        ///
+        /// Returns an error if the variant string is invalid.
+        /// Returns `true` if the variant was added, `false` if already present.
+        #[diplomat::rust_link(icu::locale::Variants::push, FnInStruct)]
+        pub fn add_variant(&mut self, s: &DiplomatStr) -> Result<bool, LocaleParseError> {
+            let variant = icu_locale_core::subtags::Variant::try_from_utf8(s)?;
+            Ok(self.0.id.variants.push(variant))
+        }
+
+        /// Removes a variant from the [`Locale`].
+        ///
+        /// Returns `true` if the variant was removed, `false` if not present.
+        /// Returns `false` for invalid variant strings (they cannot exist in the locale).
+        #[diplomat::rust_link(icu::locale::Variants::remove, FnInStruct)]
+        pub fn remove_variant(&mut self, s: &DiplomatStr) -> bool {
+            icu_locale_core::subtags::Variant::try_from_utf8(s)
+                .map(|v| self.0.id.variants.remove(&v))
+                .unwrap_or(false)
+        }
+
+        /// Clears all variants from the [`Locale`].
+        #[diplomat::rust_link(icu::locale::Variants::clear, FnInStruct)]
+        pub fn clear_variants(&mut self) {
+            self.0.id.variants.clear();
+        }
+
+        // --- Other ---
+
         /// Normalizes a locale string.
         #[diplomat::rust_link(icu::locale::Locale::normalize, FnInStruct)]
         #[diplomat::rust_link(icu::locale::Locale::normalize_utf8, FnInStruct, hidden)]