[ Strings and Atoms | The ECLiPSe Built-In Predicates | Reference Manual | Alphabetic Index ]

# substring(+String1, ?Position, ?Length, ?String2)

Succeeds if String2 is the substring of String1 starting at position Position and of length Length.

String1
  String.
Position
  Integer (from 1 upwards) or variable.
Length
  Integer (from 0 upwards) or variable.
String2
  String or variable.

## Description

Succeeds if String2 is a substring of String1 starting at position Position and of length Length.

On backtracking, all such substrings are found.

The first character of a string is at position 1.

Note If String1 and String2 are instantiated, it is more efficient to use the predicates substring/3 and/or string_length/2.

### Modes and Determinism

- substring(+, +, +, -) is semidet
- substring(+, +, -, -) is nondet
- substring(+, -, +, -) is nondet
- substring(+, -, -, +) is nondet
- substring(+, -, -, -) is multi

### Fail Conditions

String1 does not have a substring at the required position and/or of the required length, or String2 does not occur within String1

### Exceptions

(5) type error
  String1 is instantiated, but not to a string.
(5) type error
  String2 is neither a string nor a variable.
(5) type error
  Either (or both) of Position or Length are neither integers nor variables.
(4) instantiation fault
  String1 is not instantiated.

## Examples

    Success:
      substring("abcabc",3,1,"c").
      substring("abcabc",6,1,"c").
      substring("abcabc",P,1,"c"). (gives P=3; P=6).
      substring("abcabc",3,3,S).   (gives S="cab").
      substring("abc",P,L,"b").    (gives P=2, L=1).

      [eclipse]: substring("ab",P,1,S).
      P=1
      S="a"     More? (;)
      P=2
      S="b"
      yes.

      [eclipse]: substring("ab",1,L,S).
      L=0
      S=""      More? (;)
      L=1
      S="a"     More? (;)
      L=2
      S="ab"
      yes,

      [eclipse]: substring("ab",P,L,S), writeq((P,L,S)), nl, fail.
      1 , 0 , ""            % on backtracking, returns all
      1 , 1 , "a"           %   substrings of String1.
      1 , 2 , "ab"
      2 , 0 , ""
      2 , 1 , "b"
      3 , 0 , ""
      no (more) solution.

    Fail:
      substring("joey",P,L,"joy").
      substring("joey",P,2,"joe").

    Error:
      substring(S1,P,L,S2).                (Error 4).
      substring(S1,1,2,"bc").              (Error 4).
      substring(S1,1,2,'str').             (Error 4).
      substring('string',2,3,S2).          (Error 5).
      substring("string",2,3,'str').       (Error 5).
      substring("string",0,L,S2).          (Error 6).
      substring("string",1,-1,S2).         (Error 6).

## See Also

substring / 3, substring / 5, string_length / 2, split_string / 4