[ Strings and Atoms | Reference Manual | Alphabetic Index ]

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

Succeeds if SubString 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

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

Modes and Determinism

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