# Substring

This function is used to extract a substring of a field or named variable. The extracted substring is saved to a track or named variable.

All supplied text fields may contain any of the escape sequences described in Escape Sequences. Escape Sequences are reevaluated for each processed file.

All indexes are zero based. ie. the first character in a string is at index 0.

An index field which evaluates to be less than zero is treated as relative from the end of the field.

A length field which evaluates to be a negative number is interpreted as to the end of the field.

There are four modes in which a substring can be extracted:

With Index & Length
  The mode returns the characters from a string that are within the adjusted values of index and length.
  examples with a field of abcde

  > index = 1, length = 2 --> bc
  > index = 2, length = -1 --> cde
  > index = -3, length = 2 of --> cd
  > index = 6, length = 1 of --> an empty string
  > index = -7, length = 3 of --> a

To Index
  This mode only specifies an index. All characters up to but not including the character at the adjusted index are returned.
  examples with a field of abcde

  > index = 3 --> abc
  > index = 1 --> a
  > index = 0 --> an empty string
  > index = -2 --> abc
  > index = 10 --> abcde

From Index
  This mode only specifies an index. All characters from the adjusted value of the index to the end of the string are returned.
  examples with a field of abcde

  > index = 3 --> de
  > index = 6 --> an empty string
  > index = -2 --> de
  > index = -10 --> abcde

With Range
  This mode expects the range field to contain index,length. If the comma is not present at runtime the mode is equivalent to the From Index mode. If a comma is present and it is not followed by an integer, the mode is equivalent to the From Index mode. This mode is an efficient means of handling ranges returned by statements such as the Regular Expression statement. Note that unlike most other Yate numeric statements, an empty range will not be treated as 0. An empty range will fail returning the empty string.
  examples with a field of abcde

  > range = 3 --> de
  > range = 3, --> de
  > range = 3,1 --> d
  > range = 2,10 --> cde
  > range = -1,3 --> e
  > range = -3,1 --> c
  > range = 10,2 --> an empty string
  > range = 1,-1 --> bcde
  > range = empty --> empty