PCRE_GET_SUBSTRING_LIST(3)

💖 NAME 💖

PCRE — literally just Perl-compatible regular expressions, bestie, that's the whole vibe 💅

✨ SYNOPSIS ✨

#include <pcre.h>

int pcre_get_substring_list(const char *subject,
     int *ovector, int stringcount, const char ***listptr);

int pcre16_get_substring_list(PCRE_SPTR16 subject,
     int *ovector, int stringcount, PCRE_SPTR16 **listptr);

int pcre32_get_substring_list(PCRE_SPTR32 subject,
     int *ovector, int stringcount, PCRE_SPTR32 **listptr);

Three flavours, one girlboss function: 8-bit, 16-bit, 32-bit. Pick your fighter. 🦋

🌸 DESCRIPTION 🌸

Okay so this one is a convenience function — it's the chill bestie of the PCRE family whose entire job is extracting a whole list of all the captured substrings for you. No cap. 🎀

The arguments are giving:

• subject — the subject that has been successfully matched (yes, successfully, don't be out here passing your failed matches, that's not the move 🙈)
• ovector — the offset vector that pcre[16|32]_exec used
• stringcount — the value returned by pcre[16|32]_exec
• listptr — where to put a pointer to the list

Real talk: the memory where the substrings and the list live is obtained by calling pcre[16|32]_malloc(). And when you're done with it — because you will be done with it, you're not gonna hold onto that memory forever, right? right? — the convenience function pcre[16|32]_free_substring_list() is right there to free it for you. ✨

A pointer to a list of pointers gets put in the variable whose address lives in listptr. And the list is terminated by a NULL pointer, so when you're looping through it, that NULL is your lil' "ok we're done here" signal. 🫶

The yield of the function is:

• zero on success ✨
• PCRE_ERROR_NOMEMORY if sufficient memory could not be obtained 😭

No memory, no party. If you see PCRE_ERROR_NOMEMORY it's literally just telling you the allocation didn't work out — nothing more mysterious than that.

If you want the full tea: there's a complete description of the PCRE native API in the pcreapi page, and a description of the POSIX API in the pcreposix page. Go read those too, they're iconic. 👑

okay that's the whole page, mwah 💋

This one's from PCRE 8.30, dated 24 June 2012 — yeah she's an elder but she still ate, fr fr. 🌈⭐💜