-*/
-
-/* A failure to find a constant substring means that there is no need to make
- an expensive call to REx engine, thus we celebrate a failure. Similarly,
- finding a substring too deep into the string means that fewer calls to
- regtry() should be needed.
-
- REx compiler's optimizer found 4 possible hints:
- a) Anchored substring;
- b) Fixed substring;
- c) Whether we are anchored (beginning-of-line or \G);
- d) First node (of those at offset 0) which may distinguish positions;
- We use a)b)d) and multiline-part of c), and try to find a position in the
- string which does not contradict any of them.
- */
-
-/* Most of decisions we do here should have been done at compile time.
- The nodes of the REx which we used for the search should have been
- deleted from the finite automaton. */
-
-/* args:
- * rx: the regex to match against
- * sv: the SV being matched: only used for utf8 flag; the string
- * itself is accessed via the pointers below. Note that on
- * something like an overloaded SV, SvPOK(sv) may be false
- * and the string pointers may point to something unrelated to
- * the SV itself.
- * strbeg: real beginning of string
- * strpos: the point in the string at which to begin matching
- * strend: pointer to the byte following the last char of the string
- * flags currently unused; set to 0
- * data: currently unused; set to NULL
+/* re_intuit_start():
+ *
+ * Based on some optimiser hints, try to find the earliest position in the
+ * string where the regex could match.
+ *
+ * rx: the regex to match against
+ * sv: the SV being matched: only used for utf8 flag; the string
+ * itself is accessed via the pointers below. Note that on
+ * something like an overloaded SV, SvPOK(sv) may be false
+ * and the string pointers may point to something unrelated to
+ * the SV itself.
+ * strbeg: real beginning of string
+ * strpos: the point in the string at which to begin matching
+ * strend: pointer to the byte following the last char of the string
+ * flags currently unused; set to 0
+ * data: currently unused; set to NULL
+ *
+ * The basic idea of re_intuit_start() is to use some known information
+ * about the pattern, namely:
+ *
+ * a) the longest known anchored substring (i.e. one that's at a
+ * constant offset from the beginning of the pattern; but not
+ * necessarily at a fixed offset from the beginning of the
+ * string);
+ * b) the longest floating substring (i.e. one that's not at a constant
+ * offset from the beginning of the pattern);
+ * c) Whether the pattern is anchored to the string; either
+ * an absolute anchor: /^../, or anchored to \n: /^.../m,
+ * or anchored to pos(): /\G/;
+ * d) A start class: a real or synthetic character class which
+ * represents which characters are legal at the start of the pattern;
+ *
+ * to either quickly reject the match, or to find the earliest position
+ * within the string at which the pattern might match, thus avoiding
+ * running the full NFA engine at those earlier locations, only to
+ * eventually fail and retry further along.
+ *
+ * Returns NULL if the pattern can't match, or returns the address within
+ * the string which is the earliest place the match could occur.
+ *
+ * The longest of the anchored and floating substrings is called 'check'
+ * and is checked first. The other is called 'other' and is checked
+ * second. The 'other' substring may not be present. For example,
+ *
+ * /(abc|xyz)ABC\d{0,3}DEFG/
+ *
+ * will have
+ *
+ * check substr (float) = "DEFG", offset 6..9 chars
+ * other substr (anchored) = "ABC", offset 3..3 chars
+ * stclass = [ax]
+ *
+ * Be aware that during the course of this function, sometimes 'anchored'
+ * refers to a substring being anchored relative to the start of the
+ * pattern, and sometimes to the pattern itself being anchored relative to
+ * the string. For example:
+ *
+ * /\dabc/: "abc" is anchored to the pattern;
+ * /^\dabc/: "abc" is anchored to the pattern and the string;
+ * /\d+abc/: "abc" is anchored to neither the pattern nor the string;
+ * /^\d+abc/: "abc" is anchored to neither the pattern nor the string,
+ * but the pattern is anchored to the string.