[ 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

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