string_list(?String, ?List, +Format)

?String

String or variable.

?List

A variable or a list of integers and/or variables.

+Format

An atom.

Description

If String is instantiated, it is must be a valid string in the encoding format specified by Format. It is then decoded and List is unified with a list of the corresponding character codes.

If List is instantiated, it is must contain character codes that are valid for the encoding format specified by Format. These characters are then encoded into a string which is unified with String.

Currently supported formats are:

bytes

every byte in the string corresponds to a list integer in the range 0..255.

utf8

the string is encoded in UTF-8 format and the list can contain integers in the range 0..2^31-1.

Note that string_list/2 can be defined as:

	string_list(S, L) :- string_list(S, L, bytes).

Fail Conditions

Resatisfiable

Exceptions

(4) instantiation fault

Format in not instantiated.

(4) instantiation fault

Neither String nor List are ground.

(5) type error

String is neither a string nor a variable.

(5) type error

List is neither a list nor a variable.

(5) type error

Format in not an atom.

(6) out of range

Format in not a valid format specification.

(6) out of range

One (or more) elements of List are not integers in a valid range for Format.

Examples

    [eclipse 1]: string_list(S,[65,66,67],bytes).
    S = "ABC"
    yes.

    [eclipse 2]: string_list(S, [65,66,67], utf8).
    S = "ABC"
    yes.

    [eclipse 3]: string_list(S, [65, 0, 700, 2147483647], bytes).
    out of range in string_list(S, [65, 0, 700, 2147483647])

    [eclipse 4]: string_list(S, [65, 0, 700, 2147483647], utf8).
    S = "A\000\312\274\375\277\277\277\277\277"
    yes.

See Also