
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

Arguments
   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.

Type
   Strings and Atoms

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 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 --- String is instantiated, but not to a string.
     5 --- SubString is neither a string nor a variable.
     5 --- Any of Before, Length or After are neither integers nor variables.
     6 --- Any of Before, Length or After negative integers.
     4 --- 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
