%% %CopyrightBegin%
%%
%% SPDX-License-Identifier: Apache-2.0
%%
%% Copyright Ericsson AB 2021-2025. All Rights Reserved.
%%
%% %CopyrightEnd%

[;1m  binary_to_existing_atom(Binary, Encoding)[0m

  As [;;4mbinary_to_atom/2[0m, but the atom must exist.

  The Erlang system has a configurable limit for the total number of
  atoms that can exist, and atoms are not garbage collected.
  Therefore, it is not safe to create many atoms from binaries that
  come from an untrusted source (for example, a file fetched from
  the Internet), for example, using [;;4mbinary_to_atom/2[0m. This
  function is thus the appropriate option when the input binary
  comes from an untrusted source.

  An atom exists in an Erlang system when included in a loaded
  Erlang module or when created programmatically (for example, by [;;4m[0m
  [;;4mbinary_to_atom/2[0m). See the next note for an example of when an
  atom exists in the source code for an Erlang module but not in the
  compiled version of the same module.

  Failure: [;;4mbadarg[0m if the atom does not exist.

  [;;4mNote[0m

    Note that the compiler may optimize away atoms. For example,
    the compiler will rewrite [;;4matom_to_list(some_atom)[0m to [;;4m[0m
    [;;4m"some_atom"[0m. If that expression is the only mention of the
    atom [;;4msome_atom[0m in the containing module, the atom will not
    be created when the module is loaded, and a subsequent call to [;;4m[0m
    [;;4mbinary_to_existing_atom(<<"some_atom">>, utf8)[0m will fail.

  [;;4mNote[0m

    The number of characters that are permitted in an atom name is
    limited. The default limits can be found in the Efficiency
    Guide (section System Limits).
