[ Strings and Atoms | Reference Manual | Alphabetic Index ]

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

Succeeds if String2 is a substring of String1 beginning at position Position.

String1
  String.
String2
  String.
Position
  Integer or variable.

## Description

Used to test that String2 is a substring of String1 beginning at position Position. In this case, String1 and String2 are strings and Position is an integer.

Also used to find the first position in String1 that its substring String2 begins. In this case, String1 and String2 are strings and Position is a variable.

String positions must be positive and start at 1.

### Modes and Determinism

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

### Fail Conditions

Fails if String2 is not a substring of String1 beginning at position Position

### Exceptions

(4) instantiation fault
  Either String1 or String2 (or both) are not instantiated.
(5) type error
  Either String1 or String2 (or both) are instantiated, but not to strings.
(5) type error
  Position is neither an integer nor a variable.
(6) out of range
  Position is not a positive integer.

## Examples

    Success:
          substring("str","st",1).
          substring("abcabcabc","bc",X)     (gives X=2).
          substring("abcabcabc","bc",8).
          substring("abc","",X).            (gives X=1).
          substring("abc","",2).
    Fail:
          substring("astring","strg",2).
          substring("","a",X).
    Error:
          substring(S,"str",1).             (Error 4).
          substring('str',S,1).             (Error 5).
          substring("st","s",1.0).          (Error 5).
          substring("ab","a",-2).           (Error 6).

## See Also

substring / 5, split_string / 4