PCRE2_SUBS...GET_BYNAME(3)

💖 NAME 💖

okay so bestie, welcome to the PCRE2 Library Functions Manual page for PCRE2_SUBS...GET_BYNAME(3) ✨ The official NAME line is literally PCRE2 - Perl-compatible regular expressions (revised API). That's the whole vibe: PCRE2, revised API, here to help you regex 💅

🎀 SYNOPSIS 🎀

#include <pcre2.h>

int pcre2_substring_get_byname(pcre2_match_data *match_data,
  PCRE2_SPTR name, PCRE2_UCHAR **bufferptr, PCRE2_SIZE *bufflen);

🦋 DESCRIPTION 🦋

This is a convenience function for extracting a captured substring by name into newly acquired memory. Think: you know the group's name, not its number, and you want that substring copied into fresh memory that belongs to you — main character energy 🫶

The arguments are:

• match_data — the match data for the match
• name — name of the required substring
• bufferptr — where to put the string pointer
• bufflen — where to put the string length

The memory where the substring lands is obtained by calling the same memory allocation function that was used for the match data block. When it is no longer needed, the convenience function pcre2_substring_free() can be used to free it. (Free your fave, bestie, don't ghost that memory 😭)

The yield of the function is zero for success, or one of these error numbers:

• PCRE2_ERROR_NOSUBSTRING — there are no groups of that name
• PCRE2_ERROR_UNAVAILBLE — the ovector was too small for that group
• PCRE2_ERROR_UNSET — the group did not participate in the match
• PCRE2_ERROR_NOMEMORY — memory could not be obtained

If there is more than one group with the given name, the first one that is set is returned. In this situation, PCRE2_ERROR_UNSET means that no group with the given name was set.

There's a complete description of the PCRE2 native API on the pcre2api page, and a description of the POSIX API on the pcre2posix page. Go read those if you want the full lore 📚✨

---

That's the whole page, bestie: PCRE2 10.47, dated 19 December 2014, xoxo 💖