Out of curiosity, how does it do that? It kinda just seems to be a complicated boolean in that it either returns None if any group is optional, or returns captures_len which I assume is precomputed?

The Captures::extract method utilizes const generics. So if the number of capture groups that match can vary based on the match, then what happens when fewer groups match than were requested? It's a footgun that can either be prevented by an immediate panic in all cases where that can possibly happen or by meticulous testing to ensure it doesn't happen on any actual inputs. The latter, I think, would make for a bad API. There are alternative API designs, such as making it fallible, but the whole point of Captures::extract is to be a nice ergonomic way to get at capture values. Shoving error handling in there kind of defeats the purpose. It was discussed quite a bit in the issue requesting the Captures::extract feature.

The static_captures_len is what lets us detect whether the number of capture groups can vary depending on the match. If it can, then static_captures_len returns None and Captures::extract will always panic. And in the case where there are an invariant number of matching capture groups, if the number of groups requested doesn't match it, then Captures::extract will always panic as well. In other words, if you use Captures::extract and it doesn't immediately panic, it's guaranteed to be correct for all possible inputs.

To be clear, static_captures_len is a niche routine. But regex needs it to make Captures::extract work sensibly. So that's why it exists. And it has to be exposed in regex-syntax for regex to use it.

The Captures::extract method utilizes const generics.

Ah that does clarify things, the documentation for extract more clearly exposes the relevant case I had not thought of (despite reading the documentation), which is in the examples of static_captures_len but which I skipped over and very much clears the confusion: (a)|(b). In that case static_captures_len does return a Some with a different value than captures_len, which is the part that confused me, my testing (and use cases) mostly centered around having optional groups at the end, so I got either static_captures_len() == None or static_captures_len() == Some(captures_len()), which is why it felt like "a complicated boolean".

This clears things up a lot. Thanks.

To be clear, static_captures_len is a niche routine. But regex needs it to make Captures::extract work sensibly. So that's why it exists. And it has to be exposed in regex-syntax for regex to use it.

Right, but it's also exposed by Regex itself which is where I got it from.

Ahhhh I understand and see the confusion now. Makes sense. Thanks for explaining that!