The circumflex and dollar metacharacters are zero-width
assertions. That is, they test for a particular condition being
true without consuming any characters from the subject string.
Outside a character class, in the default matching mode, the
circumflex character is an assertion that is true only if the
current matching point is at the start of the subject string. If
the startoffset argument of pcre_exec() is non-zero, circumflex
can never match if the PCRE_MULTILINE option is unset. Inside a
character class, circumflex has an entirely different meaning
(see below).
Circumflex need not be the first character of the pattern if a
number of alternatives are involved, but it should be the first
thing in each alternative in which it appears if the pattern is
ever to match that branch. If all possible alternatives start
with a circumflex, that is, if the pattern is constrained to
match only at the start of the subject, it is said to be an
"anchored" pattern. (There are also other constructs that can
cause a pattern to be anchored.)
The dollar character is an assertion that is true only if the
current matching point is at the end of the subject string, or
immediately before a newline at the end of the string (by
default). Note, however, that it does not actually match the
newline. Dollar need not be the last character of the pattern if
a number of alternatives are involved, but it should be the last
item in any branch in which it appears. Dollar has no special
meaning in a character class.
The meaning of dollar can be changed so that it matches only at
the very end of the string, by setting the PCRE_DOLLAR_ENDONLY
option at compile time. This does not affect the \Z assertion.
The meanings of the circumflex and dollar characters are changed
if the PCRE_MULTILINE option is set. When this is the case, a
circumflex matches immediately after internal newlines as well as
at the start of the subject string. It does not match after a
newline that ends the string. A dollar matches before any
newlines in the string, as well as at the very end, when
PCRE_MULTILINE is set. When newline is specified as the two-
character sequence CRLF, isolated CR and LF characters do not
indicate newlines.
For example, the pattern /^abc$/ matches the subject string
"def\nabc" (where \n represents a newline) in multiline mode, but
not otherwise. Consequently, patterns that are anchored in single
line mode because all branches start with ^ are not anchored in
multiline mode, and a match for circumflex is possible when the
startoffset argument of pcre_exec() is non-zero. The
PCRE_DOLLAR_ENDONLY option is ignored if PCRE_MULTILINE is set.
Note that the sequences \A, \Z, and \z can be used to match the
start and end of the subject in both modes, and if all branches
of a pattern start with \A it is always anchored, whether or not
PCRE_MULTILINE is set.
