Is regular expression search guaranteed to return first match?

Question

I am looking for a method to return the first match of a given regexp in a string. It looks like re.search is exactly the method I am looking for.

However, the documentation is not explicit about whether the first match is guaranteed to be returned from search method.

The documentation claims that the method "scans through string" which suggests to me that it does so from the beginning of the string.

However I need some strong argument. Merely testing that cat1 is found in cat1cat2 is not enough.

The best would be a hint to official documentation or implementation.

Answer 1

I don't want to read through the code for re.search, because there's a lot of it. However, if we look at the code for re.sub, we see that it uses re.search, and re.sub is guaranteed to replace the leftmost occurrence of the pattern. Therefore, re.search must return it.

Relevant code from _sre.c (comments replace lengthy irrelevant code)

static PyObject*
pattern_subx(PatternObject* self, PyObject* ptemplate, PyObject* string,
             Py_ssize_t count, Py_ssize_t subn)
{
    // init stuff...
    while (!count || n < count) {

        state_reset(&state);

        state.ptr = state.start;

        status = sre_search(&state, PatternObject_GetCode(self));
        // Do the replacement...

Edit:

Thanks to @Veedrac opening the issue, the documentation has been clarified to state

Scan through string looking for the first location where the regular expression pattern produces a match, and return a corresponding match object.