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

# substring(+String, ?Before, ?Length, ?After, ?SubString)

Succeeds if String2 is a substring of String, with length Length, preceded by Before, and followed by After characters

String
  String.
Before
  Integer (from 0 upwards) or variable.
Length
  Integer (from 0 upwards) or variable.
After
  Integer (from 0 upwards) or variable.
SubString
  String or variable.

## Description

Succeeds if String can be split into three substrings, StringL, SubString and StringR, such that Before is the length of StringL, Length is the length of SubString and After is the length of StringR.

On backtracking, all such substrings are found.

Zero length substrings may be specified.

This predicate is very versatile and can be used to

- check for substrings
- extract substrings
- search for substrings

Note: This predicate provides for strings the functionality that the ISO sub_atom/5 predicate provides for atoms.

### Modes and Determinism

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

### Fail Conditions

String cannot be split into substrings of the required lengths, or SubString does not occur within String

### Exceptions

(5) type error
  String is instantiated, but not to a string.
(5) type error
  SubString is neither a string nor a variable.
(5) type error
  Any of Before, Length or After are neither integers nor variables.
(5) type error
  Any of Before, Length or After negative integers.
(4) instantiation fault
  String is not instantiated.

## Examples

    Success:
      substring("abracadabra",0,5,_,S2). (gives S2="abrac").
      substring("abracadabra",_,5,0,S2). (gives S2="dabra").
      substring("abracadabra",3,L,3,S2). (gives L=5, S2="acada").
      substring("abracadabra",B,2,A,ab). (gives B=0, A=9; B=7, A=2).
      substring("Banana",3,2,_,S2).      (gives S2="an").

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

      [eclipse]: substring("charity",B,3,A,S2).
      B=0
      A=4
      S2="cha" More? (;)
      B=1
      A=3
      S2="har" More? (;)
      B=2
      A=2
      S2="ari" More? (;)
      B=3
      A=1
      S2="rit" More? (;)
      B=4
      A=0
      S2="ity"
      yes.

      [eclipse]: substring("abab",B,L,A,S), writeq((B,L,A,S)), nl, fail.
      0, 0, 4, ""           % on backtracking, returns all
      0, 1, 3, "a"          %   substrings of String.
      0, 2, 2, "ab"
      0, 3, 1, "aba"
      0, 4, 0, "abab"
      1, 0, 3, ""
      1, 1, 2, "b"
      1, 2, 1, "ba"
      1, 3, 0, "bab"
      2, 0, 2, ""
      2, 1, 1, "a"
      2, 2, 0, "ab"
      3, 0, 1, ""
      3, 1, 0, "b"
      4, 0, 0, ""
      no (more) solution.

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

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

## See Also

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