1//! Encoding / locale probing utilities.
2//!
3//! This module exists mainly for debugging + experiments around R's string
4//! encodings. R's runtime has both:
5//! - per-CHARSXP encoding tags (UTF-8 / Latin-1 / bytes / native)
6//! - global/locale-level settings (native encoding, UTF-8 locale flags)
7//!
8//! # Availability
9//!
10//! The global signals are **non-API** (from `Defn.h`) and require the `nonapi`
11//! feature. Only the locale flags R's shared library exports are read
12//! (`utf8locale`, `mbcslocale`, `known_to_be_latin1`); the hidden ones
13//! (`known_to_be_utf8`, `latin1locale`, `R_nativeEncoding`) must not even be
14//! *referenced* — an eager data relocation against a hidden symbol aborts
15//! `dyn.load` of the whole package (see `sys::nonapi_encoding`).
16//!
17//! `miniextendr_encoding_init()` is not called by `package_init`; it exists
18//! for debugging and for standalone Rust applications embedding R.
19//!
20//! A package loads in any locale. String conversions read each CHARSXP's
21//! encoding mark and translate when needed; in a session whose locale isn't
22//! UTF-8, the first translation of a native non-ASCII string raises one
23//! warning ([`NATIVE_TRANSLATION_CLASS`]).
2425use std::sync::OnceLock;
2627/// Cached snapshot of R's encoding / locale state at init time.
28#[derive(#[automatically_derived]impl ::core::fmt::Debug for REncodingInfo {
#[inline]
fn fmt(&self, f: &mut ::core::fmt::Formatter) -> ::core::fmt::Result {
::core::fmt::Formatter::write_str(f, "REncodingInfo")
}
}Debug, #[automatically_derived]impl ::core::clone::Clone for REncodingInfo {
#[inline]
fn clone(&self) -> Self { REncodingInfo {} }
}Clone)]
29pub struct REncodingInfo {
30#[cfg(feature = "nonapi")]
31/// Whether R thinks the current locale is UTF-8 (non-API `utf8locale`).
32pub utf8_locale: Option<bool>,
33#[cfg(feature = "nonapi")]
34/// Whether the current locale is multi-byte (non-API `mbcslocale`).
35pub mbcs_locale: Option<bool>,
36#[cfg(feature = "nonapi")]
37/// Whether R treats unknown-encoding strings as Latin-1 (non-API
38 /// `known_to_be_latin1`).
39pub known_to_be_latin1: Option<bool>,
40}
4142static ENCODING_INFO: OnceLock<REncodingInfo> = OnceLock::new();
4344/// Return the cached encoding info (if `miniextendr_encoding_init()` has run).
45#[inline]
46pub fn encoding_info() -> Option<&'static REncodingInfo> {
47ENCODING_INFO.get()
48}
4950/// The class of the warning a package raises the first time it translates a
51/// native string to UTF-8.
52pub const NATIVE_TRANSLATION_CLASS: &str = "miniextendr_native_translation";
5354/// Queue a warning, once per session for each package, the first time a
55/// native (unmarked) non-ASCII string is translated to UTF-8: the session's
56/// locale isn't UTF-8, and bytes its encoding can't represent came out as
57/// `<xx>` escapes.
58///
59/// Deferred, so it is signalled when the current call returns, never from
60/// inside a conversion; class [`NATIVE_TRANSLATION_CLASS`].
61pub(crate) fn warn_native_translation() {
62static WARNED: std::sync::atomic::AtomicBool = std::sync::atomic::AtomicBool::new(false);
63if WARNED.swap(true, std::sync::atomic::Ordering::Relaxed) {
64return;
65 }
66crate::deferred_condition::defer_warning(
67crate::condition::RError::new(
68"translated a string from the session's native encoding to UTF-8: the R session's \
69 locale isn't UTF-8, so characters that encoding can't represent became <xx> \
70 escapes. Start R in a UTF-8 locale (for example LANG=C.UTF-8) to avoid \
71 translation. Shown once per session.",
72 )
73 .class(NATIVE_TRANSLATION_CLASS)
74 .without_call(),
75 );
76}
7778/// Initialize / snapshot R's encoding state.
79///
80/// Intended to be called once from `R_init_*` (package init).
81#[unsafe(no_mangle)]
82pub extern "C-unwind" fn miniextendr_encoding_init() {
83let _ = ENCODING_INFO.get_or_init(|| {
84#[cfg(feature = "nonapi")]
85unsafe {
86use crate::Rboolean;
87use crate::sys::nonapi_encoding;
8889let utf8_locale = Some(nonapi_encoding::utf8locale != Rboolean::FALSE);
90let mbcs_locale = Some(nonapi_encoding::mbcslocale != Rboolean::FALSE);
91let known_to_be_latin1 = Some(nonapi_encoding::known_to_be_latin1 != Rboolean::FALSE);
9293let info = REncodingInfo {
94 utf8_locale,
95 mbcs_locale,
96 known_to_be_latin1,
97 };
9899if std::env::var_os("MINIEXTENDR_ENCODING_DEBUG").is_some() {
100let msg = format!("[miniextendr] encoding init: {info:?}\n");
101if let Ok(c_msg) = std::ffi::CString::new(msg) {
102crate::sys::REprintf_unchecked(c"%s".as_ptr(), c_msg.as_ptr());
103 }
104 }
105106 info
107 }
108109#[cfg(not(feature = "nonapi"))]
110{
111REncodingInfo {}
112 }
113 });
114}