rustler 0.39.0

#[cfg(feature = "nif_version_2_17")]
use crate::sys::enif_make_new_atom_len;
use crate::sys::{
    c_char, c_uint, enif_get_atom, enif_get_atom_length, enif_make_existing_atom_len,
    ErlNifCharEncoding, ErlNifEnv, ErlNifTerm,
};
#[cfg(not(feature = "nif_version_2_17"))]
use crate::sys::{enif_is_exception, enif_make_atom_len};
use crate::{Decoder, Encoder, Env, Error, NifResult, Term};
use std::fmt;
use std::hash::{Hash, Hasher};
use std::mem::MaybeUninit;

// Atoms are a special case of a term. They can be stored and used on all envs regardless of where
// it lives and when it is created.
#[derive(PartialEq, Eq, Clone, Copy)]
#[repr(transparent)]
pub struct Atom {
    term: ErlNifTerm,
}

impl Atom {
    pub fn as_c_arg(self) -> ErlNifTerm {
        self.term
    }

    pub fn to_term(self, env: Env) -> Term {
        // Safe because atoms are not associated with any environment.
        unsafe { Term::new(env, self.term) }
    }

    unsafe fn from_nif_term(term: ErlNifTerm) -> Self {
        Self { term }
    }

    pub fn from_term(term: Term) -> NifResult<Self> {
        if term.is_atom() {
            Ok(unsafe { Self::from_nif_term(term.as_c_arg()) })
        } else {
            Err(Error::BadArg)
        }
    }

    /// Return the atom whose text representation is Latin1 `bytes`.
    ///
    /// # Errors
    /// `Error::BadArg` if atom creation fails.
    ///
    /// This function uses Latin-1 encoding for compatibility.
    pub fn from_bytes(env: Env, bytes: &[u8]) -> NifResult<Self> {
        Self::from_encoded_bytes(env, bytes, ErlNifCharEncoding::ERL_NIF_LATIN1)
    }

    /// Return the atom whose text representation is UTF-8 `bytes`.
    ///
    /// # Errors
    /// `Error::BadArg` if atom creation fails. Before NIF 2.17, it will also
    /// return `Error::BadArg` if the atom can not be encoded to Latin1.
    ///
    /// On NIF 2.17+ (`OTP 26+`), this uses UTF-8 atom APIs directly.
    /// On older NIF versions, UTF-8 is transcoded to Latin-1 before atom creation.
    pub fn from_utf8_bytes(env: Env, bytes: &[u8]) -> NifResult<Self> {
        use ErlNifCharEncoding::*;

        #[cfg(feature = "nif_version_2_17")]
        {
            Self::from_encoded_bytes(env, bytes, ERL_NIF_UTF8)
        }

        #[cfg(not(feature = "nif_version_2_17"))]
        {
            let string = std::str::from_utf8(bytes).map_err(|_| Error::BadArg)?;
            let mut latin1 = Vec::with_capacity(string.len());
            for c in string.chars() {
                if (c as u32) >= 256 {
                    return Err(Error::BadArg);
                }
                latin1.push(c as u8);
            }
            Self::from_encoded_bytes(env, &latin1, ERL_NIF_LATIN1)
        }
    }

    fn from_encoded_bytes(env: Env, bytes: &[u8], encoding: ErlNifCharEncoding) -> NifResult<Self> {
        unsafe { make_atom(env.as_c_arg(), bytes, encoding).map(|term| Self::from_nif_term(term)) }
    }

    /// Return the atom whose text representation is Latin1 `bytes`, like `erlang:binary_to_existing_atom/1`,
    /// if atom with given text representation exists.
    ///
    /// # Errors
    /// `Error::BadArg` if the bytes are incorrectly encoded, the array is too long (255 bytes before
    /// NIF 2.17, 255 characters later), or the atom does not exist.
    pub fn existing_from_bytes(env: Env, bytes: &[u8]) -> NifResult<Self> {
        Self::existing_from_encoded_bytes(env, bytes, ErlNifCharEncoding::ERL_NIF_LATIN1)
    }

    /// Return the atom whose text representation is Latin1 `bytes`, like `erlang:binary_to_existing_atom/1`,
    /// if atom with given text representation exists.
    #[deprecated(since = "0.38.0", note = "Use existing_from_(utf8_)bytes")]
    pub fn try_from_bytes(env: Env, bytes: &[u8]) -> NifResult<Option<Self>> {
        Self::existing_from_bytes(env, bytes).map(Some)
    }

    /// Return the atom whose text representation is UTF8 `bytes`, like `erlang:binary_to_existing_atom/2`,
    /// if atom with given text representation exists.
    ///
    /// # Errors
    /// `Error::BadArg` if the bytes are incorrectly encoded, the array is too long (255 bytes before
    /// NIF 2.17, 255 characters later), or the atom does not exist.
    ///
    /// On NIF 2.17+ (`OTP 26+`), this uses UTF-8 atom APIs directly.
    /// On older NIF versions, UTF-8 is transcoded to Latin-1 before lookup.
    pub fn existing_from_utf8_bytes(env: Env, bytes: &[u8]) -> NifResult<Self> {
        use ErlNifCharEncoding::*;

        #[cfg(feature = "nif_version_2_17")]
        {
            Self::existing_from_encoded_bytes(env, bytes, ERL_NIF_UTF8)
        }

        #[cfg(not(feature = "nif_version_2_17"))]
        {
            let string = std::str::from_utf8(bytes).map_err(|_| Error::BadArg)?;
            let mut latin1 = Vec::with_capacity(string.len());
            for c in string.chars() {
                if (c as u32) >= 256 {
                    return Err(Error::BadArg);
                }
                latin1.push(c as u8);
            }
            Self::existing_from_encoded_bytes(env, &latin1, ERL_NIF_LATIN1)
        }
    }

    /// Return the atom whose text representation is `bytes`, like `erlang:binary_to_existing_atom/2`,
    /// if atom with given text representation exists.
    ///
    /// # Errors
    /// `Error::BadArg` if the bytes are incorrectly encoded, the array is too long (255 bytes before
    /// NIF 2.17, 255 characters later), or the atom does not exist.
    fn existing_from_encoded_bytes(
        env: Env,
        bytes: &[u8],
        encoding: ErlNifCharEncoding,
    ) -> NifResult<Self> {
        unsafe {
            make_existing_atom(env.as_c_arg(), bytes, encoding)
                .map(|term| Self::from_nif_term(term))
        }
    }

    /// Return the atom whose text representation is the given `string`.
    ///
    /// # Errors
    /// `Error::BadArg` if atom creation fails.
    pub fn from_str(env: Env, string: &str) -> NifResult<Self> {
        Self::from_utf8_bytes(env, string.as_bytes())
    }

    /// Return the atom whose text representation is the given `string`.
    ///
    /// # Errors
    /// `Error::BadArg` if atom lookup fails.
    pub fn existing_from_str(env: Env, string: &str) -> NifResult<Self> {
        Self::existing_from_utf8_bytes(env, string.as_bytes())
    }

    /// Return the atom whose text representation is the given `string`.
    ///
    /// Deprecated in favor of [`Atom::from_str_existing`].
    #[deprecated(since = "0.38.0", note = "Use existing_from_str")]
    pub fn try_from_str(env: Env, string: &str) -> NifResult<Option<Self>> {
        Self::existing_from_str(env, string).map(Some)
    }
}

impl fmt::Debug for Atom {
    fn fmt(&self, f: &mut fmt::Formatter) -> Result<(), fmt::Error> {
        crate::term::fmt(self.as_c_arg(), f)
    }
}

impl Encoder for Atom {
    fn encode<'a>(&self, env: Env<'a>) -> Term<'a> {
        self.to_term(env)
    }
}
impl<'a> Decoder<'a> for Atom {
    fn decode(term: Term<'a>) -> NifResult<Atom> {
        Atom::from_term(term)
    }
}

impl<'a> PartialEq<Term<'a>> for Atom {
    fn eq(&self, other: &Term<'a>) -> bool {
        self.as_c_arg() == other.as_c_arg()
    }
}

/// ## Atom terms
impl Term<'_> {
    /// When the term is an atom, this method will return the string
    /// representation of it.
    ///
    /// If you only need to test for equality, comparing the terms directly
    /// is much faster.
    ///
    /// Will return None if the term is not an atom.
    pub fn atom_to_string(&self) -> NifResult<String> {
        unsafe { get_atom(self.get_env().as_c_arg(), self.as_c_arg()) }
    }
}

pub fn is_truthy(term: Term) -> bool {
    !((term.as_c_arg() == false_().as_c_arg()) || (term.as_c_arg() == nil().as_c_arg()))
}

pub(in crate::types) fn decode_bool(term: Term) -> NifResult<bool> {
    let as_c_arg = term.as_c_arg();

    if as_c_arg == true_().as_c_arg() {
        return Ok(true);
    }

    if as_c_arg == false_().as_c_arg() {
        return Ok(false);
    }

    Err(Error::BadArg)
}

impl Hash for Atom {
    fn hash<H: Hasher>(&self, state: &mut H) {
        use crate::sys::{enif_hash, ErlNifHash};
        let hash =
            unsafe { enif_hash(ErlNifHash::ERL_NIF_INTERNAL_HASH, self.as_c_arg(), 0) as u32 };
        state.write_u32(hash);
    }
}

// This is safe because atoms are never removed/changed once they are created.
unsafe impl Sync for Atom {}
unsafe impl Send for Atom {}

/// Macro for defining Rust functions that return Erlang atoms.
///
/// For example, this code:
///
///     mod my_atoms {
///         rustler::atoms! {
///             jpeg,
///         }
///     }
///     # fn main() {}
///
/// defines a public function `my_atoms::jpeg()` that returns the `Atom` for the `jpeg` atom.
///
/// Multiple atoms can be defined. Each one can have its own doc comment and other attributes.
///
///     rustler::atoms! {
///         /// The `jpeg` atom.
///         jpeg,
///
///         /// The `png` atom.
///         png,
///
///         #[allow(non_snake_case)]
///         WebP,
///     }
///     # fn main() {}
///
/// When you need an atom that's not a legal Rust function name, write `NAME = "ATOM"`, like
/// this:
///
///     rustler::atoms! {
///         /// The `mod` atom. The function isn't called `mod` because that's
///         /// a Rust keyword.
///         mod_atom = "mod",
///
///         /// The atom `'hello world'`. Obviously this function can't be
///         /// called `hello world` because there's a space in it.
///         hello_world = "hello world",
///     }
///     # fn main() {}
///
/// # Performance
///
/// These functions are faster than `get_atom` and `get_atom_init`. The first time you call one, it
/// creates atoms for all its sibling functions and caches them, so that all later calls are fast.
/// The only overhead is checking that the atoms have been created (an atomic integer read).
///
#[macro_export]
macro_rules! atoms {
    {
        $(
            $( #[$attr:meta] )*
            $name:ident $( = $str:expr )?
        ),*$(,)?
    } => {
        #[allow(non_snake_case)]
        struct RustlerAtoms {
            $( $name : $crate::types::atom::Atom ),*
        }
        impl RustlerAtoms {
            fn get() -> &'static Self {
                use std::sync::OnceLock;
                static RUSTLER_ATOMS: OnceLock<RustlerAtoms> = OnceLock::new();
                RUSTLER_ATOMS.get_or_init(||
                    $crate::env::OwnedEnv::new().run(|env| {
                        RustlerAtoms {
                            $( $name: $crate::atoms!(@internal_make_atom(env, $name $( = $str)? )) ),*
                        }
                    })
                )
            }
        }
        $(
            $( #[$attr] )*
            pub fn $name() -> $crate::types::atom::Atom {
                RustlerAtoms::get().$name
            }
        )*
    };

    // Internal helper macros.
    { @internal_make_atom($env:ident, $name:ident) } => {
        $crate::atoms!(@internal_make_atom($env, $name = stringify!($name)))
    };
    { @internal_make_atom($env:ident, $name:ident = $str:expr) } => {
        $crate::types::atom::Atom::from_str($env, $str)
            .expect("rustler::atoms!: bad atom string")
    };
}

atoms! {
    /// The `nif_panicked` atom.
    nif_panicked,

    /// The `nil` atom.
    nil,

    /// The `undefined` atom, commonly used in Erlang libraries to express the
    /// absence of value.
    undefined,

    /// The `ok` atom, commonly used in success tuples.
    ok,

    /// The `error` atom, commonly used in error tuples.
    error,

    /// The `badarg` atom, which Rustler sometimes returns to indicate that a function was
    /// called with incorrect arguments.
    badarg,

    /// The `false` atom. (Trailing underscore because `false` is a keyword in Rust.)
    ///
    /// If you're looking to convert between Erlang terms and Rust `bool`
    /// values, use `Encoder` and `Decoder` instead.
    false_ = "false",

    /// The `true` atom. (Trailing underscore because `true` is a keyword in Rust.)
    ///
    /// If you're looking to convert between Erlang terms and Rust `bool`
    /// values, use `Encoder` and `Decoder` instead.
    true_ = "true",

    /// The `__struct__` atom used by Elixir.
    __struct__,

    /// The `first` atom used by `Elixir.Range`.
    first,

    /// The `last` atom used by `Elixir.Range`.
    last,

    /// The `step` atom used by `Elixir.Range` vor Elixir >= v1.12
    step,
}

#[cfg(not(feature = "nif_version_2_17"))]
unsafe fn make_atom(
    env: *mut ErlNifEnv,
    name: &[u8],
    _encoding: ErlNifCharEncoding,
) -> Result<ErlNifTerm, Error> {
    let res = enif_make_atom_len(env, name.as_ptr() as *const c_char, name.len());

    if enif_is_exception(env, res) != 0 {
        Err(Error::BadArg)
    } else {
        Ok(res)
    }
}

#[cfg(feature = "nif_version_2_17")]
unsafe fn make_atom(
    env: *mut ErlNifEnv,
    name: &[u8],
    encoding: ErlNifCharEncoding,
) -> Result<ErlNifTerm, Error> {
    let mut atom_out = MaybeUninit::uninit();

    if enif_make_new_atom_len(
        env,
        name.as_ptr() as *const c_char,
        name.len(),
        atom_out.as_mut_ptr(),
        encoding,
    ) != 0
    {
        Ok(atom_out.assume_init())
    } else {
        Err(Error::BadArg)
    }
}

unsafe fn make_existing_atom(
    env: *mut ErlNifEnv,
    name: &[u8],
    encoding: ErlNifCharEncoding,
) -> Result<ErlNifTerm, Error> {
    let mut atom_out = MaybeUninit::uninit();

    if enif_make_existing_atom_len(
        env,
        name.as_ptr() as *const c_char,
        name.len(),
        atom_out.as_mut_ptr(),
        encoding,
    ) != 0
    {
        Ok(atom_out.assume_init())
    } else {
        Err(Error::BadArg)
    }
}

#[cfg(feature = "nif_version_2_17")]
unsafe fn get_atom(env: *mut ErlNifEnv, term: ErlNifTerm) -> Result<String, Error> {
    let mut len = 0;
    let success = enif_get_atom_length(env, term, &mut len, ErlNifCharEncoding::ERL_NIF_UTF8);
    if success == 0 {
        return Err(Error::BadArg);
    }

    let mut string = String::with_capacity(len as usize + 1);
    let bytes = string.as_mut_vec();
    let nbytes = enif_get_atom(
        env,
        term,
        bytes.as_mut_ptr() as *mut c_char,
        len + 1,
        ErlNifCharEncoding::ERL_NIF_UTF8,
    );
    assert!(nbytes as c_uint == len + 1);

    bytes.set_len(len as usize);

    Ok(string)
}

#[cfg(not(feature = "nif_version_2_17"))]
unsafe fn get_atom(env: *mut ErlNifEnv, term: ErlNifTerm) -> Result<String, Error> {
    let mut len = 0;
    let success = enif_get_atom_length(env, term, &mut len, ErlNifCharEncoding::ERL_NIF_LATIN1);
    if success == 0 {
        return Err(Error::BadArg);
    }

    let mut bytes: Vec<u8> = Vec::with_capacity(len as usize + 1);
    let nbytes = enif_get_atom(
        env,
        term,
        bytes.as_mut_ptr() as *mut c_char,
        len + 1,
        ErlNifCharEncoding::ERL_NIF_LATIN1,
    );
    assert!(nbytes as c_uint == len + 1);

    bytes.set_len(len as usize);

    let nonascii_count = bytes.iter().filter(|&&b| b >= 128).count();
    if nonascii_count == 0 {
        Ok(String::from_utf8_unchecked(bytes))
    } else {
        let mut out = String::with_capacity(bytes.len() + nonascii_count);
        for b in bytes {
            out.push(b as char);
        }
        Ok(out)
    }
}