
string_code(?Index, +String, ?Code)

   Succeeds if Code is the value of the Index'th character code in String

Arguments
   Index               Variable or integer between 1 and the length of String
   String              String
   Code                Variable or non-negative integer

Type
   Strings and Atoms

Description
    This predicate maps the index position Index to the corresponding
    character code in the given string String.  Character codes in the
    string are numbered from 1 (analogous to array indices in subscript/3
    and arg/3).  Index positions of zero or greater than the string length
    lead to failure.
    
    The predicate may be used to extract the Index'th character, to find
    the position(s) of a particular character code, or to enumerate all
    positions and character codes in the string.
    
    For simply extracting the Index'th character code from a string,
    the deterministic variant get_string_code/3 might be preferred
    for efficiency and stricter error checking.
    
    For backward compatibility with earlier versions of ECLiPSe, the 
    call pattern string_code(+String,+Index,-Code) is also allowed.


Modes and Determinism
   string_code(+, +, -) is det
   string_code(-, +, +) is nondet
   string_code(-, +, -) is nondet

Fail Conditions
   Fails if character Code does not occur in String

Exceptions
     4 --- String is uninstantated
     5 --- String is instantiated, but not a string
    24 --- Index is instantiated, but not an integer
     5 --- Code is instantiated, but not an integer
     6 --- Index or Code is a negative integer

Examples
   
   string_code(1, "abc", 0'a).        % succeeds
   string_code(1, "abc", 97).         % succeeds
   string_code(3, "abc", C).          % gives C = 0'c
   string_code(I, "abc", 0'c).        % gives I = 3
   string_code(I, "abcb", 0'b).       % gives I = 2 ; I = 4 on backtracking
   string_code(I, "ab", C).           % gives I=1,C=0'a ; I=2,C=0'b on backtracking

   string_code(2, "abc", 100).        % fails
   string_code(I, "abc", 0'd).        % fails
   string_code(0, "abc", C).          % fails
   string_code(4, "abc", C).          % fails
   string_code(I, "", C).             % fails

   string_code(1, S, 0'c).            % Error 4
   string_code(1, abc, C).            % Error 5
   string_code(1.5, "abc", C).        % Error 5
   string_code(I, "abc", b).          % Error 5
   string_code(-1, "abc", C).         % Error 6
   string_code(I, "abc", -1).         % Error 6


See Also
   get_string_code / 3, string_codes / 2, string_list / 2, char_code / 2
