[ Strings and Atoms | Reference Manual | Alphabetic Index ]

# text_to_string(++Text, -String)

Convert different text representations to a string

Text
  An atom, string or list of characters.
String
  Variable or string.

## Description

This predicate converts different text representations to a string. Text is an atom, string, list of character codes, or list of single-character atoms.

Note that the atom '[]' represents the empty list [], and is therefore converted to the empty string.

Apart from error handling, this is a shorthand for

        text_to_string(Text, String) :-
    	( Text == [] -> String = ""
    	; atom(Text) -> atom_string(Text, String)
        	; string(Text) -> String = Text
    	; is_list(Text), Text = [C|_], atom(C) -> string_chars(String, Text)
    	; is_list(Text), Text = [C|_], integer(C) -> string_codes(String, Text)
    	).

### Modes and Determinism

- text_to_string(++, -) is det

### Exceptions

(4) instantiation fault
  Text is nonground.
(5) type error
  Text is neither atom, string, nor a proper list.
(5) type error
  Text is a list, but contains neither purely atoms nor purely integers.
(6) out of range
  Text is a list of atoms that do no all represent characters
(6) out of range
  Text is a list of integers that do no all represent characters

## Examples

      Success:

        text_to_string([0'a,0'b,0'c],S)     % gives S=="abc".
        text_to_string([a,b,c],S)	        % gives S=="abc".
        text_to_string(abc,S)               % gives S=="abc".
        text_to_string("abc",S)             % gives S=="abc".
        text_to_string([],S)                % gives S=="".

      Fail:
        text_to_string(abc,abc)             % gives S=="abc".

      Error:
        text_to_string(T,S)                 % Error 4
        text_to_string([a,B,c],S)           % Error 4
        text_to_string([a,0'b,c],S)         % Error 5
        text_to_string(123,S)               % Error 5
        text_to_string([a,bb,c],S)          % Error 6
        text_to_string([97,-1,99],S)        % Error 6

## See Also

string_codes / 2, string_chars / 2, string_list / 3, atom_string / 2