src/external/pcre2-10.32/doc/pcre2_substring_list_get.3

   1 .TH PCRE2_SUBSTRING_LIST_GET 3 "21 October 2014" "PCRE2 10.00"
   2 .SH NAME
   3 PCRE2 - Perl-compatible regular expressions (revised API)
   4 .SH SYNOPSIS
   5 .rs
   6 .sp
   7 .B #include <pcre2.h>
   8 .PP
   9 .nf
  10 .B int pcre2_substring_list_get(pcre2_match_data *\fImatch_data\fP,
  11 .B "  PCRE2_UCHAR ***\fIlistptr\fP, PCRE2_SIZE **\fIlengthsptr\fP);
  12 .fi
  13 .
  14 .SH DESCRIPTION
  15 .rs
  16 .sp
  17 This is a convenience function for extracting all the captured substrings after
  18 a pattern match. It builds a list of pointers to the strings, and (optionally)
  19 a second list that contains their lengths (in code units), excluding a
  20 terminating zero that is added to each of them. All this is done in a single
  21 block of memory that is obtained using the same memory allocation function that
  22 was used to get the match data block. The convenience function
  23 \fBpcre2_substring_list_free()\fP can be used to free it when it is no longer
  24 needed. The arguments are:
  25 .sp
  26   \fImatch_data\fP    The match data block
  27   \fIlistptr\fP       Where to put a pointer to the list
  28   \fIlengthsptr\fP    Where to put a pointer to the lengths, or NULL
  29 .sp
  30 A pointer to a list of pointers is put in the variable whose address is in
  31 \fIlistptr\fP. The list is terminated by a NULL pointer. If \fIlengthsptr\fP is
  32 not NULL, a matching list of lengths is created, and its address is placed in
  33 \fIlengthsptr\fP. The yield of the function is zero on success or
  34 PCRE2_ERROR_NOMEMORY if sufficient memory could not be obtained.
  35 .P
  36 There is a complete description of the PCRE2 native API in the
  37 .\" HREF
  38 \fBpcre2api\fP
  39 .\"
  40 page and a description of the POSIX API in the
  41 .\" HREF
  42 \fBpcre2posix\fP
  43 .\"
  44 page.