[ Strings and Atoms | Reference Manual | Alphabetic Index ]
string_list(?String, ?List, +Format)
Conversion between string in different encodings and a character list
- String
- String or variable.
- List
- A variable or a list of integers and/or variables.
- Format
- An atom.
Description
   This predicate performs conversion between a string encoded in Format
   and a list of the corresponding character representations.
   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 representations.
   If List is instantiated, it is must contain character representations
   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 or octet
- 
    Every byte in the string corresponds to a list integer in the range 0..255.
- chars
- 
    Every character in the string corresponds to a single-character atom
    in the list.  This format assumes a default character encoding.
- codes
- 
    Every character in the string corresponds to an integer character code
    in the list.  This format assumes a default character encoding.
- 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).
Modes and Determinism
- string_list(+, -, +) is det
- string_list(-, +, +) is det
Exceptions
- (4) instantiation fault 
- Format is 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 is not an atom.
- (6) out of range 
- One (or more) elements of List are not of the type corresponding to Format.
- (6) out of range 
- Format is not a valid format specification.
- (6) out of range 
- One (or more) elements of List are not integers or atoms in the 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
string_list / 2, write / 2, read_string / 4