[ Strings and Atoms | Reference Manual | Alphabetic Index ]

# concat_atoms(+Src1, +Src2, -Dest)

Succeeds if Dest is the concatenation of Src1 and Src2. It is more efficient to use concat_strings/3 whenever possible.

Src1
  Atom.
Src2
  Atom.
Dest
  Atom or variable.

## Description

Dest is unified with the concatenation of Src1 and Src2. The use of this predicate is discouraged in favour of concat_strings/3, because the creation of new atoms involves entering them into a dictionary whose garbage collection is relatively expensive.

### Modes and Determinism

- concat_atoms(+, +, -) is det

### Exceptions

(4) instantiation fault
  Either (or both) of Src1 and Src2 is not instantiated (non-coroutine mode only).
(5) type error
  Either (or both) of Src1 and Src2 is instantiated, but not to an atom.
(5) type error
  Dest is neither an atom nor a variable.

## Examples

    Success:
          concat_atoms(abc,def,abcdef).

          [eclipse]: [user].
           filename(File,Full) :-
                name(File,L),
                member(0'.,L) -> Full = File ;
                              concat_atoms(File,'.pl',Full).
           user compiled 208 bytes in 0.00 seconds
          yes.
          [eclipse]: filename(a,P), filename('b.pl',F).
          P = 'a.pl'
          F = 'b.pl'
          yes.

    Fail:
          concat_atoms(ab,bc,abc).

    Error:
          concat_atoms(art,X,artpaul).      (Error 4).
          concat_atoms(art,"paul",X).       (Error 5).

## See Also

concat_strings / 3, append_strings / 3, atom_string / 2