How to match something at the Start and/or End of a line with a regular expression

^alpha

\Aalpha

omega$

omega\Z

^begin

end$

The regular expression tokens ^, $, \A, \Z, and \z are called anchors. They do not match any characters. Instead, they match at certain positions, effectively anchoring the regular expression match at those positions.

A line is the part of the subject text that lies between the start of the subject and a line break, between two line breaks, or between a line break and the end of the subject. If there are no line breaks in the subject, then the whole subject is considered to be one line. Thus, the following text consists of four lines, one each for one, two, an empty string, and four:

one

two



four

The text could be represented in a program as oneLFtwoLFLFfour.

The anchor \A always matches at the very start of the subject text, before the first character. That is the only place where it matches. Place \A at the start of your regular expression to test whether the subject text begins with the text you want to match. The “A” must be uppercase.

Javascript does not support \A.

The anchor ^ is equivalent to \A, as long as you do not turn on the “^ and $ match at line breaks” option. This option is off by default for all regex flavors except Ruby. Ruby does not offer a way to turn this option off.

Unless you’re using Javascript, we recommend that you always use \A instead of ^. The meaning of \A never changes, avoiding any confusion or mistakes in setting regex options.

The anchors \Z and \z always match at the very end of the subject text, after the last character. Place \Z or \z at the end of your regular expression to test whether the subject text ends with the text you want to match.

.NET, Java, PCRE, Perl, and Ruby support both \Z and \z. Python supports only \Z. Javascript does not support \Z or \z at all.

The difference between \Z and \z comes into play when the last character in your subject text is a line break. In that case, \Z can match at the very end of the subject text, after the final line break, as well as immediately before that line break. The benefit is that you can search for omega\Z without having to worry about stripping off a trailing line break at the end of your subject text. When reading a file line by line, some tools include the line break at the end of the line, whereas others don’t; \Z masks this difference. \z matches only at the very end of the subject text, so it will not match text if a trailing line break follows.

The anchor $ is equivalent to \Z, as long as you do not turn on the “^ and $ match at line breaks” option. This option is off by default for all regex flavors except Ruby. Ruby does not offer a way to turn this option off. Just like \Z, $ matches at the very end of the subject text, as well as before the final line break, if any.

To help clarify this subtle and somewhat confusing situation, lets look at an example in Perl. Assuming that $/ (the current record separator) is set to its default \n, the following Perl statement reads a single line from the terminal (standard input):

$line = <>;

Perl leaves the newline on the content of the variable $line. Therefore, an expression such as end●of●input.\z will not match the variable. But end●of●input.\Z and end●of●input.$ will both match, because they ignore the trailing newline.

To make processing easier, Perl programmers often strip newlines with:

chomp $line;

After that operation is performed, all three anchors will match. (Technically, chomp strips a string of the current record separator.)

Unless you’re using Javascript, we recommend that you always use \Z instead of $. The meaning of \Z never changes, avoiding any confusion or mistakes in setting regex options.

By default, ^ matches only at the start of the subject text, just like \A. Only in Ruby does ^ always match at the start of a line. All the other flavors require you to turn on the option to make the caret and dollar sign match at line breaks. This option is typically referred to as “multiline” mode.

Do not confuse this mode with “single line” mode, which would be better known as “dot matches line breaks” mode. “Multiline” mode affects only the caret and dollar sign; “single line” mode affects only the dot.. It is perfectly possible to turn on both “single line” and “multiline” mode at the same time. By default, both options are off.

With the correct option set, ^ will match at the start of each line in the subject text. Strictly speaking, it matches before the very first character in the file, as it always does, and also after each line break character in the subject text. The caret in \n^ is redundant because ^ always matches after \n.

By default, $ matches only at the end of the subject text or before the final line break, just like \Z. Only in Ruby does $ always match at the end of each line. All the other flavors require you to turn on the “multiline” option to make the caret and dollar match at line breaks.

With the correct option set, $ will match at the end of each line in the subject text. (Of course, it also matches after the very last character in the text because that is always the end of a line as well.) The dollar in $\n is redundant because $ always matches before \n.

It is perfectly valid for a regular expression to consist of nothing but one or more anchors. Such a regular expression will find a zero-length match at each position where the anchor can match. If you place several anchors together, all of them need to match at the same position for the regex to match.

You could use such a regular expression in a search-and-replace. Replace \A or \Z to prepend or append something to the whole subject. Replace ^ or $, in “^ and $ match at line breaks” mode, to prepend or append something in each line in the subject text.

Combine two anchors to test for blank lines or missing input. \A\Z matches the empty string, as well as the string that consists of a single newline. \A\z matches only the empty string. ^$, in “^ and $ match at line breaks” mode, matches each empty line in the subject text.