[ Strings and Atoms | 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

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