Packages
gleam_stdlib
0.10.0
1.0.3
1.0.2
1.0.1
1.0.0
0.71.0
0.70.0
0.69.0
0.68.1
0.68.0
0.67.1
0.67.0
0.65.0
0.64.0
0.63.2
0.63.1
0.63.0
0.62.1
0.62.0
0.61.0
0.60.0
0.59.0
0.58.0
0.57.0
0.56.0
0.55.0
0.54.0
0.53.0
0.52.0
0.51.0
0.50.0
0.49.0
0.48.0
0.47.0
0.46.0
0.45.0
0.44.0
0.43.0
0.42.0
0.41.0
0.40.0
0.39.0
0.38.0
0.37.0
0.36.0
0.35.1
0.35.0
0.34.0
0.33.1
0.33.0
0.32.1
0.32.0
0.31.0
0.30.2
0.30.1
0.30.0
0.29.2
0.29.1
0.29.0
0.28.2
0.28.1
0.28.0
0.27.0
0.26.1
0.26.0
0.25.0
0.24.0
0.23.0
0.22.3
0.22.2
0.22.1
0.22.0
0.21.0
0.20.0
0.19.3
0.19.2
0.19.1
0.19.0
0.18.1
0.18.0
0.18.0-rc1
0.17.1
0.17.0
0.16.0
0.15.0
0.14.0
0.13.0
0.12.0
0.11.0
0.10.1
0.10.0
0.9.0
0.8.0
0.7.0
0.6.0
0.5.0
0.4.0
0.4.0-rc1
0.3.1
0.3.0
0.2.0
retired
A standard library for the Gleam programming language
Current section
Files
Jump to
Current section
Files
src/gleam/atom.gleam
/// Atom is a special string-like data-type that is most commonly used for
/// interfacing with code written in other BEAM languages such as Erlang and
/// Elixir. It is preferable to define your own custom types to use instead of
/// atoms where possible.
///
/// Atoms are not used much in typical Gleam code!
///
/// ## Creating atoms
///
/// We can create atoms with the the [`create_from_string`](#create_from_string)
/// function, though we must be careful when doing so as atoms are never
/// garbage collected. If we create too many atoms (for example, if we convert
/// user input into atoms) we may hit the max limit of atoms and cause the
/// virtual machine to crash.
///
pub external type Atom
/// An error returned when no atom is found in the virtual machine's atom table
/// for a given string when calling the [`from_string`](#from_string) function.
pub type FromStringError {
AtomNotLoaded
}
/// Find an existing Atom for the given String.
///
/// If no atom is found in the virtual machine's atom table for the String then
/// an error is returned.
///
/// ## Examples
///
/// > from_string("ok")
/// Ok(create_from_string("ok"))
///
/// > from_string("some_new_atom")
/// Error(AtomNotLoaded)
///
pub external fn from_string(String) -> Result(Atom, FromStringError) =
"gleam_stdlib" "atom_from_string"
/// Create an atom from a string, inserting a new value into the virtual
/// machine's atom table if an atom does not already exist for the given
/// string.
///
/// We must be careful when using this function as there is a limit to the
/// number of atom that can fit in the virtual machine's atom table. Never
/// convert user input into atoms as filling the atom table will cause the
/// virtual machine to crash!
///
pub external fn create_from_string(String) -> Atom =
"gleam_stdlib" "atom_create_from_string"
/// Retuns a `String` corresponding to the text representation of the given
/// `Atom`.
///
/// ## Examples
///
/// > let ok_atom = create_from_string("ok")
/// > to_string(ok_atom)
/// "ok"
///
pub external fn to_string(Atom) -> String =
"gleam_stdlib" "atom_to_string"