[ Strings and Atoms | Reference Manual | Alphabetic Index ]

# string_chars(?String, ?Chars)

Chars is a list whose elements are the single-character atoms of the characters in the string

String
  String or variable.
Chars
  Chars of integer character codes and/or variables, or simply a variable.

## Description

This predicate performs the mapping between a string and the corresponding list of single-character atoms.

If String is instantiated, unifies Chars with the list whose elements are the single-character atoms for the character in the string.

If Chars is instantiated, unifies String with the string composed from the single-character atoms given by the list elements.

### Modes and Determinism

- string_chars(+, -) is det
- string_chars(-, +) is det

### Exceptions

(5) type error
  String is not a string.
(5) type error
  Chars is not a proper list.
(5) type error
  Chars contains non-atom elements.
(6) out of range
  Condes contains atoms that do not represent characters.
(4) instantiation fault
  Both String and Chars are nonground (non-coroutine mode only).

## Examples

       Success:
       string_chars(S,['A',b,c]).           (gives S="Abc").
       string_chars("abc",L).               (gives L=[a,b,c]).
       string_chars("abc",[a,A,c]).         (gives A=b).
       string_chars(S,['']).                (gives S="\177").
       string_chars("abc",[a|A]).           (gives A=[b,c]).
       Fail:
       string_chars("abc",[b,c,d]).
       Error:
       string_chars(S,[A|[128]]).           (Error 4).
       string_chars(S,[1|A]).               (Error 4).
       string_chars('string',L).            (Error 5).
       string_chars(S,"list").              (Error 5).
       string_chars('string',[128]).        (Error 5).
       string_chars(S,["B"]).               (Error 5).
       string_chars(S,[256]).               (Error 6).

## See Also

string_code / 3, string_codes / 2, string_list / 3, char_code / 2