Skip to main content

miniextendr_api/
encoding.rs

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`]).
24
25use std::sync::OnceLock;
26
27/// 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`).
32    pub utf8_locale: Option<bool>,
33    #[cfg(feature = "nonapi")]
34    /// Whether the current locale is multi-byte (non-API `mbcslocale`).
35    pub 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`).
39    pub known_to_be_latin1: Option<bool>,
40}
41
42static ENCODING_INFO: OnceLock<REncodingInfo> = OnceLock::new();
43
44/// Return the cached encoding info (if `miniextendr_encoding_init()` has run).
45#[inline]
46pub fn encoding_info() -> Option<&'static REncodingInfo> {
47    ENCODING_INFO.get()
48}
49
50/// 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";
53
54/// 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() {
62    static WARNED: std::sync::atomic::AtomicBool = std::sync::atomic::AtomicBool::new(false);
63    if WARNED.swap(true, std::sync::atomic::Ordering::Relaxed) {
64        return;
65    }
66    crate::deferred_condition::defer_warning(
67        crate::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}
77
78/// 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() {
83    let _ = ENCODING_INFO.get_or_init(|| {
84        #[cfg(feature = "nonapi")]
85        unsafe {
86            use crate::Rboolean;
87            use crate::sys::nonapi_encoding;
88
89            let utf8_locale = Some(nonapi_encoding::utf8locale != Rboolean::FALSE);
90            let mbcs_locale = Some(nonapi_encoding::mbcslocale != Rboolean::FALSE);
91            let known_to_be_latin1 = Some(nonapi_encoding::known_to_be_latin1 != Rboolean::FALSE);
92
93            let info = REncodingInfo {
94                utf8_locale,
95                mbcs_locale,
96                known_to_be_latin1,
97            };
98
99            if std::env::var_os("MINIEXTENDR_ENCODING_DEBUG").is_some() {
100                let msg = format!("[miniextendr] encoding init: {info:?}\n");
101                if let Ok(c_msg) = std::ffi::CString::new(msg) {
102                    crate::sys::REprintf_unchecked(c"%s".as_ptr(), c_msg.as_ptr());
103                }
104            }
105
106            info
107        }
108
109        #[cfg(not(feature = "nonapi"))]
110        {
111            REncodingInfo {}
112        }
113    });
114}