| <!DOCTYPE html><html lang="en"><head><meta charset="UTF-8"><meta http-equiv="X-UA-Compatible" content="IE=edge"><meta name="viewport" content="width=device-width, initial-scale=1.0"><meta name="generator" content="Asciidoctor 2.0.26"><meta name="description" content="PCRE2's native API"><title>pcre2api(3)</title><link rel="stylesheet" href="./css/document.css"><link rel="stylesheet" href="./css/standalone.css"><meta name="color-scheme" content="light dark"><meta name="theme-color" media="(prefers-color-scheme: light)" content="#0085cc"><meta name="theme-color" media="(prefers-color-scheme: dark)" content="#33b8ff"></head><body class="manpage toc2 toc-right offline-manual"><header class="offline-nav"><nav><a class="offline-index" href="./index.html">Index</a><a class="offline-home" href="https://www.pcre2.org/"><span aria-hidden="true">🌐︎</span> PCRE2 homepage</a></nav></header><main class="document-page"><header class="document-title"><h1>pcre2api(3)</h1><p class="document-meta">PCRE2 10.50-DEV manual; updated <time datetime="2025-12-08">8 Dec 2025</time></p></header><div class="document-layout"><nav id="toc" class="toc2" role="doc-toc"><h2 id="toc-title">Contents</h2><ol class="toc-list level-1"><li><a href="#_description" title="Description">Description</a></li><li><a href="#_pcre2_native_api_basic_functions" title="PCRE2 native API basic functions">PCRE2 native API basic functions</a></li><li><a href="#_pcre2_native_api_auxiliary_match_functions" title="PCRE2 native API auxiliary match functions">PCRE2 native API auxiliary match functions</a></li><li><a href="#_pcre2_native_api_general_context_functions" title="PCRE2 native API general context functions">PCRE2 native API general context functions</a></li><li><a href="#_pcre2_native_api_compile_context_functions" title="PCRE2 native API compile context functions">PCRE2 native API compile context functions</a></li><li><a href="#_pcre2_native_api_match_context_functions" title="PCRE2 native API match context functions">PCRE2 native API match context functions</a></li><li><a href="#_pcre2_native_api_string_extraction_functions" title="PCRE2 native API string extraction functions">PCRE2 native API string extraction functions</a></li><li><a href="#_pcre2_native_api_string_substitution_function" title="PCRE2 native API string substitution function">PCRE2 native API string substitution function</a></li><li><a href="#_pcre2_native_api_jit_functions" title="PCRE2 native API JIT functions">PCRE2 native API JIT functions</a></li><li><a href="#_pcre2_native_api_serialization_functions" title="PCRE2 native API serialization functions">PCRE2 native API serialization functions</a></li><li><a href="#_pcre2_native_api_auxiliary_functions" title="PCRE2 native API auxiliary functions">PCRE2 native API auxiliary functions</a></li><li><a href="#_pcre2_native_api_obsolete_functions" title="PCRE2 native API obsolete functions">PCRE2 native API obsolete functions</a></li><li><a href="#_pcre2_experimental_pattern_conversion_functions" title="PCRE2 experimental pattern conversion functions">PCRE2 experimental pattern conversion functions</a></li><li><a href="#_pcre2_8_bit_16_bit_and_32_bit_libraries" title="PCRE2 8-bit, 16-bit, and 32-bit libraries">PCRE2 8-bit, 16-bit, and 32-bit libraries</a></li><li><a href="#_pcre2_api_overview" title="PCRE2 API overview">PCRE2 API overview</a></li><li><a href="#_string_lengths_and_offsets" title="String lengths and offsets">String lengths and offsets</a></li><li><a href="#_newlines" title="Newlines">Newlines</a></li><li><a href="#_multithreading" title="Multithreading">Multithreading</a><ol class="toc-list level-2"><li><a href="#_the_compiled_pattern" title="The compiled pattern">The compiled pattern</a></li><li><a href="#_context_blocks" title="Context blocks">Context blocks</a></li><li><a href="#_match_blocks" title="Match blocks">Match blocks</a></li></ol></li><li><a href="#pcre2-contexts" title="PCRE2 contexts">PCRE2 contexts</a><ol class="toc-list level-2"><li><a href="#_the_general_context" title="The general context">The general context</a></li><li><a href="#_the_compile_context" title="The compile context">The compile context</a></li><li><a href="#match-context" title="The match context">The match context</a></li></ol></li><li><a href="#_checking_build_time_options" title="Checking build-time options">Checking build-time options</a></li><li><a href="#compiling-a-pattern" title="Compiling a pattern">Compiling a pattern</a><ol class="toc-list level-2"><li><a href="#_main_compile_options" title="Main compile options">Main compile options</a></li><li><a href="#extra-compile-options" title="Extra compile options">Extra compile options</a></li></ol></li><li><a href="#_just_in_time_jit_compilation" title="Just-in-time (JIT) compilation">Just-in-time (JIT) compilation</a></li><li><a href="#locale-support" title="Locale support">Locale support</a><ol class="toc-list level-2"><li><a href="#_saving_locale_tables" title="Saving locale tables">Saving locale tables</a></li></ol></li><li><a href="#information-about-compiled-pattern" title="Information about a compiled pattern">Information about a compiled pattern</a></li><li><a href="#information-about-pattern-callouts" title="Information about a pattern’s callouts">Information about a pattern’s callouts</a></li><li><a href="#_serialization_and_precompiling" title="Serialization and precompiling">Serialization and precompiling</a></li><li><a href="#_the_match_data_block" title="The match data block">The match data block</a></li><li><a href="#_memory_use_for_match_data_blocks" title="Memory use for match data blocks">Memory use for match data blocks</a></li><li><a href="#_matching_a_pattern_the_traditional_function" title="Matching a pattern: the traditional function">Matching a pattern: the traditional function</a><ol class="toc-list level-2"><li><a href="#_the_string_to_be_matched_by_pcre2_match" title="The string to be matched by pcre2_match()">The string to be matched by <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code></a></li><li><a href="#match-option-bits" title="Option bits for pcre2_match()">Option bits for <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code></a></li></ol></li><li><a href="#_newline_handling_when_matching" title="Newline handling when matching">Newline handling when matching</a></li><li><a href="#matched-strings" title="How pcre2_match() returns a string and captured substrings">How <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> returns a string and captured substrings</a></li><li><a href="#other-match-information" title="Other information about a match">Other information about a match</a></li><li><a href="#_error_returns_from_pcre2_match" title="Error returns from pcre2_match()">Error returns from <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code></a></li><li><a href="#_obtaining_a_textual_error_message" title="Obtaining a textual error message">Obtaining a textual error message</a></li><li><a href="#iterating-over-matches" title="Iterating over all matches">Iterating over all matches</a></li><li><a href="#_extracting_captured_substrings_by_number" title="Extracting captured substrings by number">Extracting captured substrings by number</a></li><li><a href="#extracting-substrings-by-name" title="Extracting a list of all captured substrings">Extracting a list of all captured substrings</a></li><li><a href="#_extracting_captured_substrings_by_name" title="Extracting captured substrings by name">Extracting captured substrings by name</a></li><li><a href="#creating-substitution-string" title="Creating a new string with substitutions">Creating a new string with substitutions</a><ol class="toc-list level-2"><li><a href="#_substitution_errors" title="Substitution errors">Substitution errors</a></li><li><a href="#_substitution_callouts" title="Substitution callouts">Substitution callouts</a></li><li><a href="#_substitution_case_callouts" title="Substitution case callouts">Substitution case callouts</a></li></ol></li><li><a href="#_duplicate_capture_group_names" title="Duplicate capture group names">Duplicate capture group names</a></li><li><a href="#_finding_all_possible_matches_at_one_position" title="Finding all possible matches at one position">Finding all possible matches at one position</a></li><li><a href="#_matching_a_pattern_the_alternative_function" title="Matching a pattern: the alternative function">Matching a pattern: the alternative function</a><ol class="toc-list level-2"><li><a href="#_option_bits_for_pcre2_dfa_match" title="Option bits for pcre2_dfa_match()">Option bits for <code class="function pcre2-api rouge"><span class="nf">pcre2_dfa_match()</span></code></a></li><li><a href="#_successful_returns_from_pcre2_dfa_match" title="Successful returns from pcre2_dfa_match()">Successful returns from <code class="function pcre2-api rouge"><span class="nf">pcre2_dfa_match()</span></code></a></li><li><a href="#_error_returns_from_pcre2_dfa_match" title="Error returns from pcre2_dfa_match()">Error returns from <code class="function pcre2-api rouge"><span class="nf">pcre2_dfa_match()</span></code></a></li></ol></li><li><a href="#_see_also" title="See also">See also</a></li></ol></nav><article class="prose" id="content"><section class="doc-section level-1"><h2 id="_description">Description</h2><div class="listing-block prototype"><pre class="rouge highlight"><code data-lang="c"><span class="cp">#include</span> <span class="cpf"><pcre2.h></span></code></pre></div> | |
| <p>PCRE2 is a new API for PCRE, starting at release 10.0. This document contains a | |
| description of all its native functions. See the | |
| <a href="./pcre2.html"><code>pcre2</code></a> | |
| document for an overview of all the PCRE2 documentation.</p></section> | |
| <section class="doc-section level-1"><h2 id="_pcre2_native_api_basic_functions">PCRE2 native API basic functions</h2><div class="listing-block prototype"><pre class="rouge highlight"><code data-lang="c"><span class="kt">pcre2_code</span> <span class="p">*</span><span class="nf">pcre2_compile</span><span class="p">(</span><span class="kt">PCRE2_SPTR</span> <span class="nv">pattern</span><span class="p">,</span> <span class="kt">PCRE2_SIZE</span> <span class="nv">patlen</span><span class="p">,</span> | |
| <span class="kt">uint32_t</span> <span class="nv">options</span><span class="p">,</span> <span class="kt">int</span> <span class="p">*</span><span class="nv">errorptr</span><span class="p">,</span> | |
| <span class="kt">PCRE2_SIZE</span> <span class="p">*</span><span class="nv">erroroffset</span><span class="p">,</span> | |
| <span class="kt">pcre2_compile_context</span> <span class="p">*</span><span class="nv">ccontext</span><span class="p">);</span> | |
| <span class="kt">void</span> <span class="nf">pcre2_code_free</span><span class="p">(</span><span class="kt">pcre2_code</span> <span class="p">*</span><span class="nv">code</span><span class="p">);</span> | |
| <span class="kt">pcre2_match_data</span> <span class="p">*</span><span class="nf">pcre2_match_data_create</span><span class="p">(</span> | |
| <span class="kt">uint32_t</span> <span class="nv">oveccount</span><span class="p">,</span> <span class="kt">pcre2_general_context</span> <span class="p">*</span><span class="nv">gcontext</span><span class="p">);</span> | |
| <span class="kt">pcre2_match_data</span> <span class="p">*</span><span class="nf">pcre2_match_data_create_from_pattern</span><span class="p">(</span> | |
| <span class="kt">const</span> <span class="kt">pcre2_code</span> <span class="p">*</span><span class="nv">code</span><span class="p">,</span> <span class="kt">pcre2_general_context</span> <span class="p">*</span><span class="nv">gcontext</span><span class="p">);</span> | |
| <span class="kt">int</span> <span class="nf">pcre2_match</span><span class="p">(</span><span class="kt">const</span> <span class="kt">pcre2_code</span> <span class="p">*</span><span class="nv">code</span><span class="p">,</span> <span class="kt">PCRE2_SPTR</span> <span class="nv">subject</span><span class="p">,</span> | |
| <span class="kt">PCRE2_SIZE</span> <span class="nv">length</span><span class="p">,</span> <span class="kt">PCRE2_SIZE</span> <span class="nv">start_offset</span><span class="p">,</span> | |
| <span class="kt">uint32_t</span> <span class="nv">options</span><span class="p">,</span> <span class="kt">pcre2_match_data</span> <span class="p">*</span><span class="nv">match_data</span><span class="p">,</span> | |
| <span class="kt">pcre2_match_context</span> <span class="p">*</span><span class="nv">mcontext</span><span class="p">);</span> | |
| <span class="kt">int</span> <span class="nf">pcre2_dfa_match</span><span class="p">(</span><span class="kt">const</span> <span class="kt">pcre2_code</span> <span class="p">*</span><span class="nv">code</span><span class="p">,</span> <span class="kt">PCRE2_SPTR</span> <span class="nv">subject</span><span class="p">,</span> | |
| <span class="kt">PCRE2_SIZE</span> <span class="nv">length</span><span class="p">,</span> <span class="kt">PCRE2_SIZE</span> <span class="nv">start_offset</span><span class="p">,</span> | |
| <span class="kt">uint32_t</span> <span class="nv">options</span><span class="p">,</span> <span class="kt">pcre2_match_data</span> <span class="p">*</span><span class="nv">match_data</span><span class="p">,</span> | |
| <span class="kt">pcre2_match_context</span> <span class="p">*</span><span class="nv">mcontext</span><span class="p">,</span> <span class="kt">int</span> <span class="p">*</span><span class="nv">workspace</span><span class="p">,</span> | |
| <span class="kt">PCRE2_SIZE</span> <span class="nv">wscount</span><span class="p">);</span> | |
| <span class="kt">void</span> <span class="nf">pcre2_match_data_free</span><span class="p">(</span><span class="kt">pcre2_match_data</span> <span class="p">*</span><span class="nv">match_data</span><span class="p">);</span></code></pre></div></section> | |
| <section class="doc-section level-1"><h2 id="_pcre2_native_api_auxiliary_match_functions">PCRE2 native API auxiliary match functions</h2><div class="listing-block prototype"><pre class="rouge highlight"><code data-lang="c"><span class="kt">PCRE2_SPTR</span> <span class="nf">pcre2_get_mark</span><span class="p">(</span><span class="kt">pcre2_match_data</span> <span class="p">*</span><span class="nv">match_data</span><span class="p">);</span> | |
| <span class="kt">PCRE2_SIZE</span> <span class="nf">pcre2_get_match_data_size</span><span class="p">(</span><span class="kt">pcre2_match_data</span> <span class="p">*</span><span class="nv">match_data</span><span class="p">);</span> | |
| <span class="kt">PCRE2_SIZE</span> <span class="nf">pcre2_get_match_data_heapframes_size</span><span class="p">(</span> | |
| <span class="kt">pcre2_match_data</span> <span class="p">*</span><span class="nv">match_data</span><span class="p">);</span> | |
| <span class="kt">uint32_t</span> <span class="nf">pcre2_get_ovector_count</span><span class="p">(</span><span class="kt">pcre2_match_data</span> <span class="p">*</span><span class="nv">match_data</span><span class="p">);</span> | |
| <span class="kt">PCRE2_SIZE</span> <span class="p">*</span><span class="nf">pcre2_get_ovector_pointer</span><span class="p">(</span><span class="kt">pcre2_match_data</span> <span class="p">*</span><span class="nv">match_data</span><span class="p">);</span> | |
| <span class="kt">PCRE2_SIZE</span> <span class="nf">pcre2_get_startchar</span><span class="p">(</span><span class="kt">pcre2_match_data</span> <span class="p">*</span><span class="nv">match_data</span><span class="p">);</span> | |
| <span class="kt">PCRE2_SPTR</span> <span class="nf">pcre2_get_subject</span><span class="p">(</span><span class="kt">pcre2_match_data</span> <span class="p">*</span><span class="nv">match_data</span><span class="p">,</span> | |
| <span class="kt">PCRE2_SIZE</span> <span class="p">*</span><span class="nv">lengthptr</span><span class="p">);</span></code></pre></div></section> | |
| <section class="doc-section level-1"><h2 id="_pcre2_native_api_general_context_functions">PCRE2 native API general context functions</h2><div class="listing-block prototype"><pre class="rouge highlight"><code data-lang="c"><span class="kt">pcre2_general_context</span> <span class="p">*</span><span class="nf">pcre2_general_context_create</span><span class="p">(</span> | |
| <span class="kt">void</span> <span class="p">*</span><span class="p">(</span><span class="p">*</span><span class="nv">private_malloc</span><span class="p">)(</span><span class="kt">size_t</span> <span class="nv">size</span><span class="p">,</span> <span class="kt">void</span> <span class="p">*</span><span class="nv">memory_data</span><span class="p">),</span> | |
| <span class="kt">void</span> <span class="p">(</span><span class="p">*</span><span class="nv">private_free</span><span class="p">)(</span><span class="kt">void</span> <span class="p">*</span><span class="nv">ptr</span><span class="p">,</span> <span class="kt">void</span> <span class="p">*</span><span class="nv">memory_data</span><span class="p">),</span> | |
| <span class="kt">void</span> <span class="p">*</span><span class="nv">memory_data</span><span class="p">);</span> | |
| <span class="kt">pcre2_general_context</span> <span class="p">*</span><span class="nf">pcre2_general_context_copy</span><span class="p">(</span> | |
| <span class="kt">pcre2_general_context</span> <span class="p">*</span><span class="nv">gcontext</span><span class="p">);</span> | |
| <span class="kt">void</span> <span class="nf">pcre2_general_context_free</span><span class="p">(</span><span class="kt">pcre2_general_context</span> <span class="p">*</span><span class="nv">gcontext</span><span class="p">);</span></code></pre></div></section> | |
| <section class="doc-section level-1"><h2 id="_pcre2_native_api_compile_context_functions">PCRE2 native API compile context functions</h2><div class="listing-block prototype"><pre class="rouge highlight"><code data-lang="c"><span class="kt">pcre2_compile_context</span> <span class="p">*</span><span class="nf">pcre2_compile_context_create</span><span class="p">(</span> | |
| <span class="kt">pcre2_general_context</span> <span class="p">*</span><span class="nv">gcontext</span><span class="p">);</span> | |
| <span class="kt">pcre2_compile_context</span> <span class="p">*</span><span class="nf">pcre2_compile_context_copy</span><span class="p">(</span> | |
| <span class="kt">pcre2_compile_context</span> <span class="p">*</span><span class="nv">ccontext</span><span class="p">);</span> | |
| <span class="kt">void</span> <span class="nf">pcre2_compile_context_free</span><span class="p">(</span><span class="kt">pcre2_compile_context</span> <span class="p">*</span><span class="nv">ccontext</span><span class="p">);</span> | |
| <span class="kt">int</span> <span class="nf">pcre2_get_bsr</span><span class="p">(</span><span class="kt">pcre2_compile_context</span> <span class="p">*</span><span class="nv">ccontext</span><span class="p">,</span> <span class="kt">uint32_t</span> <span class="p">*</span><span class="nv">value</span><span class="p">);</span> | |
| <span class="kt">int</span> <span class="nf">pcre2_get_max_pattern_length</span><span class="p">(</span><span class="kt">pcre2_compile_context</span> <span class="p">*</span><span class="nv">ccontext</span><span class="p">,</span> | |
| <span class="kt">PCRE2_SIZE</span> <span class="p">*</span><span class="nv">length</span><span class="p">);</span> | |
| <span class="kt">int</span> <span class="nf">pcre2_get_newline</span><span class="p">(</span><span class="kt">pcre2_compile_context</span> <span class="p">*</span><span class="nv">ccontext</span><span class="p">,</span> | |
| <span class="kt">uint32_t</span> <span class="p">*</span><span class="nv">newline</span><span class="p">);</span> | |
| <span class="kt">int</span> <span class="nf">pcre2_get_parens_nest_limit</span><span class="p">(</span><span class="kt">pcre2_compile_context</span> <span class="p">*</span><span class="nv">ccontext</span><span class="p">,</span> | |
| <span class="kt">uint32_t</span> <span class="p">*</span><span class="nv">limit</span><span class="p">);</span> | |
| <span class="kt">int</span> <span class="nf">pcre2_set_bsr</span><span class="p">(</span><span class="kt">pcre2_compile_context</span> <span class="p">*</span><span class="nv">ccontext</span><span class="p">,</span> <span class="kt">uint32_t</span> <span class="nv">value</span><span class="p">);</span> | |
| <span class="kt">int</span> <span class="nf">pcre2_set_character_tables</span><span class="p">(</span><span class="kt">pcre2_compile_context</span> <span class="p">*</span><span class="nv">ccontext</span><span class="p">,</span> | |
| <span class="kt">const</span> <span class="kt">uint8_t</span> <span class="p">*</span><span class="nv">tables</span><span class="p">);</span> | |
| <span class="kt">int</span> <span class="nf">pcre2_set_compile_extra_options</span><span class="p">(</span><span class="kt">pcre2_compile_context</span> <span class="p">*</span><span class="nv">ccontext</span><span class="p">,</span> | |
| <span class="kt">uint32_t</span> <span class="nv">options</span><span class="p">);</span> | |
| <span class="kt">int</span> <span class="nf">pcre2_set_max_pattern_length</span><span class="p">(</span><span class="kt">pcre2_compile_context</span> <span class="p">*</span><span class="nv">ccontext</span><span class="p">,</span> | |
| <span class="kt">PCRE2_SIZE</span> <span class="nv">length</span><span class="p">);</span> | |
| <span class="kt">int</span> <span class="nf">pcre2_set_max_pattern_compiled_length</span><span class="p">(</span> | |
| <span class="kt">pcre2_compile_context</span> <span class="p">*</span><span class="nv">ccontext</span><span class="p">,</span> <span class="kt">PCRE2_SIZE</span> <span class="nv">length</span><span class="p">);</span> | |
| <span class="kt">int</span> <span class="nf">pcre2_set_max_varlookbehind</span><span class="p">(</span><span class="kt">pcre2_compile_context</span> <span class="p">*</span><span class="nv">ccontext</span><span class="p">,</span> | |
| <span class="kt">uint32_t</span> <span class="nv">limit</span><span class="p">);</span> | |
| <span class="kt">int</span> <span class="nf">pcre2_set_newline</span><span class="p">(</span><span class="kt">pcre2_compile_context</span> <span class="p">*</span><span class="nv">ccontext</span><span class="p">,</span> | |
| <span class="kt">uint32_t</span> <span class="nv">newline</span><span class="p">);</span> | |
| <span class="kt">int</span> <span class="nf">pcre2_set_parens_nest_limit</span><span class="p">(</span><span class="kt">pcre2_compile_context</span> <span class="p">*</span><span class="nv">ccontext</span><span class="p">,</span> | |
| <span class="kt">uint32_t</span> <span class="nv">limit</span><span class="p">);</span> | |
| <span class="kt">int</span> <span class="nf">pcre2_set_compile_recursion_guard</span><span class="p">(</span><span class="kt">pcre2_compile_context</span> <span class="p">*</span><span class="nv">ccontext</span><span class="p">,</span> | |
| <span class="kt">int</span> <span class="p">(</span><span class="p">*</span><span class="nv">guard</span><span class="p">)(</span><span class="kt">uint32_t</span> <span class="nv">depth</span><span class="p">,</span> | |
| <span class="kt">void</span> <span class="p">*</span><span class="nv">user_data</span><span class="p">),</span> | |
| <span class="kt">void</span> <span class="p">*</span><span class="nv">user_data</span><span class="p">);</span> | |
| <span class="kt">int</span> <span class="nf">pcre2_set_optimize</span><span class="p">(</span><span class="kt">pcre2_compile_context</span> <span class="p">*</span><span class="nv">ccontext</span><span class="p">,</span> | |
| <span class="kt">uint32_t</span> <span class="nv">directive</span><span class="p">);</span></code></pre></div></section> | |
| <section class="doc-section level-1"><h2 id="_pcre2_native_api_match_context_functions">PCRE2 native API match context functions</h2><div class="listing-block prototype"><pre class="rouge highlight"><code data-lang="c"><span class="kt">pcre2_match_context</span> <span class="p">*</span><span class="nf">pcre2_match_context_create</span><span class="p">(</span> | |
| <span class="kt">pcre2_general_context</span> <span class="p">*</span><span class="nv">gcontext</span><span class="p">);</span> | |
| <span class="kt">pcre2_match_context</span> <span class="p">*</span><span class="nf">pcre2_match_context_copy</span><span class="p">(</span> | |
| <span class="kt">pcre2_match_context</span> <span class="p">*</span><span class="nv">mcontext</span><span class="p">);</span> | |
| <span class="kt">void</span> <span class="nf">pcre2_match_context_free</span><span class="p">(</span><span class="kt">pcre2_match_context</span> <span class="p">*</span><span class="nv">mcontext</span><span class="p">);</span> | |
| <span class="kt">int</span> <span class="nf">pcre2_get_heap_limit</span><span class="p">(</span><span class="kt">pcre2_match_context</span> <span class="p">*</span><span class="nv">mcontext</span><span class="p">,</span> | |
| <span class="kt">uint32_t</span> <span class="p">*</span><span class="nv">limit</span><span class="p">);</span> | |
| <span class="kt">int</span> <span class="nf">pcre2_get_match_limit</span><span class="p">(</span><span class="kt">pcre2_match_context</span> <span class="p">*</span><span class="nv">mcontext</span><span class="p">,</span> | |
| <span class="kt">uint32_t</span> <span class="p">*</span><span class="nv">limit</span><span class="p">);</span> | |
| <span class="kt">int</span> <span class="nf">pcre2_get_depth_limit</span><span class="p">(</span><span class="kt">pcre2_match_context</span> <span class="p">*</span><span class="nv">mcontext</span><span class="p">,</span> | |
| <span class="kt">uint32_t</span> <span class="p">*</span><span class="nv">limit</span><span class="p">);</span> | |
| <span class="kt">int</span> <span class="nf">pcre2_get_offset_limit</span><span class="p">(</span><span class="kt">pcre2_match_context</span> <span class="p">*</span><span class="nv">mcontext</span><span class="p">,</span> | |
| <span class="kt">PCRE2_SIZE</span> <span class="p">*</span><span class="nv">limit</span><span class="p">);</span> | |
| <span class="kt">int</span> <span class="nf">pcre2_set_callout</span><span class="p">(</span><span class="kt">pcre2_match_context</span> <span class="p">*</span><span class="nv">mcontext</span><span class="p">,</span> | |
| <span class="kt">int</span> <span class="p">(</span><span class="p">*</span><span class="nv">callout</span><span class="p">)(</span> | |
| <span class="kt">pcre2_callout_block</span> <span class="p">*</span><span class="nv">callout_block</span><span class="p">,</span> | |
| <span class="kt">void</span> <span class="p">*</span><span class="nv">callout_data</span><span class="p">),</span> | |
| <span class="kt">void</span> <span class="p">*</span><span class="nv">callout_data</span><span class="p">);</span> | |
| <span class="kt">int</span> <span class="nf">pcre2_set_substitute_callout</span><span class="p">(</span> | |
| <span class="kt">pcre2_match_context</span> <span class="p">*</span><span class="nv">mcontext</span><span class="p">,</span> | |
| <span class="kt">int</span> <span class="p">(</span><span class="p">*</span><span class="nv">substitute_callout</span><span class="p">)(</span> | |
| <span class="kt">pcre2_substitute_callout_block</span> <span class="p">*</span><span class="nv">callout_block</span><span class="p">,</span> | |
| <span class="kt">void</span> <span class="p">*</span><span class="nv">substitute_callout_data</span><span class="p">),</span> | |
| <span class="kt">void</span> <span class="p">*</span><span class="nv">substitute_callout_data</span><span class="p">);</span> | |
| <span class="kt">int</span> <span class="nf">pcre2_set_substitute_case_callout</span><span class="p">(</span> | |
| <span class="kt">pcre2_match_context</span> <span class="p">*</span><span class="nv">mcontext</span><span class="p">,</span> | |
| <span class="nf">PCRE2_SIZE</span> <span class="p">(</span><span class="p">*</span><span class="nv">substitute_case_callout</span><span class="p">)(</span> | |
| <span class="kt">PCRE2_SPTR</span> <span class="nv">input</span><span class="p">,</span> <span class="kt">PCRE2_SIZE</span> <span class="nv">input_length</span><span class="p">,</span> | |
| <span class="kt">PCRE2_UCHAR</span> <span class="p">*</span><span class="nv">output</span><span class="p">,</span> <span class="kt">PCRE2_SIZE</span> <span class="nv">output_capacity</span><span class="p">,</span> | |
| <span class="kt">int</span> <span class="nv">case_operation</span><span class="p">,</span> <span class="kt">void</span> <span class="p">*</span><span class="nv">substitute_case_callout_data</span><span class="p">),</span> | |
| <span class="kt">void</span> <span class="p">*</span><span class="nv">substitute_case_callout_data</span><span class="p">);</span> | |
| <span class="kt">int</span> <span class="nf">pcre2_set_offset_limit</span><span class="p">(</span><span class="kt">pcre2_match_context</span> <span class="p">*</span><span class="nv">mcontext</span><span class="p">,</span> | |
| <span class="kt">PCRE2_SIZE</span> <span class="nv">limit</span><span class="p">);</span> | |
| <span class="kt">int</span> <span class="nf">pcre2_set_heap_limit</span><span class="p">(</span><span class="kt">pcre2_match_context</span> <span class="p">*</span><span class="nv">mcontext</span><span class="p">,</span> | |
| <span class="kt">uint32_t</span> <span class="nv">limit</span><span class="p">);</span> | |
| <span class="kt">int</span> <span class="nf">pcre2_set_match_limit</span><span class="p">(</span><span class="kt">pcre2_match_context</span> <span class="p">*</span><span class="nv">mcontext</span><span class="p">,</span> | |
| <span class="kt">uint32_t</span> <span class="nv">limit</span><span class="p">);</span> | |
| <span class="kt">int</span> <span class="nf">pcre2_set_depth_limit</span><span class="p">(</span><span class="kt">pcre2_match_context</span> <span class="p">*</span><span class="nv">mcontext</span><span class="p">,</span> | |
| <span class="kt">uint32_t</span> <span class="nv">limit</span><span class="p">);</span></code></pre></div></section> | |
| <section class="doc-section level-1"><h2 id="_pcre2_native_api_string_extraction_functions">PCRE2 native API string extraction functions</h2><div class="listing-block prototype"><pre class="rouge highlight"><code data-lang="c"><span class="kt">int</span> <span class="nf">pcre2_substring_copy_byname</span><span class="p">(</span><span class="kt">pcre2_match_data</span> <span class="p">*</span><span class="nv">match_data</span><span class="p">,</span> | |
| <span class="kt">PCRE2_SPTR</span> <span class="nv">stringname</span><span class="p">,</span> | |
| <span class="kt">PCRE2_UCHAR</span> <span class="p">*</span><span class="nv">buffer</span><span class="p">,</span> | |
| <span class="kt">PCRE2_SIZE</span> <span class="p">*</span><span class="nv">sizeptr</span><span class="p">);</span> | |
| <span class="kt">int</span> <span class="nf">pcre2_substring_copy_bynumber</span><span class="p">(</span><span class="kt">pcre2_match_data</span> <span class="p">*</span><span class="nv">match_data</span><span class="p">,</span> | |
| <span class="kt">uint32_t</span> <span class="nv">stringnumber</span><span class="p">,</span> | |
| <span class="kt">PCRE2_UCHAR</span> <span class="p">*</span><span class="nv">buffer</span><span class="p">,</span> | |
| <span class="kt">PCRE2_SIZE</span> <span class="p">*</span><span class="nv">sizeptr</span><span class="p">);</span> | |
| <span class="kt">void</span> <span class="nf">pcre2_substring_free</span><span class="p">(</span><span class="kt">PCRE2_UCHAR</span> <span class="p">*</span><span class="nv">string</span><span class="p">);</span> | |
| <span class="kt">int</span> <span class="nf">pcre2_substring_get_byname</span><span class="p">(</span><span class="kt">pcre2_match_data</span> <span class="p">*</span><span class="nv">match_data</span><span class="p">,</span> | |
| <span class="kt">PCRE2_SPTR</span> <span class="nv">stringname</span><span class="p">,</span> | |
| <span class="kt">PCRE2_UCHAR</span> <span class="p">*</span><span class="p">*</span><span class="nv">stringptr</span><span class="p">,</span> | |
| <span class="kt">PCRE2_SIZE</span> <span class="p">*</span><span class="nv">sizeptr</span><span class="p">);</span> | |
| <span class="kt">int</span> <span class="nf">pcre2_substring_get_bynumber</span><span class="p">(</span><span class="kt">pcre2_match_data</span> <span class="p">*</span><span class="nv">match_data</span><span class="p">,</span> | |
| <span class="kt">uint32_t</span> <span class="nv">stringnumber</span><span class="p">,</span> | |
| <span class="kt">PCRE2_UCHAR</span> <span class="p">*</span><span class="p">*</span><span class="nv">stringptr</span><span class="p">,</span> | |
| <span class="kt">PCRE2_SIZE</span> <span class="p">*</span><span class="nv">sizeptr</span><span class="p">);</span> | |
| <span class="kt">int</span> <span class="nf">pcre2_substring_length_byname</span><span class="p">(</span><span class="kt">pcre2_match_data</span> <span class="p">*</span><span class="nv">match_data</span><span class="p">,</span> | |
| <span class="kt">PCRE2_SPTR</span> <span class="nv">stringname</span><span class="p">,</span> | |
| <span class="kt">PCRE2_SIZE</span> <span class="p">*</span><span class="nv">sizeptr</span><span class="p">);</span> | |
| <span class="kt">int</span> <span class="nf">pcre2_substring_length_bynumber</span><span class="p">(</span><span class="kt">pcre2_match_data</span> <span class="p">*</span><span class="nv">match_data</span><span class="p">,</span> | |
| <span class="kt">uint32_t</span> <span class="nv">stringnumber</span><span class="p">,</span> | |
| <span class="kt">PCRE2_SIZE</span> <span class="p">*</span><span class="nv">sizeptr</span><span class="p">);</span> | |
| <span class="kt">int</span> <span class="nf">pcre2_substring_nametable_scan</span><span class="p">(</span><span class="kt">const</span> <span class="kt">pcre2_code</span> <span class="p">*</span><span class="nv">code</span><span class="p">,</span> | |
| <span class="kt">PCRE2_SPTR</span> <span class="nv">stringname</span><span class="p">,</span> | |
| <span class="kt">PCRE2_SPTR</span> <span class="p">*</span><span class="nv">firstptr</span><span class="p">,</span> | |
| <span class="kt">PCRE2_SPTR</span> <span class="p">*</span><span class="nv">lastptr</span><span class="p">);</span> | |
| <span class="kt">int</span> <span class="nf">pcre2_substring_number_from_name</span><span class="p">(</span><span class="kt">const</span> <span class="kt">pcre2_code</span> <span class="p">*</span><span class="nv">code</span><span class="p">,</span> | |
| <span class="kt">PCRE2_SPTR</span> <span class="nv">stringname</span><span class="p">);</span> | |
| <span class="kt">void</span> <span class="nf">pcre2_substring_list_free</span><span class="p">(</span><span class="kt">PCRE2_UCHAR</span> <span class="p">*</span><span class="p">*</span><span class="nv">list</span><span class="p">);</span> | |
| <span class="kt">int</span> <span class="nf">pcre2_substring_list_get</span><span class="p">(</span><span class="kt">pcre2_match_data</span> <span class="p">*</span><span class="nv">match_data</span><span class="p">,</span> | |
| <span class="kt">PCRE2_UCHAR</span> <span class="p">*</span><span class="p">*</span><span class="p">*</span><span class="nv">listptr</span><span class="p">,</span> | |
| <span class="kt">PCRE2_SIZE</span> <span class="p">*</span><span class="p">*</span><span class="nv">lengthsptr</span><span class="p">);</span></code></pre></div></section> | |
| <section class="doc-section level-1"><h2 id="_pcre2_native_api_string_substitution_function">PCRE2 native API string substitution function</h2><div class="listing-block prototype"><pre class="rouge highlight"><code data-lang="c"><span class="kt">int</span> <span class="nf">pcre2_substitute</span><span class="p">(</span><span class="kt">const</span> <span class="kt">pcre2_code</span> <span class="p">*</span><span class="nv">code</span><span class="p">,</span> <span class="kt">PCRE2_SPTR</span> <span class="nv">subject</span><span class="p">,</span> | |
| <span class="kt">PCRE2_SIZE</span> <span class="nv">length</span><span class="p">,</span> <span class="kt">PCRE2_SIZE</span> <span class="nv">start_offset</span><span class="p">,</span> | |
| <span class="kt">uint32_t</span> <span class="nv">options</span><span class="p">,</span> <span class="kt">pcre2_match_data</span> <span class="p">*</span><span class="nv">match_data</span><span class="p">,</span> | |
| <span class="kt">pcre2_match_context</span> <span class="p">*</span><span class="nv">mcontext</span><span class="p">,</span> | |
| <span class="kt">PCRE2_SPTR</span> <span class="nv">replacement</span><span class="p">,</span> <span class="kt">PCRE2_SIZE</span> <span class="nv">rlength</span><span class="p">,</span> | |
| <span class="kt">PCRE2_UCHAR</span> <span class="p">*</span><span class="nv">buffer</span><span class="p">,</span> <span class="kt">PCRE2_SIZE</span> <span class="p">*</span><span class="nv">blength</span><span class="p">);</span></code></pre></div></section> | |
| <section class="doc-section level-1"><h2 id="_pcre2_native_api_jit_functions">PCRE2 native API JIT functions</h2><div class="listing-block prototype"><pre class="rouge highlight"><code data-lang="c"><span class="kt">int</span> <span class="nf">pcre2_jit_compile</span><span class="p">(</span><span class="kt">pcre2_code</span> <span class="p">*</span><span class="nv">code</span><span class="p">,</span> <span class="kt">uint32_t</span> <span class="nv">options</span><span class="p">);</span> | |
| <span class="kt">int</span> <span class="nf">pcre2_jit_match</span><span class="p">(</span><span class="kt">const</span> <span class="kt">pcre2_code</span> <span class="p">*</span><span class="nv">code</span><span class="p">,</span> <span class="kt">PCRE2_SPTR</span> <span class="nv">subject</span><span class="p">,</span> | |
| <span class="kt">PCRE2_SIZE</span> <span class="nv">length</span><span class="p">,</span> <span class="kt">PCRE2_SIZE</span> <span class="nv">start_offset</span><span class="p">,</span> | |
| <span class="kt">uint32_t</span> <span class="nv">options</span><span class="p">,</span> <span class="kt">pcre2_match_data</span> <span class="p">*</span><span class="nv">match_data</span><span class="p">,</span> | |
| <span class="kt">pcre2_match_context</span> <span class="p">*</span><span class="nv">mcontext</span><span class="p">);</span> | |
| <span class="kt">void</span> <span class="nf">pcre2_jit_free_unused_memory</span><span class="p">(</span><span class="kt">pcre2_general_context</span> <span class="p">*</span><span class="nv">gcontext</span><span class="p">);</span> | |
| <span class="kt">pcre2_jit_stack</span> <span class="p">*</span><span class="nf">pcre2_jit_stack_create</span><span class="p">(</span> | |
| <span class="kt">size_t</span> <span class="nv">startsize</span><span class="p">,</span> <span class="kt">size_t</span> <span class="nv">maxsize</span><span class="p">,</span> | |
| <span class="kt">pcre2_general_context</span> <span class="p">*</span><span class="nv">gcontext</span><span class="p">);</span> | |
| <span class="kt">void</span> <span class="nf">pcre2_jit_stack_assign</span><span class="p">(</span><span class="kt">pcre2_match_context</span> <span class="p">*</span><span class="nv">mcontext</span><span class="p">,</span> | |
| <span class="kt">pcre2_jit_callback</span> <span class="nv">callback</span><span class="p">,</span> | |
| <span class="kt">void</span> <span class="p">*</span><span class="nv">callback_data</span><span class="p">);</span> | |
| <span class="kt">void</span> <span class="nf">pcre2_jit_stack_free</span><span class="p">(</span><span class="kt">pcre2_jit_stack</span> <span class="p">*</span><span class="nv">jit_stack</span><span class="p">);</span></code></pre></div></section> | |
| <section class="doc-section level-1"><h2 id="_pcre2_native_api_serialization_functions">PCRE2 native API serialization functions</h2><div class="listing-block prototype"><pre class="rouge highlight"><code data-lang="c"><span class="kt">int32_t</span> <span class="nf">pcre2_serialize_decode</span><span class="p">(</span><span class="kt">pcre2_code</span> <span class="p">*</span><span class="p">*</span><span class="nv">codes</span><span class="p">,</span> | |
| <span class="kt">int32_t</span> <span class="nv">number_of_codes</span><span class="p">,</span> | |
| <span class="kt">const</span> <span class="kt">uint8_t</span> <span class="p">*</span><span class="nv">bytes</span><span class="p">,</span> | |
| <span class="kt">pcre2_general_context</span> <span class="p">*</span><span class="nv">gcontext</span><span class="p">);</span> | |
| <span class="kt">int32_t</span> <span class="nf">pcre2_serialize_encode</span><span class="p">(</span><span class="kt">const</span> <span class="kt">pcre2_code</span> <span class="p">*</span><span class="p">*</span><span class="nv">codes</span><span class="p">,</span> | |
| <span class="kt">int32_t</span> <span class="nv">number_of_codes</span><span class="p">,</span> | |
| <span class="kt">uint8_t</span> <span class="p">*</span><span class="p">*</span><span class="nv">serialized_bytes</span><span class="p">,</span> | |
| <span class="kt">PCRE2_SIZE</span> <span class="p">*</span><span class="nv">serialized_size</span><span class="p">,</span> | |
| <span class="kt">pcre2_general_context</span> <span class="p">*</span><span class="nv">gcontext</span><span class="p">);</span> | |
| <span class="kt">void</span> <span class="nf">pcre2_serialize_free</span><span class="p">(</span><span class="kt">uint8_t</span> <span class="p">*</span><span class="nv">bytes</span><span class="p">);</span> | |
| <span class="kt">int32_t</span> <span class="nf">pcre2_serialize_get_number_of_codes</span><span class="p">(</span><span class="kt">const</span> <span class="kt">uint8_t</span> <span class="p">*</span><span class="nv">bytes</span><span class="p">);</span></code></pre></div></section> | |
| <section class="doc-section level-1"><h2 id="_pcre2_native_api_auxiliary_functions">PCRE2 native API auxiliary functions</h2><div class="listing-block prototype"><pre class="rouge highlight"><code data-lang="c"><span class="kt">pcre2_code</span> <span class="p">*</span><span class="nf">pcre2_code_copy</span><span class="p">(</span><span class="kt">const</span> <span class="kt">pcre2_code</span> <span class="p">*</span><span class="nv">code</span><span class="p">);</span> | |
| <span class="kt">pcre2_code</span> <span class="p">*</span><span class="nf">pcre2_code_copy_with_tables</span><span class="p">(</span><span class="kt">const</span> <span class="kt">pcre2_code</span> <span class="p">*</span><span class="nv">code</span><span class="p">);</span> | |
| <span class="kt">int</span> <span class="nf">pcre2_get_error_message</span><span class="p">(</span><span class="kt">int</span> <span class="nv">errorcode</span><span class="p">,</span> <span class="kt">PCRE2_UCHAR</span> <span class="p">*</span><span class="nv">buffer</span><span class="p">,</span> | |
| <span class="kt">PCRE2_SIZE</span> <span class="nv">bufflen</span><span class="p">);</span> | |
| <span class="kt">const</span> <span class="kt">uint8_t</span> <span class="p">*</span><span class="nf">pcre2_maketables</span><span class="p">(</span><span class="kt">pcre2_general_context</span> <span class="p">*</span><span class="nv">gcontext</span><span class="p">);</span> | |
| <span class="kt">void</span> <span class="nf">pcre2_maketables_free</span><span class="p">(</span><span class="kt">pcre2_general_context</span> <span class="p">*</span><span class="nv">gcontext</span><span class="p">,</span> | |
| <span class="kt">const</span> <span class="kt">uint8_t</span> <span class="p">*</span><span class="nv">tables</span><span class="p">);</span> | |
| <span class="kt">int</span> <span class="nf">pcre2_pattern_info</span><span class="p">(</span><span class="kt">const</span> <span class="kt">pcre2_code</span> <span class="p">*</span><span class="nv">code</span><span class="p">,</span> <span class="kt">uint32_t</span> <span class="nv">what</span><span class="p">,</span> | |
| <span class="kt">void</span> <span class="p">*</span><span class="nv">where</span><span class="p">);</span> | |
| <span class="kt">int</span> <span class="nf">pcre2_callout_enumerate</span><span class="p">(</span> | |
| <span class="kt">const</span> <span class="kt">pcre2_code</span> <span class="p">*</span><span class="nv">code</span><span class="p">,</span> | |
| <span class="kt">int</span> <span class="p">(</span><span class="p">*</span><span class="nv">callback</span><span class="p">)(</span><span class="kt">pcre2_callout_enumerate_block</span> <span class="p">*</span><span class="nv">callout_block</span><span class="p">,</span> | |
| <span class="kt">void</span> <span class="p">*</span><span class="nv">callout_data</span><span class="p">),</span> | |
| <span class="kt">void</span> <span class="p">*</span><span class="nv">callout_data</span><span class="p">);</span> | |
| <span class="kt">int</span> <span class="nf">pcre2_config</span><span class="p">(</span><span class="kt">uint32_t</span> <span class="nv">what</span><span class="p">,</span> <span class="kt">void</span> <span class="p">*</span><span class="nv">where</span><span class="p">);</span></code></pre></div></section> | |
| <section class="doc-section level-1"><h2 id="_pcre2_native_api_obsolete_functions">PCRE2 native API obsolete functions</h2><div class="listing-block prototype"><pre class="rouge highlight"><code data-lang="c"><span class="kt">int</span> <span class="nf">pcre2_set_recursion_limit</span><span class="p">(</span><span class="kt">pcre2_match_context</span> <span class="p">*</span><span class="nv">mcontext</span><span class="p">,</span> | |
| <span class="kt">uint32_t</span> <span class="nv">limit</span><span class="p">);</span> | |
| <span class="kt">int</span> <span class="nf">pcre2_set_recursion_memory_management</span><span class="p">(</span> | |
| <span class="kt">pcre2_match_context</span> <span class="p">*</span><span class="nv">mcontext</span><span class="p">,</span> | |
| <span class="kt">void</span> <span class="p">*</span><span class="p">(</span><span class="p">*</span><span class="nv">mymalloc</span><span class="p">)(</span><span class="kt">size_t</span> <span class="nv">size</span><span class="p">,</span> <span class="kt">void</span> <span class="p">*</span><span class="nv">mydata</span><span class="p">),</span> | |
| <span class="kt">void</span> <span class="p">(</span><span class="p">*</span><span class="nv">myfree</span><span class="p">)(</span><span class="kt">void</span> <span class="p">*</span><span class="nv">ptr</span><span class="p">,</span> <span class="kt">void</span> <span class="p">*</span><span class="nv">mydata</span><span class="p">),</span> | |
| <span class="kt">void</span> <span class="p">*</span><span class="nv">mydata</span><span class="p">);</span></code></pre></div> | |
| <p>These functions became obsolete at release 10.30 and are retained only for | |
| backward compatibility. They should not be used in new code. The first is | |
| replaced by <code class="function pcre2-api rouge"><span class="nf">pcre2_set_depth_limit()</span></code>; the second is no longer needed and | |
| has no effect (it always returns zero).</p></section> | |
| <section class="doc-section level-1"><h2 id="_pcre2_experimental_pattern_conversion_functions">PCRE2 experimental pattern conversion functions</h2><div class="listing-block prototype"><pre class="rouge highlight"><code data-lang="c"><span class="kt">pcre2_convert_context</span> <span class="p">*</span><span class="nf">pcre2_convert_context_create</span><span class="p">(</span> | |
| <span class="kt">pcre2_general_context</span> <span class="p">*</span><span class="nv">gcontext</span><span class="p">);</span> | |
| <span class="kt">pcre2_convert_context</span> <span class="p">*</span><span class="nf">pcre2_convert_context_copy</span><span class="p">(</span> | |
| <span class="kt">pcre2_convert_context</span> <span class="p">*</span><span class="nv">ccontext</span><span class="p">);</span> | |
| <span class="kt">void</span> <span class="nf">pcre2_convert_context_free</span><span class="p">(</span><span class="kt">pcre2_convert_context</span> <span class="p">*</span><span class="nv">ccontext</span><span class="p">);</span> | |
| <span class="kt">int</span> <span class="nf">pcre2_set_glob_escape</span><span class="p">(</span><span class="kt">pcre2_convert_context</span> <span class="p">*</span><span class="nv">ccontext</span><span class="p">,</span> | |
| <span class="kt">uint32_t</span> <span class="nv">escape_char</span><span class="p">);</span> | |
| <span class="kt">int</span> <span class="nf">pcre2_set_glob_separator</span><span class="p">(</span><span class="kt">pcre2_convert_context</span> <span class="p">*</span><span class="nv">ccontext</span><span class="p">,</span> | |
| <span class="kt">uint32_t</span> <span class="nv">separator_char</span><span class="p">);</span> | |
| <span class="kt">int</span> <span class="nf">pcre2_pattern_convert</span><span class="p">(</span><span class="kt">PCRE2_SPTR</span> <span class="nv">pattern</span><span class="p">,</span> <span class="kt">PCRE2_SIZE</span> <span class="nv">plength</span><span class="p">,</span> | |
| <span class="kt">uint32_t</span> <span class="nv">options</span><span class="p">,</span> <span class="kt">PCRE2_UCHAR</span> <span class="p">*</span><span class="p">*</span><span class="nv">buffptr</span><span class="p">,</span> | |
| <span class="kt">PCRE2_SIZE</span> <span class="p">*</span><span class="nv">bufflenptr</span><span class="p">,</span> | |
| <span class="kt">pcre2_convert_context</span> <span class="p">*</span><span class="nv">ccontext</span><span class="p">);</span> | |
| <span class="kt">void</span> <span class="nf">pcre2_converted_pattern_free</span><span class="p">(</span><span class="kt">PCRE2_UCHAR</span> <span class="p">*</span><span class="nv">converted</span><span class="p">);</span></code></pre></div> | |
| <p>These functions provide a way of converting non-PCRE2 patterns into | |
| patterns that can be processed by <code class="function pcre2-api rouge"><span class="nf">pcre2_compile()</span></code>. This facility is | |
| experimental and may be changed in future releases. At present, "globs" and | |
| POSIX basic and extended patterns can be converted. Details are given in the | |
| <a href="./pcre2convert.html"><code>pcre2convert</code></a> | |
| documentation.</p></section> | |
| <section class="doc-section level-1"><h2 id="_pcre2_8_bit_16_bit_and_32_bit_libraries">PCRE2 8-bit, 16-bit, and 32-bit libraries</h2><p>There are three PCRE2 libraries, supporting 8-bit, 16-bit, and 32-bit code | |
| units, respectively. However, there is just one header file, <code>pcre2.h</code>. | |
| This contains the function prototypes and other definitions for all three | |
| libraries. One, two, or all three can be installed simultaneously. On Unix-like | |
| systems the libraries are called <code>libpcre2-8</code>, <code>libpcre2-16</code>, and | |
| <code>libpcre2-32</code>, and they can also co-exist with the original PCRE libraries. | |
| Every PCRE2 function comes in three different forms, one for each library, for | |
| example:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="c"><span class="nf">pcre2_compile_8</span><span class="p">()</span> | |
| <span class="nf">pcre2_compile_16</span><span class="p">()</span> | |
| <span class="nf">pcre2_compile_32</span><span class="p">()</span></code></pre></div> | |
| <p>There are also three different sets of data types:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="c"><span class="kt">PCRE2_UCHAR8</span><span class="p">,</span> <span class="kt">PCRE2_UCHAR16</span><span class="p">,</span> <span class="kt">PCRE2_UCHAR32</span> | |
| <span class="kt">PCRE2_SPTR8</span><span class="p">,</span> <span class="kt">PCRE2_SPTR16</span><span class="p">,</span> <span class="kt">PCRE2_SPTR32</span></code></pre></div> | |
| <p>The UCHAR types define unsigned code units of the appropriate widths. | |
| For example, <code class="type pcre2-api rouge"><span class="kt">PCRE2_UCHAR16</span></code> is usually defined as <code class="type pcre2-api rouge"><span class="kt">uint16_t</span></code>. | |
| The SPTR types are pointers to constants of the equivalent UCHAR types, | |
| that is, they are pointers to vectors of unsigned code units.</p> | |
| <p>Character strings are passed to a PCRE2 library as sequences of unsigned | |
| integers in code units of the appropriate width. The length of a string may | |
| be given as a number of code units, or the string may be specified as | |
| zero-terminated.</p> | |
| <p>Many applications use only one code unit width. For their convenience, macros | |
| are defined whose names are the generic forms such as <code class="function pcre2-api rouge"><span class="nf">pcre2_compile()</span></code> and | |
| <code class="type pcre2-api rouge"><span class="kt">PCRE2_SPTR</span></code>. These macros use the value of the macro <code class="constant pcre2-api rouge"><span class="no">PCRE2_CODE_UNIT_WIDTH</span></code> to | |
| generate the appropriate width-specific function and macro names. | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_CODE_UNIT_WIDTH</span></code> is not defined by default. An application must define it | |
| to be 8, 16, or 32 before including <code>pcre2.h</code> in order to make use of the | |
| generic names.</p> | |
| <p>Applications that use more than one code unit width can be linked with more | |
| than one PCRE2 library, but must define <code class="constant pcre2-api rouge"><span class="no">PCRE2_CODE_UNIT_WIDTH</span></code> to be 0 before | |
| including <code>pcre2.h</code>, and then use the real function names. Any code that is | |
| to be included in an environment where the value of <code class="constant pcre2-api rouge"><span class="no">PCRE2_CODE_UNIT_WIDTH</span></code> is | |
| unknown should also use the real function names. (Unfortunately, it is not | |
| possible in C code to save and restore the value of a macro.)</p> | |
| <p>If <code class="constant pcre2-api rouge"><span class="no">PCRE2_CODE_UNIT_WIDTH</span></code> is not defined before including <code>pcre2.h</code>, a | |
| compiler error occurs.</p> | |
| <p>When using multiple libraries in an application, you must take care when | |
| processing any particular pattern to use only functions from a single library. | |
| For example, if you want to run a match using a pattern that was compiled with | |
| <code class="c rouge" data-lang="c"><span class="nf">pcre2_compile_16</span><span class="p">()</span></code>, you must do so with <code class="c rouge" data-lang="c"><span class="nf">pcre2_match_16</span><span class="p">()</span></code>, not | |
| <code class="c rouge" data-lang="c"><span class="nf">pcre2_match_8</span><span class="p">()</span></code> or <code class="c rouge" data-lang="c"><span class="nf">pcre2_match_32</span><span class="p">()</span></code>.</p> | |
| <p>In the function summaries above, and in the rest of this document and other | |
| PCRE2 documents, functions and data types are described using their generic | |
| names, without the <code>_8</code>, <code>_16</code>, or <code>_32</code> suffix.</p></section> | |
| <section class="doc-section level-1"><h2 id="_pcre2_api_overview">PCRE2 API overview</h2><p>PCRE2 has its own native API, which is described in this document. There are | |
| also some wrapper functions for the 8-bit library that correspond to the | |
| POSIX regular expression API, but they do not give access to all the | |
| functionality of PCRE2 and they are not thread-safe. They are described in the | |
| <a href="./pcre2posix.html"><code>pcre2posix</code></a> | |
| documentation. Both these APIs define a set of C function calls.</p> | |
| <p>The native API C data types, function prototypes, option values, and error | |
| codes are defined in the header file <code>pcre2.h</code>, which also contains | |
| definitions of <code class="constant pcre2-api rouge"><span class="no">PCRE2_MAJOR</span></code> and <code class="constant pcre2-api rouge"><span class="no">PCRE2_MINOR</span></code>, the major and minor release numbers | |
| for the library. Applications can use these to include support for different | |
| releases of PCRE2.</p> | |
| <p>In a Windows environment, if you want to statically link an application program | |
| against a non-dll PCRE2 library, you must define <code class="constant pcre2-api rouge"><span class="no">PCRE2_STATIC</span></code> before including | |
| <code>pcre2.h</code>.</p> | |
| <p>The functions <code class="function pcre2-api rouge"><span class="nf">pcre2_compile()</span></code> and <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> are used for | |
| compiling and matching regular expressions in a Perl-compatible manner. A | |
| sample program that demonstrates the simplest way of using them is provided in | |
| the file called <code>pcre2demo.c</code> in the PCRE2 source distribution. A listing | |
| of this program is given in the | |
| <a href="./pcre2demo.html"><code>pcre2demo</code></a> | |
| documentation, and the | |
| <a href="./pcre2sample.html"><code>pcre2sample</code></a> | |
| documentation describes how to compile and run it.</p> | |
| <p>The compiling and matching functions recognize various options that are passed | |
| as bits in an options argument. There are also some more complicated parameters | |
| such as custom memory management functions and resource limits that are passed | |
| in "contexts" (which are just memory blocks, described below). Simple | |
| applications do not need to make use of contexts.</p> | |
| <p>Just-in-time (JIT) compiler support is an optional feature of PCRE2 that can be | |
| built in appropriate hardware environments. It greatly speeds up the matching | |
| performance of many patterns. Programs can request that it be used if | |
| available by calling <code class="function pcre2-api rouge"><span class="nf">pcre2_jit_compile()</span></code> after a pattern has been | |
| successfully compiled by <code class="function pcre2-api rouge"><span class="nf">pcre2_compile()</span></code>. This does nothing if JIT | |
| support is not available.</p> | |
| <p>More complicated programs might need to make use of the specialist functions | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_jit_stack_create()</span></code>, <code class="function pcre2-api rouge"><span class="nf">pcre2_jit_stack_free()</span></code>, and | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_jit_stack_assign()</span></code> in order to control the JIT code’s memory usage.</p> | |
| <p>JIT matching is automatically used by <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> if it is available, | |
| unless the <code class="constant pcre2-api rouge"><span class="no">PCRE2_NO_JIT</span></code> option is set. There is also a direct interface for JIT | |
| matching, which gives improved performance at the expense of less sanity | |
| checking. The JIT-specific functions are discussed in the | |
| <a href="./pcre2jit.html"><code>pcre2jit</code></a> | |
| documentation.</p> | |
| <p>A second matching function, <code class="function pcre2-api rouge"><span class="nf">pcre2_dfa_match()</span></code>, which is not | |
| Perl-compatible, is also provided. This uses a different algorithm for the | |
| matching. The alternative algorithm finds all possible matches (at a given | |
| point in the subject), and scans the subject just once (unless there are | |
| lookaround assertions). However, this algorithm does not return captured | |
| substrings. A description of the two matching algorithms and their advantages | |
| and disadvantages is given in the | |
| <a href="./pcre2matching.html"><code>pcre2matching</code></a> | |
| documentation. There is no JIT support for <code class="function pcre2-api rouge"><span class="nf">pcre2_dfa_match()</span></code>.</p> | |
| <p>In addition to the main compiling and matching functions, there are convenience | |
| functions for extracting captured substrings from a subject string that has | |
| been matched by <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code>. They are:</p> | |
| <ul class="compact"><li><code class="function pcre2-api rouge"><span class="nf">pcre2_substring_copy_byname()</span></code></li><li><code class="function pcre2-api rouge"><span class="nf">pcre2_substring_copy_bynumber()</span></code></li><li><code class="function pcre2-api rouge"><span class="nf">pcre2_substring_get_byname()</span></code></li><li><code class="function pcre2-api rouge"><span class="nf">pcre2_substring_get_bynumber()</span></code></li><li><code class="function pcre2-api rouge"><span class="nf">pcre2_substring_list_get()</span></code></li><li><code class="function pcre2-api rouge"><span class="nf">pcre2_substring_length_byname()</span></code></li><li><code class="function pcre2-api rouge"><span class="nf">pcre2_substring_length_bynumber()</span></code></li><li><code class="function pcre2-api rouge"><span class="nf">pcre2_substring_nametable_scan()</span></code></li><li><code class="function pcre2-api rouge"><span class="nf">pcre2_substring_number_from_name()</span></code></li></ul> | |
| <p><code class="function pcre2-api rouge"><span class="nf">pcre2_substring_free()</span></code> and <code class="function pcre2-api rouge"><span class="nf">pcre2_substring_list_free()</span></code> are also | |
| provided, to free memory used for extracted strings. If either of these | |
| functions is called with a <code class="constant pcre2-api rouge"><span class="kc">NULL</span></code> argument, the function returns immediately | |
| without doing anything.</p> | |
| <p>The function <code class="function pcre2-api rouge"><span class="nf">pcre2_substitute()</span></code> can be called to match a pattern and | |
| return a copy of the subject string with substitutions for parts that were | |
| matched.</p> | |
| <p>Functions whose names begin with <code class="c rouge" data-lang="c"><span class="kt">pcre2_serialize_</span></code> are used for saving | |
| compiled patterns on disc or elsewhere, and reloading them later.</p> | |
| <p>Finally, there are functions for finding out information about a compiled | |
| pattern (<code class="function pcre2-api rouge"><span class="nf">pcre2_pattern_info()</span></code>) and about the configuration with which | |
| PCRE2 was built (<code class="function pcre2-api rouge"><span class="nf">pcre2_config()</span></code>) and that it is using.</p> | |
| <p>Functions with names ending with <code class="c rouge" data-lang="c"><span class="nf">_free</span><span class="p">()</span></code> are used for freeing memory | |
| blocks of various sorts. In all cases, if one of these functions is called with | |
| a <code class="constant pcre2-api rouge"><span class="kc">NULL</span></code> argument, it does nothing.</p></section> | |
| <section class="doc-section level-1"><h2 id="_string_lengths_and_offsets">String lengths and offsets</h2><p>The PCRE2 API uses string lengths and offsets into strings of code units in | |
| several places. These values are always of type <code class="type pcre2-api rouge"><span class="kt">PCRE2_SIZE</span></code>, which is an | |
| unsigned integer type, currently always defined as <code class="type pcre2-api rouge"><span class="kt">size_t</span></code>. The largest | |
| value that can be stored in such a type (that is <code class="c rouge" data-lang="c"><span class="o">~</span><span class="p">(</span><span class="kt">PCRE2_SIZE</span><span class="p">)</span><span class="mi">0</span></code>) is reserved | |
| as a special indicator for zero-terminated strings and unset offsets. | |
| Therefore, the longest string that can be handled is one less than this | |
| maximum. Note that string lengths are always given in code units. Only in the | |
| 8-bit library is such a length the same as the number of bytes in the string.</p></section> | |
| <section class="doc-section level-1"><h2 id="_newlines">Newlines</h2><p>PCRE2 supports five different conventions for indicating line breaks in | |
| strings: a single CR (carriage return) character, a single LF (linefeed) | |
| character, the two-character sequence CRLF, any of the three preceding, or any | |
| Unicode newline sequence. The Unicode newline sequences are the three just | |
| mentioned, plus the single characters VT (vertical tab, <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-1"><code class="character pcre2-api rouge"><span class="sc">U+000B</span></code><span class="character-card" id="pcre2-character-1" role="tooltip" aria-label="LINE TABULATION (U+000B)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="LINE TABULATION"></span><span class="character-codepoint" data-codepoint="U+000B"></span></span></span>), FF (form feed, | |
| <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-2"><code class="character pcre2-api rouge"><span class="sc">U+000C</span></code><span class="character-card" id="pcre2-character-2" role="tooltip" aria-label="FORM FEED (U+000C)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="FORM FEED"></span><span class="character-codepoint" data-codepoint="U+000C"></span></span></span>), NEL (next line, <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-3"><code class="character pcre2-api rouge"><span class="sc">U+0085</span></code><span class="character-card" id="pcre2-character-3" role="tooltip" aria-label="NEXT LINE (U+0085)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="NEXT LINE"></span><span class="character-codepoint" data-codepoint="U+0085"></span></span></span>), LS (line separator, <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-4"><code class="character pcre2-api rouge"><span class="sc">U+2028</span></code><span class="character-card" id="pcre2-character-4" role="tooltip" aria-label="LINE SEPARATOR (U+2028)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="LINE SEPARATOR"></span><span class="character-codepoint" data-codepoint="U+2028"></span></span></span>), and PS | |
| (paragraph separator, <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-5"><code class="character pcre2-api rouge"><span class="sc">U+2029</span></code><span class="character-card" id="pcre2-character-5" role="tooltip" aria-label="PARAGRAPH SEPARATOR (U+2029)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="PARAGRAPH SEPARATOR"></span><span class="character-codepoint" data-codepoint="U+2029"></span></span></span>).</p> | |
| <p>Each of the first three conventions is used by at least one operating system as | |
| its standard newline sequence. When PCRE2 is built, a default can be specified. | |
| If it is not, the default is set to LF, which is the Unix standard. However, | |
| the newline convention can be changed by an application when calling | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_compile()</span></code>, or it can be specified by special text at the start of | |
| the pattern itself; this overrides any other settings. See the | |
| <a href="./pcre2pattern.html"><code>pcre2pattern</code></a> | |
| page for details of the special character sequences.</p> | |
| <p>In the PCRE2 documentation the word "newline" is used to mean "the character or | |
| pair of characters that indicate a line break". The choice of newline | |
| convention affects the handling of the dot, circumflex, and dollar | |
| metacharacters, the handling of <code class="regex rouge"><span class="pcre2-semantic">#</span></code>-comments in <code class="regex rouge"><span class="pcre2-semantic">/x</span></code> mode, and, when CRLF is a | |
| recognized line ending sequence, the match position advancement for a | |
| non-anchored pattern. There is more detail about this in the | |
| section <a href="#match-option-bits">Option bits for <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code></a> | |
| below.</p> | |
| <p>The choice of newline convention does not affect the interpretation of | |
| the <code class="regex rouge"><span class="pcre2-semantic">\n</span></code> or <code class="regex rouge"><span class="pcre2-semantic">\r</span></code> escape sequences, nor does it affect what <code class="regex rouge"><span class="pcre2-semantic">\R</span></code> matches; this has | |
| its own separate convention.</p></section> | |
| <section class="doc-section level-1"><h2 id="_multithreading">Multithreading</h2><p>In a multithreaded application it is important to keep thread-specific data | |
| separate from data that can be shared between threads. The PCRE2 library code | |
| itself is thread-safe: it contains no static or global variables. The API is | |
| designed to be fairly simple for non-threaded applications while at the same | |
| time ensuring that multithreaded applications can use it.</p> | |
| <p>There are several different blocks of data that are used to pass information | |
| between the application and the PCRE2 libraries.</p> | |
| <section class="doc-section level-2"><h3 id="_the_compiled_pattern">The compiled pattern</h3><p>A pointer to the compiled form of a pattern is returned to the user when | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_compile()</span></code> is successful. The data in the compiled pattern is fixed, | |
| and does not change when the pattern is matched. Therefore, it is thread-safe, | |
| that is, the same compiled pattern can be used by more than one thread | |
| simultaneously. For example, an application can compile all its patterns at the | |
| start, before forking off multiple threads that use them. However, if the | |
| just-in-time (JIT) optimization feature is being used, it needs separate memory | |
| stack areas for each thread. See the | |
| <a href="./pcre2jit.html"><code>pcre2jit</code></a> | |
| documentation for more details.</p> | |
| <p>In a more complicated situation, where patterns are compiled only when they are | |
| first needed, but are still shared between threads, pointers to compiled | |
| patterns must be protected from simultaneous writing by multiple threads. This | |
| is somewhat tricky to do correctly. If you know that writing to a pointer is | |
| atomic in your environment, you can use logic like this:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="c"><span class="c1">// Get a read-only (shared) lock (mutex) for pointer</span> | |
| <span class="k">if</span> <span class="p">(</span><span class="nv">pointer</span> <span class="o">==</span> <span class="kc">NULL</span><span class="p">)</span> | |
| <span class="p">{</span> | |
| <span class="c1">// Get a write (unique) lock for pointer</span> | |
| <span class="k">if</span> <span class="p">(</span><span class="nv">pointer</span> <span class="o">==</span> <span class="kc">NULL</span><span class="p">)</span> | |
| <span class="nv">pointer</span> <span class="o">=</span> <span class="nf">pcre2_compile</span><span class="p">(...);</span> | |
| <span class="p">}</span> | |
| <span class="c1">// Release the lock</span> | |
| <span class="c1">// Use pointer in pcre2_match()</span></code></pre></div> | |
| <p>Of course, testing for compilation errors should also be included in the code.</p> | |
| <p>The reason for checking the pointer a second time is as follows: Several | |
| threads may have acquired the shared lock and tested the pointer for being | |
| <code class="constant pcre2-api rouge"><span class="kc">NULL</span></code>, but only one of them will be given the write lock, with the rest kept | |
| waiting. The winning thread will compile the pattern and store the result. | |
| After this thread releases the write lock, another thread will get it, and if | |
| it does not retest pointer for being <code class="constant pcre2-api rouge"><span class="kc">NULL</span></code>, will recompile the pattern and | |
| overwrite the pointer, creating a memory leak and possibly causing other | |
| issues.</p> | |
| <p>In an environment where writing to a pointer may not be atomic, the above logic | |
| is not sufficient. The thread that is doing the compiling may be descheduled | |
| after writing only part of the pointer, which could cause other threads to use | |
| an invalid value. Instead of checking the pointer itself, a separate "pointer | |
| is valid" flag (that can be updated atomically) must be used:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="c"><span class="c1">// Get a read-only (shared) lock (mutex) for pointer</span> | |
| <span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="nv">pointer_is_valid</span><span class="p">)</span> | |
| <span class="p">{</span> | |
| <span class="c1">// Get a write (unique) lock for pointer</span> | |
| <span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="nv">pointer_is_valid</span><span class="p">)</span> | |
| <span class="p">{</span> | |
| <span class="nv">pointer</span> <span class="o">=</span> <span class="nf">pcre2_compile</span><span class="p">(...);</span> | |
| <span class="nv">pointer_is_valid</span> <span class="o">=</span> <span class="kc">TRUE</span><span class="p">;</span> | |
| <span class="p">}</span> | |
| <span class="p">}</span> | |
| <span class="c1">// Release the lock</span> | |
| <span class="c1">// Use pointer in pcre2_match()</span></code></pre></div> | |
| <p>If JIT is being used, but the JIT compilation is not being done immediately | |
| (perhaps waiting to see if the pattern is used often enough), similar logic is | |
| required. JIT compilation updates a value within the compiled code block, so a | |
| thread must gain unique write access to the pointer before calling | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_jit_compile()</span></code>. Alternatively, <code class="function pcre2-api rouge"><span class="nf">pcre2_code_copy()</span></code> or | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_code_copy_with_tables()</span></code> can be used to obtain a private copy of the | |
| compiled code before calling the JIT compiler.</p></section> | |
| <section class="doc-section level-2"><h3 id="_context_blocks">Context blocks</h3><p>The section <a href="#pcre2-contexts">PCRE2 contexts</a> below introduces the idea of "contexts" in which PCRE2 | |
| functions are called. A context is nothing more than a collection of parameters | |
| that control the way PCRE2 operates. Grouping a number of parameters together | |
| in a context is a convenient way of passing them to a PCRE2 function without | |
| using lots of arguments. The parameters that are stored in contexts are in some | |
| sense "advanced features" of the API. Many straightforward applications will | |
| not need to use contexts.</p> | |
| <p>In a multithreaded application, if the parameters in a context are values that | |
| are never changed, the same context can be used by all the threads. However, if | |
| any thread needs to change any value in a context, it must make its own | |
| thread-specific copy.</p></section> | |
| <section class="doc-section level-2"><h3 id="_match_blocks">Match blocks</h3><p>The matching functions need a block of memory for storing the results of a | |
| match. This includes details of what was matched, as well as additional | |
| information such as the name of a <code class="regex rouge"><span class="pcre2-semantic">(*MARK)</span></code> setting. Each thread must provide its | |
| own copy of this memory.</p></section></section> | |
| <section class="doc-section level-1"><h2 id="pcre2-contexts">PCRE2 contexts</h2><p>Some PCRE2 functions have a lot of parameters, many of which are used only by | |
| specialist applications, for example, those that use custom memory management | |
| or non-standard character tables. To keep function argument lists at a | |
| reasonable size, and at the same time to keep the API extensible, "uncommon" | |
| parameters are passed to certain functions in a "context" instead of | |
| directly. A context is just a block of memory that holds the parameter values. | |
| Applications that do not need to adjust any of the context parameters can pass | |
| <code class="constant pcre2-api rouge"><span class="kc">NULL</span></code> to operations that accept a context to select their defaults. The | |
| context setter and getter functions require a non-<code class="constant pcre2-api rouge"><span class="kc">NULL</span></code> context. | |
| Getter output pointers must also be non-<code class="constant pcre2-api rouge"><span class="kc">NULL</span></code>.</p> | |
| <p>The main API uses a general context that is relevant for several PCRE2 | |
| operations, a compile-time context, and a match-time context. The experimental | |
| pattern conversion API also has a conversion context, described in | |
| <a href="./pcre2convert.html"><code>pcre2convert</code></a>.</p> | |
| <section class="doc-section level-2"><h3 id="_the_general_context">The general context</h3><p>At present, this context just contains pointers to (and data for) external | |
| memory management functions that are called from several places in the PCRE2 | |
| library. The context is named 'general' rather than specifically 'memory' | |
| because in future other fields may be added. If you do not want to supply your | |
| own custom memory management functions, you do not need to bother with a | |
| general context. A general context is created by:</p> | |
| <div class="listing-block prototype"><pre class="rouge highlight"><code data-lang="c"><span class="kt">pcre2_general_context</span> <span class="p">*</span><span class="nf">pcre2_general_context_create</span><span class="p">(</span> | |
| <span class="kt">void</span> <span class="p">*</span><span class="p">(</span><span class="p">*</span><span class="nv">private_malloc</span><span class="p">)(</span><span class="kt">size_t</span> <span class="nv">size</span><span class="p">,</span> <span class="kt">void</span> <span class="p">*</span><span class="nv">memory_data</span><span class="p">),</span> | |
| <span class="kt">void</span> <span class="p">(</span><span class="p">*</span><span class="nv">private_free</span><span class="p">)(</span><span class="kt">void</span> <span class="p">*</span><span class="nv">ptr</span><span class="p">,</span> <span class="kt">void</span> <span class="p">*</span><span class="nv">memory_data</span><span class="p">),</span> | |
| <span class="kt">void</span> <span class="p">*</span><span class="nv">memory_data</span><span class="p">);</span></code></pre></div> | |
| <p>The two function pointers specify custom memory management functions, whose | |
| prototypes are:</p> | |
| <div class="listing-block prototype"><pre class="rouge highlight"><code data-lang="c"><span class="kt">void</span> <span class="p">*</span><span class="nf">private_malloc</span><span class="p">(</span><span class="kt">PCRE2_SIZE</span><span class="p">,</span> <span class="kt">void</span> <span class="p">*</span><span class="p">);</span> | |
| <span class="kt">void</span> <span class="nf">private_free</span><span class="p">(</span><span class="kt">void</span> <span class="p">*</span><span class="p">,</span> <span class="kt">void</span> <span class="p">*</span><span class="p">);</span></code></pre></div> | |
| <p>Whenever code in PCRE2 calls these functions, the final argument is the value | |
| of <code class="parameter pcre2-api rouge"><span class="nv">memory_data</span></code>. Either of the first two arguments of the creation | |
| function may be <code class="constant pcre2-api rouge"><span class="kc">NULL</span></code>, in which case the system memory management functions | |
| <code class="c rouge" data-lang="c"><span class="nf">malloc</span><span class="p">()</span></code> and <code class="c rouge" data-lang="c"><span class="nf">free</span><span class="p">()</span></code> are used. (This is not currently useful, as | |
| there are no other fields in a general context, but in future there might be.) | |
| The <code class="c rouge" data-lang="c"><span class="nf">private_malloc</span><span class="p">()</span></code> function is used (if supplied) to obtain memory for | |
| storing the context, and all three values are saved as part of the context.</p> | |
| <p>Whenever PCRE2 creates a data block of any kind, the block contains a pointer | |
| to the <code class="c rouge" data-lang="c"><span class="nf">free</span><span class="p">()</span></code> function that matches the <code class="c rouge" data-lang="c"><span class="nf">malloc</span><span class="p">()</span></code> function that was | |
| used. When the time comes to free the block, this function is called.</p> | |
| <p>A general context can be copied by calling:</p> | |
| <div class="listing-block prototype"><pre class="rouge highlight"><code data-lang="c"><span class="kt">pcre2_general_context</span> <span class="p">*</span><span class="nf">pcre2_general_context_copy</span><span class="p">(</span> | |
| <span class="kt">pcre2_general_context</span> <span class="p">*</span><span class="nv">gcontext</span><span class="p">);</span></code></pre></div> | |
| <p>The memory used for a general context should be freed by calling:</p> | |
| <div class="listing-block prototype"><pre class="rouge highlight"><code data-lang="c"><span class="kt">void</span> <span class="nf">pcre2_general_context_free</span><span class="p">(</span><span class="kt">pcre2_general_context</span> <span class="p">*</span><span class="nv">gcontext</span><span class="p">);</span></code></pre></div> | |
| <p>If this function is passed a <code class="constant pcre2-api rouge"><span class="kc">NULL</span></code> argument, it returns immediately without | |
| doing anything.</p></section> | |
| <section class="doc-section level-2"><h3 id="_the_compile_context">The compile context</h3><p>A compile context is required if you want to provide an external function for | |
| stack checking during compilation or to change the default values of any of the | |
| following compile-time parameters:</p> | |
| <ul class="compact"><li>What <code class="regex rouge"><span class="pcre2-semantic">\R</span></code> matches (Unicode newlines or CR, LF, CRLF only)</li><li>PCRE2’s character tables</li><li>The newline character sequence</li><li>The compile time nested parentheses limit</li><li>The maximum length of the pattern string</li><li>The extra options bits (none set by default)</li><li>Which performance optimizations the compiler should apply</li></ul> | |
| <p>A compile context is also required if you are using custom memory management. | |
| If none of these apply, just pass <code class="constant pcre2-api rouge"><span class="kc">NULL</span></code> as the context argument of | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_compile()</span></code>.</p> | |
| <p>A compile context is created, copied, and freed by the following functions:</p> | |
| <div class="listing-block prototype"><pre class="rouge highlight"><code data-lang="c"><span class="kt">pcre2_compile_context</span> <span class="p">*</span><span class="nf">pcre2_compile_context_create</span><span class="p">(</span> | |
| <span class="kt">pcre2_general_context</span> <span class="p">*</span><span class="nv">gcontext</span><span class="p">);</span> | |
| <span class="kt">pcre2_compile_context</span> <span class="p">*</span><span class="nf">pcre2_compile_context_copy</span><span class="p">(</span> | |
| <span class="kt">pcre2_compile_context</span> <span class="p">*</span><span class="nv">ccontext</span><span class="p">);</span> | |
| <span class="kt">void</span> <span class="nf">pcre2_compile_context_free</span><span class="p">(</span><span class="kt">pcre2_compile_context</span> <span class="p">*</span><span class="nv">ccontext</span><span class="p">);</span></code></pre></div> | |
| <p>A compile context is created with default values for its parameters. These can | |
| be changed by calling the following functions, which return 0 on success, or | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_BADDATA</span></code> if invalid data is detected. The function | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_set_optimize()</span></code> returns <code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_BADOPTION</span></code> for an invalid | |
| <code class="parameter pcre2-api rouge"><span class="nv">directive</span></code> argument.</p> | |
| <p>The following functions get, respectively, the convention for processing <code class="regex rouge"><span class="pcre2-semantic">\R</span></code>, | |
| the maximum pattern length, the newline convention, and the maximum depth of | |
| nested parentheses. They return 0 and require both arguments to be | |
| non-<code class="constant pcre2-api rouge"><span class="kc">NULL</span></code>.</p> | |
| <div class="listing-block prototype"><pre class="rouge highlight"><code data-lang="c"><span class="kt">int</span> <span class="nf">pcre2_get_bsr</span><span class="p">(</span><span class="kt">pcre2_compile_context</span> <span class="p">*</span><span class="nv">ccontext</span><span class="p">,</span> <span class="kt">uint32_t</span> <span class="p">*</span><span class="nv">value</span><span class="p">);</span> | |
| <span class="kt">int</span> <span class="nf">pcre2_get_max_pattern_length</span><span class="p">(</span><span class="kt">pcre2_compile_context</span> <span class="p">*</span><span class="nv">ccontext</span><span class="p">,</span> | |
| <span class="kt">PCRE2_SIZE</span> <span class="p">*</span><span class="nv">length</span><span class="p">);</span> | |
| <span class="kt">int</span> <span class="nf">pcre2_get_newline</span><span class="p">(</span><span class="kt">pcre2_compile_context</span> <span class="p">*</span><span class="nv">ccontext</span><span class="p">,</span> | |
| <span class="kt">uint32_t</span> <span class="p">*</span><span class="nv">newline</span><span class="p">);</span> | |
| <span class="kt">int</span> <span class="nf">pcre2_get_parens_nest_limit</span><span class="p">(</span><span class="kt">pcre2_compile_context</span> <span class="p">*</span><span class="nv">ccontext</span><span class="p">,</span> | |
| <span class="kt">uint32_t</span> <span class="p">*</span><span class="nv">limit</span><span class="p">);</span></code></pre></div> | |
| <p>The value returned by <code class="function pcre2-api rouge"><span class="nf">pcre2_get_max_pattern_length()</span></code> is the largest | |
| value a <code class="type pcre2-api rouge"><span class="kt">PCRE2_SIZE</span></code> variable can hold when the limit is unlimited. Passing this | |
| value to <code class="function pcre2-api rouge"><span class="nf">pcre2_set_max_pattern_length()</span></code> makes the limit unlimited.</p> | |
| <div class="listing-block prototype"><pre class="rouge highlight"><code data-lang="c"><span class="kt">int</span> <span class="nf">pcre2_set_bsr</span><span class="p">(</span><span class="kt">pcre2_compile_context</span> <span class="p">*</span><span class="nv">ccontext</span><span class="p">,</span> <span class="kt">uint32_t</span> <span class="nv">value</span><span class="p">);</span></code></pre></div> | |
| <p>The value must be <code class="constant pcre2-api rouge"><span class="no">PCRE2_BSR_ANYCRLF</span></code>, to specify that <code class="regex rouge"><span class="pcre2-semantic">\R</span></code> matches only CR, LF, | |
| or CRLF, or <code class="constant pcre2-api rouge"><span class="no">PCRE2_BSR_UNICODE</span></code>, to specify that <code class="regex rouge"><span class="pcre2-semantic">\R</span></code> matches any Unicode line | |
| ending sequence. The value is used by the JIT compiler and by the two | |
| interpreted matching functions, <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> and | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_dfa_match()</span></code>.</p> | |
| <div class="listing-block prototype"><pre class="rouge highlight"><code data-lang="c"><span class="kt">int</span> <span class="nf">pcre2_set_character_tables</span><span class="p">(</span><span class="kt">pcre2_compile_context</span> <span class="p">*</span><span class="nv">ccontext</span><span class="p">,</span> | |
| <span class="kt">const</span> <span class="kt">uint8_t</span> <span class="p">*</span><span class="nv">tables</span><span class="p">);</span></code></pre></div> | |
| <p>The value may be <code class="constant pcre2-api rouge"><span class="kc">NULL</span></code> to select the default tables; the result of | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_maketables()</span></code>; or another valid set of PCRE2 character tables. | |
| The <code class="function pcre2-api rouge"><span class="nf">pcre2_maketables()</span></code> function takes a general context and builds tables | |
| in the current locale. Supplied tables must remain valid while the context or | |
| patterns compiled with them are in use.</p> | |
| <div class="listing-block prototype"><pre class="rouge highlight"><code data-lang="c"><span class="kt">int</span> <span class="nf">pcre2_set_compile_extra_options</span><span class="p">(</span><span class="kt">pcre2_compile_context</span> <span class="p">*</span><span class="nv">ccontext</span><span class="p">,</span> | |
| <span class="kt">uint32_t</span> <span class="nv">options</span><span class="p">);</span></code></pre></div> | |
| <p>As PCRE2 has developed, almost all the 32 option bits that are available in | |
| the <code class="parameter pcre2-api rouge"><span class="nv">options</span></code> argument of <code class="function pcre2-api rouge"><span class="nf">pcre2_compile()</span></code> have been used up. To avoid | |
| running out, the compile context contains a set of extra option bits which are | |
| used for some newer, assumed rarer, options. This function sets those bits. It | |
| always sets all the bits (either on or off). It does not modify any existing | |
| setting. The available options are defined in the section | |
| <a href="#extra-compile-options">Extra compile options</a> | |
| below.</p> | |
| <div class="listing-block prototype"><pre class="rouge highlight"><code data-lang="c"><span class="kt">int</span> <span class="nf">pcre2_set_max_pattern_length</span><span class="p">(</span><span class="kt">pcre2_compile_context</span> <span class="p">*</span><span class="nv">ccontext</span><span class="p">,</span> | |
| <span class="kt">PCRE2_SIZE</span> <span class="nv">length</span><span class="p">);</span></code></pre></div> | |
| <p>This sets a maximum length, in code units, for any pattern string that is | |
| compiled with this context. If the pattern is longer, an error is generated. | |
| This facility is provided so that applications that accept patterns from | |
| external sources can limit their size. The default is the largest number that a | |
| <code class="type pcre2-api rouge"><span class="kt">PCRE2_SIZE</span></code> variable can hold, which is effectively unlimited.</p> | |
| <div class="listing-block prototype"><pre class="rouge highlight"><code data-lang="c"><span class="kt">int</span> <span class="nf">pcre2_set_max_pattern_compiled_length</span><span class="p">(</span> | |
| <span class="kt">pcre2_compile_context</span> <span class="p">*</span><span class="nv">ccontext</span><span class="p">,</span> <span class="kt">PCRE2_SIZE</span> <span class="nv">length</span><span class="p">);</span></code></pre></div> | |
| <p>This sets a maximum size, in bytes, for the memory needed to hold the compiled | |
| version of a pattern that is compiled with this context. If the pattern needs | |
| more memory, an error is generated. This facility is provided so that | |
| applications that accept patterns from external sources can limit the amount of | |
| memory they use. The default is the largest number that a <code class="type pcre2-api rouge"><span class="kt">PCRE2_SIZE</span></code> variable | |
| can hold, which is effectively unlimited.</p> | |
| <p>This limit excludes the fixed, platform-dependent compiled-pattern header. | |
| Therefore, <code class="constant pcre2-api rouge"><span class="no">PCRE2_INFO_SIZE</span></code> can report a larger total allocation. This limit | |
| does not restrict temporary compilation workspace, JIT code, or separate character | |
| tables.</p> | |
| <div class="listing-block prototype"><pre class="rouge highlight"><code data-lang="c"><span class="kt">int</span> <span class="nf">pcre2_set_max_varlookbehind</span><span class="p">(</span><span class="kt">pcre2_compile_context</span> <span class="p">*</span><span class="nv">ccontext</span><span class="p">,</span> | |
| <span class="kt">uint32_t</span> <span class="nv">limit</span><span class="p">);</span></code></pre></div> | |
| <p>This sets a maximum length for the number of characters matched by a | |
| variable-length lookbehind assertion. The default is set when PCRE2 is built, | |
| with the ultimate default being 255, the same as Perl. Lookbehind assertions | |
| without a bounding length are not supported.</p> | |
| <div class="listing-block prototype"><pre class="rouge highlight"><code data-lang="c"><span class="kt">int</span> <span class="nf">pcre2_set_newline</span><span class="p">(</span><span class="kt">pcre2_compile_context</span> <span class="p">*</span><span class="nv">ccontext</span><span class="p">,</span> | |
| <span class="kt">uint32_t</span> <span class="nv">newline</span><span class="p">);</span></code></pre></div> | |
| <p>This specifies which characters or character sequences are to be recognized as | |
| newlines. The value must be one of <code class="constant pcre2-api rouge"><span class="no">PCRE2_NEWLINE_CR</span></code> (carriage return only), | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_NEWLINE_LF</span></code> (linefeed only), <code class="constant pcre2-api rouge"><span class="no">PCRE2_NEWLINE_CRLF</span></code> (the two-character | |
| sequence CR followed by LF), <code class="constant pcre2-api rouge"><span class="no">PCRE2_NEWLINE_ANYCRLF</span></code> (any of the above), | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_NEWLINE_ANY</span></code> (any Unicode newline sequence), or <code class="constant pcre2-api rouge"><span class="no">PCRE2_NEWLINE_NUL</span></code> (the | |
| NUL character, that is a binary zero).</p> | |
| <p>A pattern can override the value set in the compile context by starting with a | |
| sequence such as <code class="regex rouge"><span class="pcre2-semantic">(*CRLF)</span></code>. See the | |
| <a href="./pcre2pattern.html"><code>pcre2pattern</code></a> | |
| page for details.</p> | |
| <p>When a pattern is compiled with the <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTENDED</span></code> or <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTENDED_MORE</span></code> | |
| option, the newline convention affects the recognition of the end of internal | |
| comments starting with <code class="regex rouge"><span class="pcre2-semantic">#</span></code>. The value is saved with the compiled pattern for | |
| subsequent use by the JIT compiler and by the two interpreted matching | |
| functions, <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> and <code class="function pcre2-api rouge"><span class="nf">pcre2_dfa_match()</span></code>.</p> | |
| <div class="listing-block prototype"><pre class="rouge highlight"><code data-lang="c"><span class="kt">int</span> <span class="nf">pcre2_set_parens_nest_limit</span><span class="p">(</span><span class="kt">pcre2_compile_context</span> <span class="p">*</span><span class="nv">ccontext</span><span class="p">,</span> | |
| <span class="kt">uint32_t</span> <span class="nv">limit</span><span class="p">);</span></code></pre></div> | |
| <p>This parameter adjusts the limit, set when PCRE2 is built (default 250), on the | |
| depth of parenthesis nesting in a pattern. This limit stops rogue patterns | |
| using up too much system stack when being compiled. The limit applies to | |
| parentheses of all kinds, not just capturing parentheses.</p> | |
| <div class="listing-block prototype"><pre class="rouge highlight"><code data-lang="c"><span class="kt">int</span> <span class="nf">pcre2_set_compile_recursion_guard</span><span class="p">(</span><span class="kt">pcre2_compile_context</span> <span class="p">*</span><span class="nv">ccontext</span><span class="p">,</span> | |
| <span class="kt">int</span> <span class="p">(</span><span class="p">*</span><span class="nv">guard</span><span class="p">)(</span><span class="kt">uint32_t</span> <span class="nv">depth</span><span class="p">,</span> | |
| <span class="kt">void</span> <span class="p">*</span><span class="nv">user_data</span><span class="p">),</span> | |
| <span class="kt">void</span> <span class="p">*</span><span class="nv">user_data</span><span class="p">);</span></code></pre></div> | |
| <p>There is at least one application that runs PCRE2 in threads with very limited | |
| system stack, where running out of stack is to be avoided at all costs. The | |
| parenthesis limit above cannot take account of how much stack is actually | |
| available during compilation. For a finer control, you can supply a function | |
| that is called whenever <code class="function pcre2-api rouge"><span class="nf">pcre2_compile()</span></code> starts to compile a parenthesized | |
| part of a pattern. This function can check the actual stack size (or anything | |
| else that it wants to, of course).</p> | |
| <p>The first argument to the callout function gives the current depth of | |
| nesting, and the second is user data that is set up by the last argument of | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_set_compile_recursion_guard()</span></code>. The callout function should return | |
| zero if all is well, or non-zero to force an error.</p> | |
| <div class="listing-block prototype"><pre class="rouge highlight"><code data-lang="c"><span class="kt">int</span> <span class="nf">pcre2_set_optimize</span><span class="p">(</span><span class="kt">pcre2_compile_context</span> <span class="p">*</span><span class="nv">ccontext</span><span class="p">,</span> | |
| <span class="kt">uint32_t</span> <span class="nv">directive</span><span class="p">);</span></code></pre></div> | |
| <p>PCRE2 can apply various performance optimizations during compilation, in order | |
| to make matching faster. For example, the compiler might convert some regex | |
| constructs into an equivalent construct which <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> can execute | |
| faster. By default, all available optimizations are enabled. However, in rare | |
| cases, one might wish to disable specific optimizations. For example, if it is | |
| known that some optimizations cannot benefit a certain regex, it might be | |
| desirable to disable them, in order to speed up compilation.</p> | |
| <p>The permitted values of <code class="parameter pcre2-api rouge"><span class="nv">directive</span></code> are as follows:</p> | |
| <dl class="values spaced" style="--tab-width: 14"><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_OPTIMIZATION_FULL</span></code></span></dt><dd>Enable all optional performance optimizations. This is the default value.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_OPTIMIZATION_NONE</span></code></span></dt><dd>Disable all optional performance optimizations.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_AUTO_POSSESS</span></code><br><code class="constant pcre2-api rouge"><span class="no">PCRE2_AUTO_POSSESS_OFF</span></code></span></dt><dd>Enable/disable "auto-possessification" of variable quantifiers such as <code class="regex rouge"><span class="pcre2-semantic">*</span></code> and <code class="regex rouge"><span class="pcre2-semantic">+</span></code>. | |
| This optimization, for example, turns <code class="regex rouge"><span class="pcre2-semantic">a+b</span></code> into | |
| <code class="regex rouge"><span class="pcre2-semantic">a++b</span></code> in order to avoid | |
| backtracks into <code class="regex rouge"><span class="pcre2-semantic">a+</span></code> that can never be successful. However, if callouts are in | |
| use, auto-possessification means that some callouts are never taken. You can | |
| disable this optimization if you want the matching functions to do a full, | |
| unoptimized search and run all the callouts.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_DOTSTAR_ANCHOR</span></code><br><code class="constant pcre2-api rouge"><span class="no">PCRE2_DOTSTAR_ANCHOR_OFF</span></code></span></dt><dd><p>Enable/disable an optimization that is applied when <code class="regex rouge"><span class="pcre2-semantic">.*</span></code> is the first significant | |
| item in a top-level branch of a pattern, and all the other branches also start | |
| with <code class="regex rouge"><span class="pcre2-semantic">.*</span></code> or with <code class="regex rouge"><span class="pcre2-semantic">\A</span></code> or <code class="regex rouge"><span class="pcre2-semantic">\G</span></code> or <code class="regex rouge"><span class="pcre2-semantic">^</span></code>. Such a pattern is automatically anchored if | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_DOTALL</span></code> is set for all the <code class="regex rouge"><span class="pcre2-semantic">.*</span></code> items and <code class="constant pcre2-api rouge"><span class="no">PCRE2_MULTILINE</span></code> is not set for any | |
| <code class="regex rouge"><span class="pcre2-semantic">^</span></code> items. Otherwise, the fact that any match must start either at the start of | |
| the subject or following a newline is remembered. Like other optimizations, | |
| this can cause callouts to be skipped.</p><p>Dotstar anchor optimization is automatically disabled for <code class="regex rouge"><span class="pcre2-semantic">.*</span></code> if it is inside an | |
| atomic group or a capture group that is the subject of a backreference, or if | |
| the pattern contains <code class="regex rouge"><span class="pcre2-semantic">(*PRUNE)</span></code> or <code class="regex rouge"><span class="pcre2-semantic">(*SKIP)</span></code>.</p></dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_START_OPTIMIZE</span></code><br><code class="constant pcre2-api rouge"><span class="no">PCRE2_START_OPTIMIZE_OFF</span></code></span></dt><dd><p>Enable/disable optimizations which cause matching functions to scan the subject | |
| string for specific code unit values before attempting a match. For example, if | |
| it is known that an unanchored match must start with a specific value, the | |
| matching code searches the subject for that value, and fails immediately if it | |
| cannot find it, without actually running the main matching function. This means | |
| that a special item such as <code class="regex rouge"><span class="pcre2-semantic">(*COMMIT)</span></code> at the start of a pattern is not | |
| considered until after a suitable starting point for the match has been found. | |
| Also, when callouts or <code class="regex rouge"><span class="pcre2-semantic">(*MARK)</span></code> items are in use, these "start-up" optimizations | |
| can cause them to be skipped if the pattern is never actually used. The start-up | |
| optimizations are in effect a pre-scan of the subject that takes place before | |
| the pattern is run.</p><p>Disabling start-up optimizations ensures that in cases where the result is "no | |
| match", the callouts do occur, and that items such as <code class="regex rouge"><span class="pcre2-semantic">(*COMMIT)</span></code> and <code class="regex rouge"><span class="pcre2-semantic">(*MARK)</span></code> are | |
| considered at every possible starting position in the subject string.</p> | |
| <p>Disabling start-up optimizations may change the outcome of a matching operation. | |
| Consider the pattern</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(*COMMIT)ABC</span></code></pre></div> | |
| <p>When this is compiled, PCRE2 records the fact that a match must start with the | |
| character <code class="subject rouge"><span class="pcre2-semantic">A</span></code>. Suppose the subject string is <code class="subject rouge"><span class="pcre2-semantic">DEFABC</span></code>. The start-up | |
| optimization scans along the subject, finds <code class="subject rouge"><span class="pcre2-semantic">A</span></code> and runs the first match | |
| attempt from there. The <code class="regex rouge"><span class="pcre2-semantic">(*COMMIT)</span></code> item means that the pattern must match the | |
| current starting position, which in this case, it does. However, if the same | |
| match is run without start-up optimizations, the initial scan along the subject | |
| string does not happen. The first match attempt is run starting from <code class="subject rouge"><span class="pcre2-semantic">D</span></code> and | |
| when this fails, <code class="regex rouge"><span class="pcre2-semantic">(*COMMIT)</span></code> prevents any further matches being tried, so the | |
| overall result is "no match".</p> | |
| <p>Another start-up optimization makes use of a minimum length for a matching | |
| subject, which is recorded when possible. Consider the pattern</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(*MARK:1)B(*MARK:2)(X|Y)</span></code></pre></div> | |
| <p>The minimum length for a match is two characters. If the subject is <code class="subject rouge"><span class="pcre2-semantic">XXBB</span></code>, the | |
| "starting character" optimization skips <code class="subject rouge"><span class="pcre2-semantic">XX</span></code>, then tries to match <code class="subject rouge"><span class="pcre2-semantic">BB</span></code>, which | |
| is long enough. In the process, <code class="regex rouge"><span class="pcre2-semantic">(*MARK:2)</span></code> is encountered and remembered. When | |
| the match attempt fails, the next <code class="subject rouge"><span class="pcre2-semantic">B</span></code> is found, but there is only one character | |
| left, so there are no more attempts, and "no match" is returned with the "last | |
| mark seen" set to <code class="subject rouge"><span class="pcre2-semantic">2</span></code>. Without start-up optimizations, however, matches are | |
| tried at every possible starting position, including at the end of the subject, | |
| where <code class="regex rouge"><span class="pcre2-semantic">(*MARK:1)</span></code> is encountered, but there is no <code class="subject rouge"><span class="pcre2-semantic">B</span></code>, so the "last mark seen" | |
| that is returned is <code class="subject rouge"><span class="pcre2-semantic">1</span></code>. In this case, the optimizations do not affect the | |
| overall match result, which is still "no match", but they do affect the | |
| auxiliary information that is returned.</p></dd></div></dl></section> | |
| <section class="doc-section level-2"><h3 id="match-context">The match context</h3><p>A match context is required if you want to:</p> | |
| <ul class="compact"><li>Set up a callout function</li><li>Set an offset limit for matching an unanchored pattern</li><li>Change the limit on the amount of heap used when matching</li><li>Change the backtracking match limit</li><li>Change the backtracking depth limit</li><li>Set custom memory management specifically for the match</li></ul> | |
| <p>If none of these apply, just pass <code class="constant pcre2-api rouge"><span class="kc">NULL</span></code> as the context argument of | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code>, <code class="function pcre2-api rouge"><span class="nf">pcre2_dfa_match()</span></code>, or <code class="function pcre2-api rouge"><span class="nf">pcre2_jit_match()</span></code>.</p> | |
| <p>A match context is created, copied, and freed by the following functions:</p> | |
| <div class="listing-block prototype"><pre class="rouge highlight"><code data-lang="c"><span class="kt">pcre2_match_context</span> <span class="p">*</span><span class="nf">pcre2_match_context_create</span><span class="p">(</span> | |
| <span class="kt">pcre2_general_context</span> <span class="p">*</span><span class="nv">gcontext</span><span class="p">);</span> | |
| <span class="kt">pcre2_match_context</span> <span class="p">*</span><span class="nf">pcre2_match_context_copy</span><span class="p">(</span> | |
| <span class="kt">pcre2_match_context</span> <span class="p">*</span><span class="nv">mcontext</span><span class="p">);</span> | |
| <span class="kt">void</span> <span class="nf">pcre2_match_context_free</span><span class="p">(</span><span class="kt">pcre2_match_context</span> <span class="p">*</span><span class="nv">mcontext</span><span class="p">);</span></code></pre></div> | |
| <p>A match context is created with default values for its parameters. These can | |
| be changed by calling the following functions, which return 0 on success, or | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_BADDATA</span></code> if invalid data is detected.</p> | |
| <p>The following functions get, respectively, the backtracking heap limit, match | |
| limit, depth limit, and offset limit. They return 0 and require both arguments | |
| to be non-<code class="constant pcre2-api rouge"><span class="kc">NULL</span></code>.</p> | |
| <div class="listing-block prototype"><pre class="rouge highlight"><code data-lang="c"><span class="kt">int</span> <span class="nf">pcre2_get_heap_limit</span><span class="p">(</span><span class="kt">pcre2_match_context</span> <span class="p">*</span><span class="nv">mcontext</span><span class="p">,</span> | |
| <span class="kt">uint32_t</span> <span class="p">*</span><span class="nv">limit</span><span class="p">);</span> | |
| <span class="kt">int</span> <span class="nf">pcre2_get_match_limit</span><span class="p">(</span><span class="kt">pcre2_match_context</span> <span class="p">*</span><span class="nv">mcontext</span><span class="p">,</span> | |
| <span class="kt">uint32_t</span> <span class="p">*</span><span class="nv">limit</span><span class="p">);</span> | |
| <span class="kt">int</span> <span class="nf">pcre2_get_depth_limit</span><span class="p">(</span><span class="kt">pcre2_match_context</span> <span class="p">*</span><span class="nv">mcontext</span><span class="p">,</span> | |
| <span class="kt">uint32_t</span> <span class="p">*</span><span class="nv">limit</span><span class="p">);</span> | |
| <span class="kt">int</span> <span class="nf">pcre2_get_offset_limit</span><span class="p">(</span><span class="kt">pcre2_match_context</span> <span class="p">*</span><span class="nv">mcontext</span><span class="p">,</span> | |
| <span class="kt">PCRE2_SIZE</span> <span class="p">*</span><span class="nv">limit</span><span class="p">);</span></code></pre></div> | |
| <p>The value returned by <code class="function pcre2-api rouge"><span class="nf">pcre2_get_offset_limit()</span></code> is the largest value a | |
| <code class="type pcre2-api rouge"><span class="kt">PCRE2_SIZE</span></code> variable can hold when there is no offset limit. Passing this value | |
| to <code class="function pcre2-api rouge"><span class="nf">pcre2_set_offset_limit()</span></code> removes the offset limit.</p> | |
| <div class="listing-block prototype"><pre class="rouge highlight"><code data-lang="c"><span class="kt">int</span> <span class="nf">pcre2_set_callout</span><span class="p">(</span><span class="kt">pcre2_match_context</span> <span class="p">*</span><span class="nv">mcontext</span><span class="p">,</span> | |
| <span class="kt">int</span> <span class="p">(</span><span class="p">*</span><span class="nv">callout</span><span class="p">)(</span> | |
| <span class="kt">pcre2_callout_block</span> <span class="p">*</span><span class="nv">callout_block</span><span class="p">,</span> | |
| <span class="kt">void</span> <span class="p">*</span><span class="nv">callout_data</span><span class="p">),</span> | |
| <span class="kt">void</span> <span class="p">*</span><span class="nv">callout_data</span><span class="p">);</span></code></pre></div> | |
| <p>This sets up a callout function for PCRE2 to call at specified points | |
| during a matching operation. Details are given in the | |
| <a href="./pcre2callout.html"><code>pcre2callout</code></a> | |
| documentation.</p> | |
| <div class="listing-block prototype"><pre class="rouge highlight"><code data-lang="c"><span class="kt">int</span> <span class="nf">pcre2_set_substitute_callout</span><span class="p">(</span> | |
| <span class="kt">pcre2_match_context</span> <span class="p">*</span><span class="nv">mcontext</span><span class="p">,</span> | |
| <span class="kt">int</span> <span class="p">(</span><span class="p">*</span><span class="nv">substitute_callout</span><span class="p">)(</span> | |
| <span class="kt">pcre2_substitute_callout_block</span> <span class="p">*</span><span class="nv">callout_block</span><span class="p">,</span> | |
| <span class="kt">void</span> <span class="p">*</span><span class="nv">substitute_callout_data</span><span class="p">),</span> | |
| <span class="kt">void</span> <span class="p">*</span><span class="nv">substitute_callout_data</span><span class="p">);</span></code></pre></div> | |
| <p>This sets up a callout function for PCRE2 to call after each substitution | |
| made by <code class="function pcre2-api rouge"><span class="nf">pcre2_substitute()</span></code>. Details are given in the section | |
| <a href="#creating-substitution-string">Creating a new string with substitutions</a> | |
| below.</p> | |
| <div class="listing-block prototype"><pre class="rouge highlight"><code data-lang="c"><span class="kt">int</span> <span class="nf">pcre2_set_substitute_case_callout</span><span class="p">(</span> | |
| <span class="kt">pcre2_match_context</span> <span class="p">*</span><span class="nv">mcontext</span><span class="p">,</span> | |
| <span class="nf">PCRE2_SIZE</span> <span class="p">(</span><span class="p">*</span><span class="nv">substitute_case_callout</span><span class="p">)(</span> | |
| <span class="kt">PCRE2_SPTR</span> <span class="nv">input</span><span class="p">,</span> <span class="kt">PCRE2_SIZE</span> <span class="nv">input_length</span><span class="p">,</span> | |
| <span class="kt">PCRE2_UCHAR</span> <span class="p">*</span><span class="nv">output</span><span class="p">,</span> <span class="kt">PCRE2_SIZE</span> <span class="nv">output_capacity</span><span class="p">,</span> | |
| <span class="kt">int</span> <span class="nv">case_operation</span><span class="p">,</span> <span class="kt">void</span> <span class="p">*</span><span class="nv">substitute_case_callout_data</span><span class="p">),</span> | |
| <span class="kt">void</span> <span class="p">*</span><span class="nv">substitute_case_callout_data</span><span class="p">);</span></code></pre></div> | |
| <p>This sets up a callout function for PCRE2 to call when performing case | |
| transformations inside <code class="function pcre2-api rouge"><span class="nf">pcre2_substitute()</span></code>. Details are given in the | |
| section <a href="#creating-substitution-string">Creating a new string with substitutions</a> | |
| below.</p> | |
| <div class="listing-block prototype"><pre class="rouge highlight"><code data-lang="c"><span class="kt">int</span> <span class="nf">pcre2_set_offset_limit</span><span class="p">(</span><span class="kt">pcre2_match_context</span> <span class="p">*</span><span class="nv">mcontext</span><span class="p">,</span> | |
| <span class="kt">PCRE2_SIZE</span> <span class="nv">limit</span><span class="p">);</span></code></pre></div> | |
| <p>The <code class="parameter pcre2-api rouge"><span class="nv">offset_limit</span></code> parameter limits how far an unanchored search can | |
| advance in the subject string. The default value is <code class="constant pcre2-api rouge"><span class="no">PCRE2_UNSET</span></code>. The | |
| value <code class="constant pcre2-api rouge"><span class="no">PCRE2_UNSET</span></code> removes the limit; any other value must not exceed the | |
| subject length in code units. <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> and <code class="function pcre2-api rouge"><span class="nf">pcre2_dfa_match()</span></code> | |
| return <code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_BADOFFSETLIMITVALUE</span></code> if this requirement is not met. | |
| When the subject length is specified as <code class="constant pcre2-api rouge"><span class="no">PCRE2_ZERO_TERMINATED</span></code>, the limit | |
| is checked against the actual string length. A limit equal to the subject | |
| length is permitted. The setter itself does not check this condition.</p> | |
| <p>For a valid limit, <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> and <code class="function pcre2-api rouge"><span class="nf">pcre2_dfa_match()</span></code> return | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_NOMATCH</span></code> if a match with a starting point before or at the given | |
| offset is not found. The <code class="function pcre2-api rouge"><span class="nf">pcre2_substitute()</span></code> function makes no more | |
| substitutions.</p> | |
| <p>For example, if the pattern <code class="regex rouge"><span class="pcre2-semantic">abc</span></code> is matched against <code class="subject rouge"><span class="pcre2-semantic">123abc</span></code> with an offset | |
| limit less than 3, the result is <code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_NOMATCH</span></code>. A match can never be | |
| found if the <code class="parameter pcre2-api rouge"><span class="nv">start_offset</span></code> argument of <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code>, | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_dfa_match()</span></code>, or <code class="function pcre2-api rouge"><span class="nf">pcre2_substitute()</span></code> is greater than the offset | |
| limit set in the match context.</p> | |
| <p>When using this facility, you must set the <code class="constant pcre2-api rouge"><span class="no">PCRE2_USE_OFFSET_LIMIT</span></code> option when | |
| calling <code class="function pcre2-api rouge"><span class="nf">pcre2_compile()</span></code> so that when JIT is in use, different code can be | |
| compiled. If a match is started with a non-default match limit when | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_USE_OFFSET_LIMIT</span></code> is not set, an error is generated.</p> | |
| <p>The offset limit facility can be used to track progress when searching large | |
| subject strings or to limit the extent of global substitutions. See also the | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_FIRSTLINE</span></code> option, which requires a match to start before or at the first | |
| newline that follows the start of matching in the subject. If this is set with | |
| an offset limit, a match must occur in the first line and also within the | |
| offset limit. In other words, whichever limit comes first is used.</p> | |
| <div class="listing-block prototype"><pre class="rouge highlight"><code data-lang="c"><span class="kt">int</span> <span class="nf">pcre2_set_heap_limit</span><span class="p">(</span><span class="kt">pcre2_match_context</span> <span class="p">*</span><span class="nv">mcontext</span><span class="p">,</span> | |
| <span class="kt">uint32_t</span> <span class="nv">limit</span><span class="p">);</span></code></pre></div> | |
| <p>The <code class="parameter pcre2-api rouge"><span class="nv">heap_limit</span></code> parameter specifies, in units of kibibytes (1024 bytes), | |
| the maximum amount of heap memory that <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> may use to hold | |
| backtracking information when running an interpretive match. This limit also | |
| applies to <code class="function pcre2-api rouge"><span class="nf">pcre2_dfa_match()</span></code>, which may use the heap when processing | |
| patterns with a lot of nested pattern recursion or lookarounds or atomic | |
| groups. This limit does not apply to matching with the JIT optimization, which | |
| has its own memory control arrangements (see the | |
| <a href="./pcre2jit.html"><code>pcre2jit</code></a> | |
| documentation for more details). If the limit is reached, the negative error | |
| code <code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_HEAPLIMIT</span></code> is returned. The default limit can be set when PCRE2 | |
| is built; if it is not, the default is set very large and is essentially | |
| unlimited.</p> | |
| <p>A value for the heap limit may also be supplied by an item at the start of a | |
| pattern of the form</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(*LIMIT_HEAP=<em>ddd</em>)</span></code></pre></div> | |
| <p>where <em>ddd</em> is a decimal number. However, such a setting is ignored unless <em>ddd</em> is | |
| less than the limit set by the caller of <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> or, if no such | |
| limit is set, less than the default.</p> | |
| <p>The <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> function always needs some heap memory, so setting a | |
| value of zero guarantees a "heap limit exceeded" error. Details of how | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> uses the heap are given in the | |
| <a href="./pcre2perform.html"><code>pcre2perform</code></a> | |
| documentation.</p> | |
| <p>For <code class="function pcre2-api rouge"><span class="nf">pcre2_dfa_match()</span></code>, a vector on the system stack is used when | |
| processing pattern recursions, lookarounds, or atomic groups, and only if this | |
| is not big enough is heap memory used. In this case, setting a value of zero | |
| disables the use of the heap.</p> | |
| <div class="listing-block prototype"><pre class="rouge highlight"><code data-lang="c"><span class="kt">int</span> <span class="nf">pcre2_set_match_limit</span><span class="p">(</span><span class="kt">pcre2_match_context</span> <span class="p">*</span><span class="nv">mcontext</span><span class="p">,</span> | |
| <span class="kt">uint32_t</span> <span class="nv">limit</span><span class="p">);</span></code></pre></div> | |
| <p>The <code class="parameter pcre2-api rouge"><span class="nv">match_limit</span></code> parameter provides a means of preventing PCRE2 from using | |
| up too many computing resources when processing patterns that are not going to | |
| match, but which have a very large number of possibilities in their search | |
| trees. The classic example is a pattern that uses nested unlimited repeats.</p> | |
| <p>There is an internal counter in <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> that is incremented each | |
| time round its main matching loop. If this value reaches the match limit, | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> returns the negative value <code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_MATCHLIMIT</span></code>. This has | |
| the effect of limiting the amount of backtracking that can take place. For | |
| patterns that are not anchored, the count restarts from zero for each position | |
| in the subject string. This limit also applies to <code class="function pcre2-api rouge"><span class="nf">pcre2_dfa_match()</span></code>, | |
| though the counting is done in a different way.</p> | |
| <p>When <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> is called with a pattern that was successfully | |
| processed by <code class="function pcre2-api rouge"><span class="nf">pcre2_jit_compile()</span></code>, the way in which matching is executed | |
| is entirely different. However, there is still the possibility of runaway | |
| matching that goes on for a very long time, and so the <code class="parameter pcre2-api rouge"><span class="nv">match_limit</span></code> value | |
| is also used in this case (but in a different way) to limit how long the | |
| matching can continue.</p> | |
| <p>The default value for the limit can be set when PCRE2 is built; the default is | |
| 10,000,000, which handles all but the most extreme cases. A value for the match | |
| limit may also be supplied by an item at the start of a pattern of the form</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(*LIMIT_MATCH=<em>ddd</em>)</span></code></pre></div> | |
| <p>where <em>ddd</em> is a decimal number. However, such a setting is ignored unless <em>ddd</em> is | |
| less than the limit set by the caller of <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> or | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_dfa_match()</span></code> or, if no such limit is set, less than the default.</p> | |
| <div class="listing-block prototype"><pre class="rouge highlight"><code data-lang="c"><span class="kt">int</span> <span class="nf">pcre2_set_depth_limit</span><span class="p">(</span><span class="kt">pcre2_match_context</span> <span class="p">*</span><span class="nv">mcontext</span><span class="p">,</span> | |
| <span class="kt">uint32_t</span> <span class="nv">limit</span><span class="p">);</span></code></pre></div> | |
| <p>This parameter limits the depth of nested backtracking in <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code>. | |
| Each time a nested backtracking point is passed, a new memory frame is used | |
| to remember the state of matching at that point. Thus, this parameter | |
| indirectly limits the amount of memory that is used in a match. However, | |
| because the size of each memory frame depends on the number of capturing | |
| parentheses, the actual memory limit varies from pattern to pattern. This limit | |
| was more useful in versions before 10.30, where function recursion was used for | |
| backtracking.</p> | |
| <p>The depth limit is not relevant, and is ignored, when matching is done using | |
| JIT compiled code. However, it is supported by <code class="function pcre2-api rouge"><span class="nf">pcre2_dfa_match()</span></code>, which | |
| uses it to limit the depth of nested internal recursive function calls that | |
| implement atomic groups, lookaround assertions, and pattern recursions. This | |
| limits, indirectly, the amount of system stack that is used. It was more useful | |
| in versions before 10.32, when stack memory was used for local workspace | |
| vectors for recursive function calls. From version 10.32, only local variables | |
| are allocated on the stack and as each call uses only a few hundred bytes, even | |
| a small stack can support quite a lot of recursion.</p> | |
| <p>If the depth of internal recursive function calls is great enough, local | |
| workspace vectors are allocated on the heap from version 10.32 onwards, so the | |
| depth limit also indirectly limits the amount of heap memory that is used. A | |
| recursive pattern such as <code class="regex rouge"><span class="pcre2-semantic">(.(?2))((?1)|)</span></code>, when matched to a very long string | |
| using <code class="function pcre2-api rouge"><span class="nf">pcre2_dfa_match()</span></code>, can use a great deal of memory. However, it is | |
| probably better to limit heap usage directly by calling | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_set_heap_limit()</span></code>.</p> | |
| <p>The default value for the depth limit can be set when PCRE2 is built; if it is | |
| not, the default is set to the same value as the default for the match limit. | |
| If the limit is exceeded, <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> or <code class="function pcre2-api rouge"><span class="nf">pcre2_dfa_match()</span></code> | |
| returns <code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_DEPTHLIMIT</span></code>. A value for the depth limit may also be | |
| supplied by an item at the start of a pattern of the form</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(*LIMIT_DEPTH=<em>ddd</em>)</span></code></pre></div> | |
| <p>where <em>ddd</em> is a decimal number. However, such a setting is ignored unless <em>ddd</em> is | |
| less than the limit set by the caller of <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> or | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_dfa_match()</span></code> or, if no such limit is set, less than the default.</p></section></section> | |
| <section class="doc-section level-1"><h2 id="_checking_build_time_options">Checking build-time options</h2><div class="listing-block prototype"><pre class="rouge highlight"><code data-lang="c"><span class="kt">int</span> <span class="nf">pcre2_config</span><span class="p">(</span><span class="kt">uint32_t</span> <span class="nv">what</span><span class="p">,</span> <span class="kt">void</span> <span class="p">*</span><span class="nv">where</span><span class="p">);</span></code></pre></div> | |
| <p>The function <code class="function pcre2-api rouge"><span class="nf">pcre2_config()</span></code> makes it possible for a PCRE2 client to find | |
| the value of certain configuration parameters and to discover which optional | |
| features have been compiled into the PCRE2 library. The | |
| <a href="./pcre2build.html"><code>pcre2build</code></a> | |
| documentation has more details about these features.</p> | |
| <p>The first argument for <code class="function pcre2-api rouge"><span class="nf">pcre2_config()</span></code> specifies which information is | |
| required. The second argument is a pointer to memory into which the information | |
| is placed. If <code class="constant pcre2-api rouge"><span class="kc">NULL</span></code> is passed, the function returns the amount of memory that is | |
| needed for the requested information. For calls that return numerical values, | |
| the value is in bytes; when requesting these values, <code class="parameter pcre2-api rouge"><span class="nv">where</span></code> should point | |
| to appropriately aligned memory. For calls that return strings, the required | |
| length is given in code units, including the terminating zero.</p> | |
| <p>When requesting information, the returned value from <code class="function pcre2-api rouge"><span class="nf">pcre2_config()</span></code> is | |
| non-negative on success, or the negative error code <code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_BADOPTION</span></code> if | |
| the value in the first argument is not recognized. The following information is | |
| available:</p> | |
| <dl class="options spaced" style="--tab-width: 14"><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_CONFIG_BSR</span></code></span></dt><dd>The output is a <code class="type pcre2-api rouge"><span class="kt">uint32_t</span></code> integer whose value indicates what character | |
| sequences the <code class="regex rouge"><span class="pcre2-semantic">\R</span></code> escape sequence matches by default. A value of | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_BSR_UNICODE</span></code> means that <code class="regex rouge"><span class="pcre2-semantic">\R</span></code> matches any Unicode line ending sequence; a | |
| value of <code class="constant pcre2-api rouge"><span class="no">PCRE2_BSR_ANYCRLF</span></code> means that <code class="regex rouge"><span class="pcre2-semantic">\R</span></code> matches only CR, LF, or CRLF. The | |
| default can be overridden when a pattern is compiled.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_CONFIG_COMPILED_WIDTHS</span></code></span></dt><dd>The output is a <code class="type pcre2-api rouge"><span class="kt">uint32_t</span></code> integer whose lower bits indicate which code unit | |
| widths were selected when PCRE2 was built. The 1-bit indicates 8-bit support, | |
| and the 2-bit and 4-bit indicate 16-bit and 32-bit support, respectively.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_CONFIG_DEPTHLIMIT</span></code></span></dt><dd>The output is a <code class="type pcre2-api rouge"><span class="kt">uint32_t</span></code> integer that gives the default limit for the depth of | |
| nested backtracking in <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> or the depth of nested recursions, | |
| lookarounds, and atomic groups in <code class="function pcre2-api rouge"><span class="nf">pcre2_dfa_match()</span></code>. Further details are | |
| given with <code class="function pcre2-api rouge"><span class="nf">pcre2_set_depth_limit()</span></code> above.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_CONFIG_EFFECTIVE_LINKSIZE</span></code></span></dt><dd>The output is a <code class="type pcre2-api rouge"><span class="kt">uint32_t</span></code> integer that contains the number of bytes the library | |
| uses for internal linkage in compiled regular expressions. Its value is derived | |
| from the value that was provided at build time and that is described below by | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_CONFIG_LINKSIZE</span></code>.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_CONFIG_HEAPLIMIT</span></code></span></dt><dd>The output is a <code class="type pcre2-api rouge"><span class="kt">uint32_t</span></code> integer that gives, in kibibytes, the default limit | |
| for the amount of heap memory used by <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> or | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_dfa_match()</span></code>. Further details are given with | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_set_heap_limit()</span></code> above.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_CONFIG_JIT</span></code></span></dt><dd>The output is a <code class="type pcre2-api rouge"><span class="kt">uint32_t</span></code> integer that is set to one if support for just-in-time | |
| compiling is included in the library; otherwise it is set to zero. Note that | |
| having the support in the library does not guarantee that JIT will be used for | |
| any given match, and neither does it guarantee that JIT will actually be able | |
| to function, because it may not be able to allocate executable memory in some | |
| environments. There is a special call to <code class="function pcre2-api rouge"><span class="nf">pcre2_jit_compile()</span></code> that can be | |
| used to check this. See the | |
| <a href="./pcre2jit.html"><code>pcre2jit</code></a> | |
| documentation for more details.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_CONFIG_JITTARGET</span></code></span></dt><dd>The <code class="parameter pcre2-api rouge"><span class="nv">where</span></code> argument should point to a code-unit-aligned buffer. All | |
| previous versions of PCRE2 have required no more than 128 code units of buffer | |
| capacity. However, this requirement is not guaranteed to be maintained, so | |
| applications should call <code class="function pcre2-api rouge"><span class="nf">pcre2_config()</span></code> with <code class="parameter pcre2-api rouge"><span class="nv">where</span></code> set to <code class="constant pcre2-api rouge"><span class="kc">NULL</span></code> to | |
| receive the required buffer size, then assert or allocate a suitably-size buffer | |
| for a second call to <code class="function pcre2-api rouge"><span class="nf">pcre2_config()</span></code>. The buffer is filled with a string | |
| that contains the name of the architecture for which the JIT compiler is | |
| configured at build time, for example, a 64-bit ARM CPU that supports the | |
| Armv8.1 extension writes <code>ARM-64 (LSE) 64bit (little endian + unaligned)</code>. If | |
| JIT support is not available, <code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_BADOPTION</span></code> is returned; otherwise the | |
| number of code units used is returned. This is the length of the string plus one | |
| unit for the terminating zero.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_CONFIG_LINKSIZE</span></code></span></dt><dd><p>The output is a <code class="type pcre2-api rouge"><span class="kt">uint32_t</span></code> integer that contains the number of bytes the library | |
| was instructed to use for internal linkage in compiled regular expressions. | |
| When PCRE2 is configured, the value can be set to 2, 3, or 4, with the default | |
| being 2 for most libraries.</p><p>The actual number of bytes used depends on the size of the code units that the | |
| library supports and can be higher. See <code class="constant pcre2-api rouge"><span class="no">PCRE2_CONFIG_EFFECTIVE_LINKSIZE</span></code> above | |
| for details.</p> | |
| <p>The default value of 2 for the 8-bit and 16-bit libraries is sufficient for all | |
| but the most massive patterns, since it allows the size of the compiled pattern | |
| to be up to 65,535 code units. Larger values allow larger regular expressions to | |
| be compiled by those two libraries, but at the expense of slower matching.</p></dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_CONFIG_MATCHLIMIT</span></code></span></dt><dd>The output is a <code class="type pcre2-api rouge"><span class="kt">uint32_t</span></code> integer that gives the default match limit for | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code>. Further details are given with | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_set_match_limit()</span></code> above.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_CONFIG_NEWLINE</span></code></span></dt><dd><p>The output is a <code class="type pcre2-api rouge"><span class="kt">uint32_t</span></code> integer whose value specifies the default character | |
| sequence that is recognized as meaning "newline". The values are:</p><div class="open-block"><div class="content"><dl class="compact" style="--tab-width: 14"><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_NEWLINE_CR</span></code> </span></dt><dd>Carriage return (CR)</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_NEWLINE_LF</span></code> </span></dt><dd>Linefeed (LF)</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_NEWLINE_CRLF</span></code> </span></dt><dd>Carriage return, linefeed (CRLF)</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_NEWLINE_ANY</span></code> </span></dt><dd>Any Unicode line ending</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_NEWLINE_ANYCRLF</span></code> </span></dt><dd>Any of CR, LF, or CRLF</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_NEWLINE_NUL</span></code> </span></dt><dd>The NUL character (binary zero)</dd></div></dl></div></div> | |
| <p>The default should normally correspond to the standard sequence for your | |
| operating system.</p></dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_CONFIG_NEVER_BACKSLASH_C</span></code></span></dt><dd>The output is a <code class="type pcre2-api rouge"><span class="kt">uint32_t</span></code> integer that is set to one if the use of <code class="regex rouge"><span class="pcre2-semantic">\C</span></code> was | |
| permanently disabled when PCRE2 was built; otherwise it is set to zero.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_CONFIG_PARENSLIMIT</span></code></span></dt><dd>The output is a <code class="type pcre2-api rouge"><span class="kt">uint32_t</span></code> integer that gives the maximum depth of nesting | |
| of parentheses (of any kind) in a pattern. This limit is imposed to cap the | |
| amount of system stack used when a pattern is compiled. It is specified when | |
| PCRE2 is built; the default is 250. This limit does not take into account the | |
| stack that may already be used by the calling application. For finer control | |
| over compilation stack usage, see <code class="function pcre2-api rouge"><span class="nf">pcre2_set_compile_recursion_guard()</span></code>.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_CONFIG_STACKRECURSE</span></code></span></dt><dd>This parameter is obsolete and should not be used in new code. The output is a | |
| <code class="type pcre2-api rouge"><span class="kt">uint32_t</span></code> integer that is always set to zero.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_CONFIG_TABLES_LENGTH</span></code></span></dt><dd>The output is a <code class="type pcre2-api rouge"><span class="kt">uint32_t</span></code> integer that gives the length of PCRE2’s character | |
| processing tables in bytes. For details of these tables see the | |
| section <a href="#locale-support">Locale support</a> | |
| below.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_CONFIG_UNICODE_VERSION</span></code></span></dt><dd>The <code class="parameter pcre2-api rouge"><span class="nv">where</span></code> argument should point to a code-unit-aligned buffer. All | |
| previous versions of PCRE2 have required no more than 24 code units of buffer | |
| capacity. However, applications should call <code class="function pcre2-api rouge"><span class="nf">pcre2_config()</span></code> with | |
| <code class="parameter pcre2-api rouge"><span class="nv">where</span></code> set to <code class="constant pcre2-api rouge"><span class="kc">NULL</span></code> to receive the required buffer size, then assert or | |
| allocate a suitably-size buffer for a second call to <code class="function pcre2-api rouge"><span class="nf">pcre2_config()</span></code>. If | |
| PCRE2 has been compiled without Unicode support, the buffer is filled with the | |
| text <code>Unicode not supported</code>. Otherwise, the Unicode version string (for | |
| example, <code>8.0.0</code>) is written. The number of code units used is returned. This is | |
| the length of the string plus one unit for the terminating zero.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_CONFIG_UNICODE</span></code></span></dt><dd>The output is a <code class="type pcre2-api rouge"><span class="kt">uint32_t</span></code> integer that is set to one if Unicode support is | |
| available; otherwise it is set to zero. Unicode support implies UTF support.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_CONFIG_VERSION</span></code></span></dt><dd>The <code class="parameter pcre2-api rouge"><span class="nv">where</span></code> argument should point to a code-unit-aligned buffer. All | |
| previous versions of PCRE2 have required no more than 24 code units of buffer | |
| capacity. However, applications should call <code class="function pcre2-api rouge"><span class="nf">pcre2_config()</span></code> with | |
| <code class="parameter pcre2-api rouge"><span class="nv">where</span></code> set to <code class="constant pcre2-api rouge"><span class="kc">NULL</span></code> to receive the required buffer size, then assert or | |
| allocate a suitably-size buffer for a second call to <code class="function pcre2-api rouge"><span class="nf">pcre2_config()</span></code>. The | |
| buffer is filled with the PCRE2 version string, zero-terminated. The number of | |
| code units used is returned. This is the length of the string plus one unit for | |
| the terminating zero.</dd></div></dl></section> | |
| <section class="doc-section level-1"><h2 id="compiling-a-pattern">Compiling a pattern</h2><div class="listing-block prototype"><pre class="rouge highlight"><code data-lang="c"><span class="kt">pcre2_code</span> <span class="p">*</span><span class="nf">pcre2_compile</span><span class="p">(</span><span class="kt">PCRE2_SPTR</span> <span class="nv">pattern</span><span class="p">,</span> <span class="kt">PCRE2_SIZE</span> <span class="nv">patlen</span><span class="p">,</span> | |
| <span class="kt">uint32_t</span> <span class="nv">options</span><span class="p">,</span> <span class="kt">int</span> <span class="p">*</span><span class="nv">errorptr</span><span class="p">,</span> | |
| <span class="kt">PCRE2_SIZE</span> <span class="p">*</span><span class="nv">erroroffset</span><span class="p">,</span> | |
| <span class="kt">pcre2_compile_context</span> <span class="p">*</span><span class="nv">ccontext</span><span class="p">);</span> | |
| <span class="kt">void</span> <span class="nf">pcre2_code_free</span><span class="p">(</span><span class="kt">pcre2_code</span> <span class="p">*</span><span class="nv">code</span><span class="p">);</span> | |
| <span class="kt">pcre2_code</span> <span class="p">*</span><span class="nf">pcre2_code_copy</span><span class="p">(</span><span class="kt">const</span> <span class="kt">pcre2_code</span> <span class="p">*</span><span class="nv">code</span><span class="p">);</span> | |
| <span class="kt">pcre2_code</span> <span class="p">*</span><span class="nf">pcre2_code_copy_with_tables</span><span class="p">(</span><span class="kt">const</span> <span class="kt">pcre2_code</span> <span class="p">*</span><span class="nv">code</span><span class="p">);</span></code></pre></div> | |
| <p>The <code class="function pcre2-api rouge"><span class="nf">pcre2_compile()</span></code> function compiles a pattern into an internal form. | |
| The pattern is defined by a pointer to a string of code units and a length in | |
| code units. If the pattern is zero-terminated, the length can be specified as | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_ZERO_TERMINATED</span></code>. A <code class="constant pcre2-api rouge"><span class="kc">NULL</span></code> pattern pointer with a length of zero is treated | |
| as an empty string (<code class="constant pcre2-api rouge"><span class="kc">NULL</span></code> with a non-zero length causes an error return). The | |
| function returns a pointer to a block of memory that contains the compiled | |
| pattern and related data, or <code class="constant pcre2-api rouge"><span class="kc">NULL</span></code> if an error occurred.</p> | |
| <p>If the compile context argument <code class="parameter pcre2-api rouge"><span class="nv">ccontext</span></code> is <code class="constant pcre2-api rouge"><span class="kc">NULL</span></code>, memory for the compiled | |
| pattern is obtained by calling <code class="c rouge" data-lang="c"><span class="nf">malloc</span><span class="p">()</span></code>. Otherwise, it is obtained from | |
| the same memory function that was used for the compile context. The caller must | |
| free the memory by calling <code class="function pcre2-api rouge"><span class="nf">pcre2_code_free()</span></code> when it is no longer needed. | |
| If <code class="function pcre2-api rouge"><span class="nf">pcre2_code_free()</span></code> is called with a <code class="constant pcre2-api rouge"><span class="kc">NULL</span></code> argument, it returns | |
| immediately, without doing anything.</p> | |
| <p>The function <code class="function pcre2-api rouge"><span class="nf">pcre2_code_copy()</span></code> makes a copy of the compiled code in new | |
| memory, using the same memory allocator as was used for the original. However, | |
| if the code has been processed by the JIT compiler (see | |
| below), | |
| the JIT information cannot be copied (because it is position-dependent). | |
| The new copy can initially be used only for non-JIT matching, though it can be | |
| passed to <code class="function pcre2-api rouge"><span class="nf">pcre2_jit_compile()</span></code> if required. If <code class="function pcre2-api rouge"><span class="nf">pcre2_code_copy()</span></code> is | |
| called with a <code class="constant pcre2-api rouge"><span class="kc">NULL</span></code> argument, it returns <code class="constant pcre2-api rouge"><span class="kc">NULL</span></code>.</p> | |
| <p>The <code class="function pcre2-api rouge"><span class="nf">pcre2_code_copy()</span></code> function provides a way for individual threads in a | |
| multithreaded application to acquire a private copy of shared compiled code. | |
| However, it does not make a copy of the character tables used by the compiled | |
| pattern; the new pattern code points to the same tables as the original code. | |
| (See | |
| "Locale Support" | |
| below for details of these character tables.) In many applications the same | |
| tables are used throughout, so this behaviour is appropriate. Nevertheless, | |
| there are occasions when a copy of a compiled pattern and the relevant tables | |
| are needed. The <code class="function pcre2-api rouge"><span class="nf">pcre2_code_copy_with_tables()</span></code> provides this facility. | |
| Copies of both the code and the tables are made, with the new code pointing to | |
| the new tables. The memory for the new tables is automatically freed when | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_code_free()</span></code> is called for the new copy of the compiled code. If | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_code_copy_with_tables()</span></code> is called with a <code class="constant pcre2-api rouge"><span class="kc">NULL</span></code> argument, it returns | |
| <code class="constant pcre2-api rouge"><span class="kc">NULL</span></code>.</p> | |
| <aside class="admonition-block note" role="note"><h6 class="block-title label-only"><span class="title-label">Note: </span></h6><p>When one of the matching functions is called, pointers to the compiled | |
| pattern and the subject string are set in the match data block so that they can | |
| be referenced by the substring extraction functions after a successful match. | |
| After running a match, you must not free a compiled pattern or a subject string | |
| until after all operations on the | |
| match data block | |
| have taken place, unless, in the case of the subject string, you have used the | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_COPY_MATCHED_SUBJECT</span></code> option, which is described in the section | |
| <a href="#match-option-bits">Option bits for <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code></a> | |
| below.</p></aside> | |
| <p>The <code class="parameter pcre2-api rouge"><span class="nv">options</span></code> argument for <code class="function pcre2-api rouge"><span class="nf">pcre2_compile()</span></code> contains various bit | |
| settings that affect the compilation. It should be zero if none of them are | |
| required. The available options are described below. Some of them (in | |
| particular, those that are compatible with Perl, but some others as well) can | |
| also be set and unset from within the pattern (see the detailed description in | |
| the | |
| <a href="./pcre2pattern.html"><code>pcre2pattern</code></a> | |
| documentation).</p> | |
| <p>For those options that can be different in different parts of the pattern, the | |
| contents of the <code class="parameter pcre2-api rouge"><span class="nv">options</span></code> argument specifies their settings at the start of | |
| compilation. The <code class="constant pcre2-api rouge"><span class="no">PCRE2_ANCHORED</span></code>, <code class="constant pcre2-api rouge"><span class="no">PCRE2_ENDANCHORED</span></code>, and <code class="constant pcre2-api rouge"><span class="no">PCRE2_NO_UTF_CHECK</span></code> | |
| options can be set at the time of matching as well as at compile time.</p> | |
| <p>Some additional options and less frequently required compile-time parameters | |
| (for example, the newline setting) can be provided in a compile context (as | |
| described | |
| above).</p> | |
| <p>If <code class="parameter pcre2-api rouge"><span class="nv">errorcode</span></code> or <code class="parameter pcre2-api rouge"><span class="nv">erroroffset</span></code> is <code class="constant pcre2-api rouge"><span class="kc">NULL</span></code>, <code class="function pcre2-api rouge"><span class="nf">pcre2_compile()</span></code> returns | |
| <code class="constant pcre2-api rouge"><span class="kc">NULL</span></code> immediately. Otherwise, the variables to which these point are set to an | |
| error code and an offset (number of code units) within the pattern, | |
| respectively, when <code class="function pcre2-api rouge"><span class="nf">pcre2_compile()</span></code> returns <code class="constant pcre2-api rouge"><span class="kc">NULL</span></code> because a compilation | |
| error has occurred.</p> | |
| <p>There are over 100 positive error codes that <code class="function pcre2-api rouge"><span class="nf">pcre2_compile()</span></code> may return | |
| if it finds an error in the pattern. There are also some negative error codes | |
| that are used for invalid UTF strings when validity checking is in force. These | |
| are the same as given by <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> and <code class="function pcre2-api rouge"><span class="nf">pcre2_dfa_match()</span></code>, and | |
| are described in the | |
| <a href="./pcre2unicode.html"><code>pcre2unicode</code></a> | |
| documentation. There is no separate documentation for the positive error codes, | |
| because the textual error messages that are obtained by calling the | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_get_error_message()</span></code> function (see "Obtaining a textual error | |
| message" | |
| below) | |
| should be self-explanatory. Macro names starting with <code>PCRE2_ERROR_</code> are defined | |
| for both positive and negative error codes in <code>pcre2.h</code>. When compilation | |
| is successful <code class="c rouge" data-lang="c"><span class="p">*</span><span class="nv">errorptr</span></code> is set to a value that returns the message <code>no | |
| error</code> if passed to <code class="function pcre2-api rouge"><span class="nf">pcre2_get_error_message()</span></code>.</p> | |
| <p>The value returned in <code class="c rouge" data-lang="c"><span class="p">*</span><span class="nv">erroroffset</span></code> is an indication of where in the | |
| pattern an error occurred. When there is no error, zero is returned. A non-zero | |
| value is not necessarily the furthest point in the pattern that was read. For | |
| example, after the error "lookbehind assertion is not fixed length", the error | |
| offset points to the start of the failing assertion. For an invalid UTF-8 or | |
| UTF-16 string, the offset is that of the first code unit of the failing | |
| character.</p> | |
| <p>Some errors are not detected until the whole pattern has been scanned; in these | |
| cases, the offset passed back is the length of the pattern. Note that the | |
| offset is in code units, not characters, even in a UTF mode. It may sometimes | |
| point into the middle of a UTF-8 or UTF-16 character.</p> | |
| <p>This code fragment shows a typical straightforward call to | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_compile()</span></code>:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="c"><span class="kt">pcre2_code</span> <span class="p">*</span><span class="nv">re</span><span class="p">;</span> | |
| <span class="kt">PCRE2_SIZE</span> <span class="nv">erroffset</span><span class="p">;</span> | |
| <span class="kt">int</span> <span class="nv">errorcode</span><span class="p">;</span> | |
| <span class="nv">re</span> <span class="o">=</span> <span class="nf">pcre2_compile</span><span class="p">(</span> | |
| <span class="s">"^A.*Z"</span><span class="p">,</span> <span class="cm">/* the pattern */</span> | |
| <span class="no">PCRE2_ZERO_TERMINATED</span><span class="p">,</span> <span class="cm">/* the pattern is zero-terminated */</span> | |
| <span class="mi">0</span><span class="p">,</span> <span class="cm">/* default options */</span> | |
| <span class="p">&</span><span class="nv">errorcode</span><span class="p">,</span> <span class="cm">/* for error code */</span> | |
| <span class="p">&</span><span class="nv">erroffset</span><span class="p">,</span> <span class="cm">/* for error offset */</span> | |
| <span class="kc">NULL</span><span class="p">);</span> <span class="cm">/* no compile context */</span></code></pre></div> | |
| <section class="doc-section level-2"><h3 id="_main_compile_options">Main compile options</h3><p>The following names for option bits are defined in the <code>pcre2.h</code> header | |
| file:</p> | |
| <dl class="options spaced" style="--tab-width: 14"><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_ANCHORED</span></code></span></dt><dd>If this bit is set, the pattern is forced to be "anchored", that is, it is | |
| constrained to match only at the first matching point in the string that is | |
| being searched (the "subject string"). This effect can also be achieved by | |
| appropriate constructs in the pattern itself, which is the only way to do it in | |
| Perl.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_ALLOW_EMPTY_CLASS</span></code></span></dt><dd>By default, for compatibility with Perl, a closing square bracket that | |
| immediately follows an opening one is treated as a data character for the | |
| class. When <code class="constant pcre2-api rouge"><span class="no">PCRE2_ALLOW_EMPTY_CLASS</span></code> is set, it terminates the class, which | |
| therefore contains no characters and so can never match.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_ALT_BSUX</span></code></span></dt><dd><p>This option request alternative handling of three escape sequences, which | |
| makes PCRE2’s behaviour more like ECMAScript (JavaScript). When it is set:</p><ol class="arabic compact"><li><code class="regex rouge"><span class="pcre2-semantic">\U</span></code> matches an upper case <code class="subject rouge"><span class="pcre2-semantic">U</span></code> character; by default <code class="regex rouge"><span class="pcre2-semantic">\U</span></code> causes a compile | |
| time error (Perl uses <code class="regex rouge"><span class="pcre2-semantic">\U</span></code> to upper case subsequent characters).</li><li><code class="regex rouge"><span class="pcre2-semantic">\u</span></code> matches a lower case <code class="subject rouge"><span class="pcre2-semantic">u</span></code> character unless it is followed by four | |
| hexadecimal digits, in which case the hexadecimal number defines the code point | |
| to match. By default, <code class="regex rouge"><span class="pcre2-semantic">\u</span></code> causes a compile time error (Perl uses it to upper | |
| case the following character).</li><li><code class="regex rouge"><span class="pcre2-semantic">\x</span></code> matches a lower case <code class="subject rouge"><span class="pcre2-semantic">x</span></code> character unless it is followed by two | |
| hexadecimal digits, in which case the hexadecimal number defines the code point | |
| to match. By default, as in Perl, a hexadecimal number is always expected after | |
| <code class="regex rouge"><span class="pcre2-semantic">\x</span></code>, but it may have one or two digits.</li></ol> | |
| <p>ECMAScript 6 added additional functionality to <code class="regex rouge"><span class="pcre2-semantic">\u</span></code>. This can be accessed using | |
| the <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_ALT_BSUX</span></code> extra option (see "Extra compile options" | |
| below). | |
| Note that this alternative escape handling applies only to patterns. Neither of | |
| these options affects the processing of replacement strings passed to | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_substitute()</span></code>.</p></dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_ALT_CIRCUMFLEX</span></code></span></dt><dd>In multiline mode (when <code class="constant pcre2-api rouge"><span class="no">PCRE2_MULTILINE</span></code> is set), the circumflex metacharacter | |
| matches at the start of the subject (unless <code class="constant pcre2-api rouge"><span class="no">PCRE2_NOTBOL</span></code> is set), and also | |
| after any internal newline. However, it does not match after a newline at the | |
| end of the subject, for compatibility with Perl. If you want a multiline | |
| circumflex also to match after a terminating newline, you must set | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_ALT_CIRCUMFLEX</span></code>.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_ALT_EXTENDED_CLASS</span></code></span></dt><dd>Alters the parsing of character classes to follow the extended syntax | |
| described by Unicode UTS#18. The <code class="constant pcre2-api rouge"><span class="no">PCRE2_ALT_EXTENDED_CLASS</span></code> option has no impact | |
| on the behaviour of the Perl-specific <code class="regex rouge"><span class="pcre2-semantic">(?[...])</span></code> syntax for extended classes, | |
| but instead enables the alternative syntax of extended class behaviour inside | |
| ordinary <code class="regex rouge"><span class="pcre2-semantic">[...]</span></code> character classes. See the | |
| <a href="./pcre2pattern.html"><code>pcre2pattern</code></a> | |
| documentation for details of the character classes supported.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_ALT_VERBNAMES</span></code></span></dt><dd>By default, for compatibility with Perl, the name in any verb sequence such as | |
| <code class="regex rouge"><span class="pcre2-semantic">(*MARK:<em>NAME</em>)</span></code> is any sequence of characters that does not include a closing | |
| parenthesis. The name is not processed in any way, and it is not possible to | |
| include a closing parenthesis in the name. However, if the <code class="constant pcre2-api rouge"><span class="no">PCRE2_ALT_VERBNAMES</span></code> | |
| option is set, normal backslash processing is applied to verb names and only an | |
| unescaped closing parenthesis terminates the name. A closing parenthesis can be | |
| included in a name either as <code class="regex rouge"><span class="pcre2-semantic">\)</span></code> or between <code class="regex rouge"><span class="pcre2-semantic">\Q</span></code> and <code class="regex rouge"><span class="pcre2-semantic">\E</span></code>. If the <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTENDED</span></code> | |
| or <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTENDED_MORE</span></code> option is set with <code class="constant pcre2-api rouge"><span class="no">PCRE2_ALT_VERBNAMES</span></code>, unescaped | |
| white space in verb names is skipped and #-comments are recognized, exactly as | |
| in the rest of the pattern.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_AUTO_CALLOUT</span></code></span></dt><dd>If this bit is set, <code class="function pcre2-api rouge"><span class="nf">pcre2_compile()</span></code> automatically inserts callout items, | |
| all with number 255, before each pattern item, except immediately before or | |
| after an explicit callout in the pattern. For discussion of the callout | |
| facility, see the | |
| <a href="./pcre2callout.html"><code>pcre2callout</code></a> | |
| documentation.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_CASELESS</span></code></span></dt><dd><p>If this bit is set, letters in the pattern match both upper and lower case | |
| letters in the subject. It is equivalent to Perl’s <code class="regex rouge"><span class="pcre2-semantic">/i</span></code> option, and it can be | |
| changed within a pattern by a <code class="regex rouge"><span class="pcre2-semantic">(?i)</span></code> option setting. If either <code class="constant pcre2-api rouge"><span class="no">PCRE2_UTF</span></code> or | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_UCP</span></code> is set, Unicode properties are used for all characters with more than | |
| one other case, and for all characters whose code points are greater than | |
| <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-6"><code class="character pcre2-api rouge"><span class="sc">U+007F</span></code><span class="character-card" id="pcre2-character-6" role="tooltip" aria-label="DELETE (U+007F)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="DELETE"></span><span class="character-codepoint" data-codepoint="U+007F"></span></span></span>.</p><p>Note that there are two ASCII characters, K and S, that, in addition to | |
| their lower case ASCII equivalents, are case-equivalent with <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-7"><code class="character pcre2-api rouge"><span class="sc">U+212A</span></code><span class="character-card" id="pcre2-character-7" role="tooltip" aria-label="KELVIN SIGN (U+212A)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character="K"></span><span class="character-name" data-character-name="KELVIN SIGN"></span><span class="character-codepoint" data-codepoint="U+212A"></span></span></span> (Kelvin | |
| sign) and <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-8"><code class="character pcre2-api rouge"><span class="sc">U+017F</span></code><span class="character-card" id="pcre2-character-8" role="tooltip" aria-label="LATIN SMALL LETTER LONG S (U+017F)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character="ſ"></span><span class="character-name" data-character-name="LATIN SMALL LETTER LONG S"></span><span class="character-codepoint" data-codepoint="U+017F"></span></span></span> (long S) respectively. If you do not want this case | |
| equivalence, you can suppress it by setting <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_CASELESS_RESTRICT</span></code>.</p> | |
| <p>One language family, Turkish and Azeri, has its own case-insensitivity rules, | |
| which can be selected by setting <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_TURKISH_CASING</span></code>. This alters the | |
| behaviour of the 'i', 'I', <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-9"><code class="character pcre2-api rouge"><span class="sc">U+0130</span></code><span class="character-card" id="pcre2-character-9" role="tooltip" aria-label="LATIN CAPITAL LETTER I WITH DOT ABOVE (U+0130)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character="İ"></span><span class="character-name" data-character-name="LATIN CAPITAL LETTER I WITH DOT ABOVE"></span><span class="character-codepoint" data-codepoint="U+0130"></span></span></span> (capital I with dot above), and <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-10"><code class="character pcre2-api rouge"><span class="sc">U+0131</span></code><span class="character-card" id="pcre2-character-10" role="tooltip" aria-label="LATIN SMALL LETTER DOTLESS I (U+0131)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character="ı"></span><span class="character-name" data-character-name="LATIN SMALL LETTER DOTLESS I"></span><span class="character-codepoint" data-codepoint="U+0131"></span></span></span> | |
| (small dotless i) characters.</p> | |
| <p>For lower valued characters with only one other case, a lookup table is used | |
| for speed. When neither <code class="constant pcre2-api rouge"><span class="no">PCRE2_UTF</span></code> nor <code class="constant pcre2-api rouge"><span class="no">PCRE2_UCP</span></code> is set, a lookup table is used | |
| for all code points less than 256, and higher code points (available only in | |
| 16-bit or 32-bit mode) are treated as not having another case.</p> | |
| <p>From release 10.45 <code class="constant pcre2-api rouge"><span class="no">PCRE2_CASELESS</span></code> also affects what some of the letter-related | |
| Unicode property escapes (<code class="regex rouge"><span class="pcre2-semantic">\p</span></code> and <code class="regex rouge"><span class="pcre2-semantic">\P</span></code>) match. The properties <code class="regex rouge"><span class="pcre2-semantic">Lu</span></code> (upper case | |
| letter), <code class="regex rouge"><span class="pcre2-semantic">Ll</span></code> (lower case letter), and <code class="regex rouge"><span class="pcre2-semantic">Lt</span></code> (title case letter) are all treated as | |
| <code class="regex rouge"><span class="pcre2-semantic">Lc</span></code> (cased letter) when <code class="constant pcre2-api rouge"><span class="no">PCRE2_CASELESS</span></code> is set.</p></dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_DOLLAR_ENDONLY</span></code></span></dt><dd>If this bit is set, a dollar metacharacter in the pattern matches only at the | |
| end of the subject string. Without this option, a dollar also matches | |
| immediately before a newline at the end of the string (but not before any other | |
| newlines). The <code class="constant pcre2-api rouge"><span class="no">PCRE2_DOLLAR_ENDONLY</span></code> option is ignored if <code class="constant pcre2-api rouge"><span class="no">PCRE2_MULTILINE</span></code> is | |
| set. There is no equivalent to this option in Perl, and no way to set it within | |
| a pattern.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_DOTALL</span></code></span></dt><dd>If this bit is set, a dot metacharacter in the pattern matches any character, | |
| including one that indicates a newline. However, it only ever matches one | |
| character, even if newlines are coded as CRLF. Without this option, a dot does | |
| not match when the current position in the subject is at a newline. This option | |
| is equivalent to Perl’s <code class="regex rouge"><span class="pcre2-semantic">/s</span></code> option, and it can be changed within a pattern by a | |
| <code class="regex rouge"><span class="pcre2-semantic">(?s)</span></code> option setting. A negative class such as <code class="regex rouge"><span class="pcre2-semantic">[^a]</span></code> always matches newline | |
| characters, and the <code class="regex rouge"><span class="pcre2-semantic">\N</span></code> escape sequence always matches a non-newline character, | |
| independent of the setting of <code class="constant pcre2-api rouge"><span class="no">PCRE2_DOTALL</span></code>.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_DUPNAMES</span></code></span></dt><dd>If this bit is set, names used to identify capture groups need not be unique. | |
| This can be helpful for certain types of pattern when it is known that only one | |
| instance of the named group can ever be matched. There are more details of | |
| named capture groups below; see also the | |
| <a href="./pcre2pattern.html"><code>pcre2pattern</code></a> | |
| documentation.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_ENDANCHORED</span></code></span></dt><dd><p>If this bit is set, the end of any pattern match must be right at the end of | |
| the string being searched (the "subject string"). If the pattern match | |
| succeeds by reaching <code class="regex rouge"><span class="pcre2-semantic">(*ACCEPT)</span></code>, but does not reach the end of the subject, the | |
| match fails at the current starting point. For unanchored patterns, a new match | |
| is then tried at the next starting point. However, if the match succeeds by | |
| reaching the end of the pattern, but not the end of the subject, backtracking | |
| occurs and an alternative match may be found. Consider these two patterns:</p><div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">.(*ACCEPT)|.. | |
| .|..</span></code></pre></div> | |
| <p>If matched against <code class="subject rouge"><span class="pcre2-semantic">abc</span></code> with <code class="constant pcre2-api rouge"><span class="no">PCRE2_ENDANCHORED</span></code> set, the first matches <code class="subject rouge"><span class="pcre2-semantic">c</span></code> | |
| whereas the second matches <code class="subject rouge"><span class="pcre2-semantic">bc</span></code>. The effect of <code class="constant pcre2-api rouge"><span class="no">PCRE2_ENDANCHORED</span></code> can also be | |
| achieved by appropriate constructs in the pattern itself, which is the only way | |
| to do it in Perl.</p> | |
| <p>For DFA matching with <code class="function pcre2-api rouge"><span class="nf">pcre2_dfa_match()</span></code>, <code class="constant pcre2-api rouge"><span class="no">PCRE2_ENDANCHORED</span></code> applies only | |
| to the first (that is, the longest) matched string. Other parallel matches, | |
| which are necessarily substrings of the first one, must obviously end before | |
| the end of the subject.</p></dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTENDED</span></code></span></dt><dd><p>If this bit is set, most white space characters in the pattern are totally | |
| ignored except when escaped, inside a character class, or inside a <code class="regex rouge"><span class="pcre2-semantic">\Q...\E</span></code> | |
| sequence. However, white space is not allowed within sequences such as <code class="regex rouge"><span class="pcre2-semantic">(?></span></code> that | |
| introduce various parenthesized groups, nor within numerical quantifiers such as | |
| <code class="regex rouge"><span class="pcre2-semantic">{1,3}</span></code>. Ignorable white space is permitted between an item and a following | |
| quantifier and between a quantifier and a following <code class="regex rouge"><span class="pcre2-semantic">+</span></code> that indicates | |
| possessiveness. <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTENDED</span></code> is equivalent to Perl’s <code class="regex rouge"><span class="pcre2-semantic">/x</span></code> option, and it can be | |
| changed within a pattern by a <code class="regex rouge"><span class="pcre2-semantic">(?x)</span></code> option setting.</p><p>When PCRE2 is compiled without Unicode support, <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTENDED</span></code> recognizes as | |
| white space only those characters with code points less than 256 that are | |
| flagged as white space in its low-character table. The table is normally | |
| created by | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_maketables()</span></code>, | |
| which uses the <code class="c rouge" data-lang="c"><span class="nf">isspace</span><span class="p">()</span></code> function to identify space characters. In most | |
| ASCII environments, the relevant characters are those with code points <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-11"><code class="character pcre2-api rouge"><span class="sc">0x0009</span></code><span class="character-card" id="pcre2-character-11" role="tooltip" aria-label="CHARACTER TABULATION (U+0009)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="CHARACTER TABULATION"></span><span class="character-codepoint" data-codepoint="U+0009"></span></span></span> | |
| (tab), <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-12"><code class="character pcre2-api rouge"><span class="sc">0x000A</span></code><span class="character-card" id="pcre2-character-12" role="tooltip" aria-label="LINE FEED (U+000A)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="LINE FEED"></span><span class="character-codepoint" data-codepoint="U+000A"></span></span></span> (linefeed), <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-13"><code class="character pcre2-api rouge"><span class="sc">0x000B</span></code><span class="character-card" id="pcre2-character-13" role="tooltip" aria-label="LINE TABULATION (U+000B)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="LINE TABULATION"></span><span class="character-codepoint" data-codepoint="U+000B"></span></span></span> (vertical tab), <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-14"><code class="character pcre2-api rouge"><span class="sc">0x000C</span></code><span class="character-card" id="pcre2-character-14" role="tooltip" aria-label="FORM FEED (U+000C)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="FORM FEED"></span><span class="character-codepoint" data-codepoint="U+000C"></span></span></span> (formfeed), <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-15"><code class="character pcre2-api rouge"><span class="sc">0x000D</span></code><span class="character-card" id="pcre2-character-15" role="tooltip" aria-label="CARRIAGE RETURN (U+000D)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="CARRIAGE RETURN"></span><span class="character-codepoint" data-codepoint="U+000D"></span></span></span> | |
| (carriage return), and <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-16"><code class="character pcre2-api rouge"><span class="sc">0x0020</span></code><span class="character-card" id="pcre2-character-16" role="tooltip" aria-label="SPACE (U+0020)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="SPACE"></span><span class="character-codepoint" data-codepoint="U+0020"></span></span></span> (space).</p> | |
| <p>When PCRE2 is compiled with Unicode support, in addition to these characters, | |
| five more Unicode "Pattern White Space" characters are recognized by | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTENDED</span></code>. These are <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-17"><code class="character pcre2-api rouge"><span class="sc">U+0085</span></code><span class="character-card" id="pcre2-character-17" role="tooltip" aria-label="NEXT LINE (U+0085)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="NEXT LINE"></span><span class="character-codepoint" data-codepoint="U+0085"></span></span></span> (next line), <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-18"><code class="character pcre2-api rouge"><span class="sc">U+200E</span></code><span class="character-card" id="pcre2-character-18" role="tooltip" aria-label="LEFT-TO-RIGHT MARK (U+200E)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="LEFT-TO-RIGHT MARK"></span><span class="character-codepoint" data-codepoint="U+200E"></span></span></span> (left-to-right mark), | |
| <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-19"><code class="character pcre2-api rouge"><span class="sc">U+200F</span></code><span class="character-card" id="pcre2-character-19" role="tooltip" aria-label="RIGHT-TO-LEFT MARK (U+200F)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="RIGHT-TO-LEFT MARK"></span><span class="character-codepoint" data-codepoint="U+200F"></span></span></span> (right-to-left mark), <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-20"><code class="character pcre2-api rouge"><span class="sc">U+2028</span></code><span class="character-card" id="pcre2-character-20" role="tooltip" aria-label="LINE SEPARATOR (U+2028)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="LINE SEPARATOR"></span><span class="character-codepoint" data-codepoint="U+2028"></span></span></span> (line separator), and <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-21"><code class="character pcre2-api rouge"><span class="sc">U+2029</span></code><span class="character-card" id="pcre2-character-21" role="tooltip" aria-label="PARAGRAPH SEPARATOR (U+2029)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="PARAGRAPH SEPARATOR"></span><span class="character-codepoint" data-codepoint="U+2029"></span></span></span> (paragraph | |
| separator). This set of characters is the same as recognized by Perl’s <code class="regex rouge"><span class="pcre2-semantic">/x</span></code> | |
| option. Note that the horizontal and vertical space characters that are matched | |
| by the <code class="regex rouge"><span class="pcre2-semantic">\h</span></code> and <code class="regex rouge"><span class="pcre2-semantic">\v</span></code> escapes in patterns are a much bigger set.</p> | |
| <p>As well as ignoring most white space, <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTENDED</span></code> also causes characters | |
| between an unescaped # outside a character class and the next newline, | |
| inclusive, to be ignored, which makes it possible to include comments inside | |
| complicated patterns. Note that the end of this type of comment is a literal | |
| newline sequence in the pattern; escape sequences that happen to represent a | |
| newline do not count.</p> | |
| <p>Which characters are interpreted as newlines can be specified by a setting in | |
| the compile context that is passed to <code class="function pcre2-api rouge"><span class="nf">pcre2_compile()</span></code> or by a special | |
| sequence at the start of the pattern, as described in the section entitled | |
| "Newline conventions" | |
| in the <code>pcre2pattern</code> documentation. A default is defined when PCRE2 is | |
| built.</p></dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTENDED_MORE</span></code></span></dt><dd>This option has the effect of <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTENDED</span></code>, but, in addition, unescaped space | |
| and horizontal tab characters are ignored inside a character class. Note: only | |
| these two characters are ignored, not the full set of pattern white space | |
| characters that are ignored outside a character class. <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTENDED_MORE</span></code> is | |
| equivalent to Perl’s <code class="regex rouge"><span class="pcre2-semantic">/xx</span></code> option, and it can be changed within a pattern by a | |
| <code class="regex rouge"><span class="pcre2-semantic">(?xx)</span></code> option setting.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_FIRSTLINE</span></code></span></dt><dd>If this option is set, the start of an unanchored pattern match must be before | |
| or at the first newline in the subject string following the start of matching, | |
| though the matched text may continue over the newline. If <code class="parameter pcre2-api rouge"><span class="nv">start_offset</span></code> is | |
| non-zero, the limiting newline is not necessarily the first newline in the | |
| subject. For example, if the subject string is <code class="subject rouge"><span class="pcre2-semantic">abc\nxyz</span></code> (where <code class="regex rouge"><span class="pcre2-semantic">\n</span></code> | |
| represents a single-character newline) a pattern match for <code class="regex rouge"><span class="pcre2-semantic">yz</span></code> succeeds with | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_FIRSTLINE</span></code> if <code class="parameter pcre2-api rouge"><span class="nv">start_offset</span></code> is greater than 3. See also | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_USE_OFFSET_LIMIT</span></code>, which provides a more general limiting facility. If | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_FIRSTLINE</span></code> is set with an offset limit, a match must occur in the first | |
| line and also within the offset limit. In other words, whichever limit comes | |
| first is used. This option has no effect for anchored patterns.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_LITERAL</span></code></span></dt><dd>If this option is set, all meta-characters in the pattern are disabled, and it | |
| is treated as a literal string. Matching literal strings with a regular | |
| expression engine is not the most efficient way of doing it. If you are doing a | |
| lot of literal matching and are worried about efficiency, you should consider | |
| using other approaches. The only other main options that are allowed with | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_LITERAL</span></code> are: <code class="constant pcre2-api rouge"><span class="no">PCRE2_ANCHORED</span></code>, <code class="constant pcre2-api rouge"><span class="no">PCRE2_ENDANCHORED</span></code>, <code class="constant pcre2-api rouge"><span class="no">PCRE2_AUTO_CALLOUT</span></code>, | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_CASELESS</span></code>, <code class="constant pcre2-api rouge"><span class="no">PCRE2_FIRSTLINE</span></code>, <code class="constant pcre2-api rouge"><span class="no">PCRE2_MATCH_INVALID_UTF</span></code>, | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_NO_START_OPTIMIZE</span></code>, <code class="constant pcre2-api rouge"><span class="no">PCRE2_NO_UTF_CHECK</span></code>, <code class="constant pcre2-api rouge"><span class="no">PCRE2_UTF</span></code>, and | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_USE_OFFSET_LIMIT</span></code>. The extra options <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_MATCH_LINE</span></code> and | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_MATCH_WORD</span></code> are also supported. Any other options cause an error.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_MATCH_INVALID_UTF</span></code></span></dt><dd>This option forces <code class="constant pcre2-api rouge"><span class="no">PCRE2_UTF</span></code> (see below) and also enables support for matching | |
| by <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> in subject strings that contain invalid UTF sequences. | |
| Note, however, that the 16-bit and 32-bit PCRE2 libraries process strings as | |
| sequences of <code class="type pcre2-api rouge"><span class="kt">uint16_t</span></code> or <code class="type pcre2-api rouge"><span class="kt">uint32_t</span></code> code points. They cannot find valid UTF | |
| sequences within an arbitrary string of bytes unless such sequences are | |
| suitably aligned. This facility is not supported for DFA matching. For details, | |
| see the | |
| <a href="./pcre2unicode.html"><code>pcre2unicode</code></a> | |
| documentation.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_MATCH_UNSET_BACKREF</span></code></span></dt><dd>If this option is set, a backreference to an unset capture group matches an | |
| empty string (by default this causes the current matching alternative to fail). | |
| A pattern such as <code class="regex rouge"><span class="pcre2-semantic">(\1)(a)</span></code> succeeds when this option is set (assuming it can | |
| find an <code class="subject rouge"><span class="pcre2-semantic">a</span></code> in the subject), whereas it fails by default, for Perl | |
| compatibility. Setting this option makes PCRE2 behave more like ECMAScript (JavaScript).</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_MULTILINE</span></code></span></dt><dd><p>By default, for the purposes of matching "start of line" and "end of line", | |
| PCRE2 treats the subject string as consisting of a single line of characters, | |
| even if it actually contains newlines. The "start of line" metacharacter (<code class="regex rouge"><span class="pcre2-semantic">^</span></code>) | |
| matches only at the start of the string, and the "end of line" metacharacter | |
| (<code class="regex rouge"><span class="pcre2-semantic">$</span></code>) matches only at the end of the string, or before a terminating newline | |
| (except when <code class="constant pcre2-api rouge"><span class="no">PCRE2_DOLLAR_ENDONLY</span></code> is set). Note, however, that unless | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_DOTALL</span></code> is set, the "any character" metacharacter (<code class="regex rouge"><span class="pcre2-semantic">.</span></code>) does not match at a | |
| newline. This behaviour (for <code class="regex rouge"><span class="pcre2-semantic">^</span></code>, <code class="regex rouge"><span class="pcre2-semantic">$</span></code>, and dot) is the same as Perl.</p><p>When <code class="constant pcre2-api rouge"><span class="no">PCRE2_MULTILINE</span></code> it is set, the "start of line" and "end of line" | |
| constructs match immediately following or immediately before internal newlines | |
| in the subject string, respectively, as well as at the very start and end. This | |
| is equivalent to Perl’s <code class="regex rouge"><span class="pcre2-semantic">/m</span></code> option, and it can be changed within a pattern by a | |
| <code class="regex rouge"><span class="pcre2-semantic">(?m)</span></code> option setting. Note that the "start of line" metacharacter does not match | |
| after a newline at the end of the subject, for compatibility with Perl. | |
| However, you can change this by setting the <code class="constant pcre2-api rouge"><span class="no">PCRE2_ALT_CIRCUMFLEX</span></code> option. If | |
| there are no newlines in a subject string, or no occurrences of <code class="regex rouge"><span class="pcre2-semantic">^</span></code> or <code class="regex rouge"><span class="pcre2-semantic">$</span></code> in a | |
| pattern, setting <code class="constant pcre2-api rouge"><span class="no">PCRE2_MULTILINE</span></code> has no effect.</p></dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_NEVER_BACKSLASH_C</span></code></span></dt><dd>This option locks out the use of <code class="regex rouge"><span class="pcre2-semantic">\C</span></code> in the pattern that is being compiled. | |
| This escape can cause unpredictable behaviour in UTF-8 or UTF-16 modes, because | |
| it may leave the current matching point in the middle of a multi-code-unit | |
| character. This option may be useful in applications that process patterns from | |
| external sources. Note that there is also a build-time option that permanently | |
| locks out the use of <code class="regex rouge"><span class="pcre2-semantic">\C</span></code>.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_NEVER_UCP</span></code></span></dt><dd>This option locks out the use of Unicode properties for handling <code class="regex rouge"><span class="pcre2-semantic">\B</span></code>, <code class="regex rouge"><span class="pcre2-semantic">\b</span></code>, <code class="regex rouge"><span class="pcre2-semantic">\D</span></code>, | |
| <code class="regex rouge"><span class="pcre2-semantic">\d</span></code>, <code class="regex rouge"><span class="pcre2-semantic">\S</span></code>, <code class="regex rouge"><span class="pcre2-semantic">\s</span></code>, <code class="regex rouge"><span class="pcre2-semantic">\W</span></code>, <code class="regex rouge"><span class="pcre2-semantic">\w</span></code>, and some of the POSIX character classes, as described | |
| for the <code class="constant pcre2-api rouge"><span class="no">PCRE2_UCP</span></code> option below. In particular, it prevents the creator of the | |
| pattern from enabling this facility by starting the pattern with <code class="regex rouge"><span class="pcre2-semantic">(*UCP)</span></code>. This | |
| option may be useful in applications that process patterns from external | |
| sources. The option combination <code class="constant pcre2-api rouge"><span class="no">PCRE2_UCP</span></code> and <code class="constant pcre2-api rouge"><span class="no">PCRE2_NEVER_UCP</span></code> causes an error.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_NEVER_UTF</span></code></span></dt><dd>This option locks out interpretation of the pattern as UTF-8, UTF-16, or | |
| UTF-32, depending on which library is in use. In particular, it prevents the | |
| creator of the pattern from switching to UTF interpretation by starting the | |
| pattern with <code class="regex rouge"><span class="pcre2-semantic">(*UTF)</span></code>. This option may be useful in applications that process | |
| patterns from external sources. The combination of <code class="constant pcre2-api rouge"><span class="no">PCRE2_UTF</span></code> and | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_NEVER_UTF</span></code> causes an error.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_NO_AUTO_CAPTURE</span></code></span></dt><dd>If this option is set, it disables the use of numbered capturing parentheses in | |
| the pattern. Any opening parenthesis that is not followed by <code class="regex rouge"><span class="pcre2-semantic">?</span></code> behaves as if it | |
| were followed by <code class="regex rouge"><span class="pcre2-semantic">?:</span></code> but named parentheses can still be used for capturing (and | |
| they acquire numbers in the usual way). This is the same as Perl’s <code class="regex rouge"><span class="pcre2-semantic">/n</span></code> option. | |
| Note that, when this option is set, references to capture groups | |
| (backreferences or recursion/subroutine calls) may only refer to named groups, | |
| though the reference can be by name or by number.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_NO_AUTO_POSSESS</span></code></span></dt><dd><p>If this (deprecated) option is set, it disables "auto-possessification", which | |
| is an optimization that, for example, turns <code class="regex rouge"><span class="pcre2-semantic">a+b</span></code> into | |
| <code class="regex rouge"><span class="pcre2-semantic">a++b</span></code> in order to avoid | |
| backtracks into <code class="regex rouge"><span class="pcre2-semantic">a+</span></code> that can never be successful. However, if callouts are in | |
| use, auto-possessification means that some callouts are never taken. You can | |
| set this option if you want the matching functions to do a full unoptimized | |
| search and run all the callouts, but it is mainly provided for testing | |
| purposes.</p><p>If a compile context is available, it is recommended to use | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_set_optimize()</span></code> with the <em>directive</em> <code class="constant pcre2-api rouge"><span class="no">PCRE2_AUTO_POSSESS_OFF</span></code> rather | |
| than the compile option <code class="constant pcre2-api rouge"><span class="no">PCRE2_NO_AUTO_POSSESS</span></code>. Note that <code class="constant pcre2-api rouge"><span class="no">PCRE2_NO_AUTO_POSSESS</span></code> | |
| takes precedence over the <code class="function pcre2-api rouge"><span class="nf">pcre2_set_optimize()</span></code> optimization directives | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_AUTO_POSSESS</span></code> and <code class="constant pcre2-api rouge"><span class="no">PCRE2_AUTO_POSSESS_OFF</span></code>.</p></dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_NO_DOTSTAR_ANCHOR</span></code></span></dt><dd>If this (deprecated) option is set, it disables an optimization that is applied | |
| when <code class="regex rouge"><span class="pcre2-semantic">.*</span></code> is the first significant item in a top-level branch of a pattern, and | |
| all the other branches also start with <code class="regex rouge"><span class="pcre2-semantic">.*</span></code> or with <code class="regex rouge"><span class="pcre2-semantic">\A</span></code>, <code class="regex rouge"><span class="pcre2-semantic">\G</span></code>, or <code class="regex rouge"><span class="pcre2-semantic">^</span></code>. The | |
| optimization is automatically disabled for <code class="regex rouge"><span class="pcre2-semantic">.*</span></code> if it is inside an atomic group | |
| or a capture group that is the subject of a backreference, or if the pattern | |
| contains <code class="regex rouge"><span class="pcre2-semantic">(*PRUNE)</span></code> or <code class="regex rouge"><span class="pcre2-semantic">(*SKIP)</span></code>. When the optimization is not disabled, such a | |
| pattern is automatically anchored if <code class="constant pcre2-api rouge"><span class="no">PCRE2_DOTALL</span></code> is set for all the <code class="regex rouge"><span class="pcre2-semantic">.*</span></code> items | |
| and <code class="constant pcre2-api rouge"><span class="no">PCRE2_MULTILINE</span></code> is not set for any <code class="regex rouge"><span class="pcre2-semantic">^</span></code> items. Otherwise, the fact that any | |
| match must start either at the start of the subject or following a newline is | |
| remembered. Like other optimizations, this can cause callouts to be skipped. | |
| (If a compile context is available, it is recommended to use | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_set_optimize()</span></code> with the <em>directive</em> <code class="constant pcre2-api rouge"><span class="no">PCRE2_DOTSTAR_ANCHOR_OFF</span></code> | |
| instead.)</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_NO_START_OPTIMIZE</span></code></span></dt><dd><p>This is an option whose main effect is at matching time. It does not change | |
| what <code class="function pcre2-api rouge"><span class="nf">pcre2_compile()</span></code> generates, but it does affect the output of the JIT | |
| compiler. Setting this option is equivalent to calling | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_set_optimize()</span></code> with the <em>directive</em> parameter set to | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_START_OPTIMIZE_OFF</span></code>.</p><p>There are a number of optimizations that may occur at the start of a match, in | |
| order to speed up the process. For example, if it is known that an unanchored | |
| match must start with a specific code unit value, the matching code searches | |
| the subject for that value, and fails immediately if it cannot find it, without | |
| actually running the main matching function. The start-up optimizations are | |
| in effect a pre-scan of the subject that takes place before the pattern is run.</p> | |
| <p>Disabling the start-up optimizations may cause performance to suffer. However, | |
| this may be desirable for patterns which contain callouts or items such as | |
| <code class="regex rouge"><span class="pcre2-semantic">(*COMMIT)</span></code> and <code class="regex rouge"><span class="pcre2-semantic">(*MARK)</span></code>. See the above description of <code class="constant pcre2-api rouge"><span class="no">PCRE2_START_OPTIMIZE_OFF</span></code> | |
| for further details.</p></dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_NO_UTF_CHECK</span></code></span></dt><dd><p>When <code class="constant pcre2-api rouge"><span class="no">PCRE2_UTF</span></code> is set, the validity of the pattern as a UTF string is | |
| automatically checked. There are discussions about the validity of | |
| UTF-8 strings, | |
| UTF-16 strings, | |
| and | |
| UTF-32 strings | |
| in the | |
| <a href="./pcre2unicode.html"><code>pcre2unicode</code></a> | |
| document. If an invalid UTF sequence is found, <code class="function pcre2-api rouge"><span class="nf">pcre2_compile()</span></code> returns a | |
| negative error code.</p><p>If you know that your pattern is a valid UTF string, and you want to skip this | |
| check for performance reasons, you can set the <code class="constant pcre2-api rouge"><span class="no">PCRE2_NO_UTF_CHECK</span></code> option. When | |
| it is set, the effect of passing an invalid UTF string as a pattern is | |
| undefined. It may cause your program to crash or loop.</p> | |
| <p>Note that this option can also be passed to <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> and | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_dfa_match()</span></code>, to suppress UTF validity checking of the subject | |
| string.</p> | |
| <p>Note also that setting <code class="constant pcre2-api rouge"><span class="no">PCRE2_NO_UTF_CHECK</span></code> at compile time does not disable the | |
| error that is given if an escape sequence for an invalid Unicode code point is | |
| encountered in the pattern. In particular, the so-called "surrogate" code | |
| points (<span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-22"><code class="character pcre2-api rouge"><span class="sc">0xd800</span></code><span class="character-card" id="pcre2-character-22" role="tooltip" aria-label="Surrogate code point (U+D800)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="Surrogate code point"></span><span class="character-codepoint" data-codepoint="U+D800"></span></span></span> to <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-23"><code class="character pcre2-api rouge"><span class="sc">0xdfff</span></code><span class="character-card" id="pcre2-character-23" role="tooltip" aria-label="Surrogate code point (U+DFFF)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="Surrogate code point"></span><span class="character-codepoint" data-codepoint="U+DFFF"></span></span></span>) are invalid. If you want to allow escape sequences | |
| such as <code class="regex rouge"><span class="pcre2-semantic">\x{d800}</span></code> you can set the <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_ALLOW_SURROGATE_ESCAPES</span></code> extra | |
| option, as described in the section <a href="#extra-compile-options">Extra compile options</a> | |
| below. | |
| However, this is possible only in UTF-8 and UTF-32 modes, because these values | |
| are not representable in UTF-16.</p></dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_UCP</span></code></span></dt><dd><p>This option has two effects. Firstly, it change the way PCRE2 processes <code class="regex rouge"><span class="pcre2-semantic">\B</span></code>, | |
| <code class="regex rouge"><span class="pcre2-semantic">\b</span></code>, <code class="regex rouge"><span class="pcre2-semantic">\D</span></code>, <code class="regex rouge"><span class="pcre2-semantic">\d</span></code>, <code class="regex rouge"><span class="pcre2-semantic">\S</span></code>, <code class="regex rouge"><span class="pcre2-semantic">\s</span></code>, <code class="regex rouge"><span class="pcre2-semantic">\W</span></code>, <code class="regex rouge"><span class="pcre2-semantic">\w</span></code>, and some of the POSIX character classes. By | |
| default, only ASCII characters are recognized, but if <code class="constant pcre2-api rouge"><span class="no">PCRE2_UCP</span></code> is set, Unicode | |
| properties are used to classify characters. There are some PCRE2_EXTRA | |
| options (see below) that add finer control to this behaviour. More details are | |
| given in the section | |
| <a href="./pcre2pattern.html#generic-character-types">Generic character types</a> | |
| in the | |
| <a href="./pcre2pattern.html"><code>pcre2pattern</code></a> | |
| page.</p><p>The second effect of <code class="constant pcre2-api rouge"><span class="no">PCRE2_UCP</span></code> is to force the use of Unicode properties for | |
| upper/lower casing operations, even when <code class="constant pcre2-api rouge"><span class="no">PCRE2_UTF</span></code> is not set. This makes it | |
| possible to process strings in the 16-bit UCS-2 code. This option is available | |
| only if PCRE2 has been compiled with Unicode support (which is the default).</p> | |
| <p>The <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_CASELESS_RESTRICT</span></code> option (see above) restricts caseless | |
| matching such that ASCII characters match only ASCII characters and non-ASCII | |
| characters match only non-ASCII characters. The <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_TURKISH_CASING</span></code> | |
| option (see above) alters the matching of the 'i' characters to follow their | |
| behaviour in Turkish and Azeri languages. For further details on | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_CASELESS_RESTRICT</span></code> and <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_TURKISH_CASING</span></code>, see the | |
| <a href="./pcre2unicode.html"><code>pcre2unicode</code></a> | |
| page.</p></dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_UNGREEDY</span></code></span></dt><dd>This option inverts the "greediness" of the quantifiers so that they are not | |
| greedy by default, but become greedy if followed by <code class="regex rouge"><span class="pcre2-semantic">?</span></code>. It is not compatible | |
| with Perl. It can also be set by a <code class="regex rouge"><span class="pcre2-semantic">(?U)</span></code> option setting within the pattern.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_USE_OFFSET_LIMIT</span></code></span></dt><dd>This option must be set for <code class="function pcre2-api rouge"><span class="nf">pcre2_compile()</span></code> if | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_set_offset_limit()</span></code> is going to be used to set a non-default offset | |
| limit in a match context for matches that use this pattern. An error is | |
| generated if an offset limit is set without this option. For more details, see | |
| the description of <code class="function pcre2-api rouge"><span class="nf">pcre2_set_offset_limit()</span></code> in the | |
| section | |
| that describes match contexts. See also the <code class="constant pcre2-api rouge"><span class="no">PCRE2_FIRSTLINE</span></code> | |
| option above.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_UTF</span></code></span></dt><dd>This option causes PCRE2 to regard both the pattern and the subject strings | |
| that are subsequently processed as strings of UTF characters instead of | |
| single-code-unit strings. It is available when PCRE2 is built to include | |
| Unicode support (which is the default). If Unicode support is not available, | |
| the use of this option provokes an error. Details of how <code class="constant pcre2-api rouge"><span class="no">PCRE2_UTF</span></code> changes the | |
| behaviour of PCRE2 are given in the | |
| <a href="./pcre2unicode.html"><code>pcre2unicode</code></a> | |
| page. In particular, note that it changes the way <code class="constant pcre2-api rouge"><span class="no">PCRE2_CASELESS</span></code> works.</dd></div></dl></section> | |
| <section class="doc-section level-2"><h3 id="extra-compile-options">Extra compile options</h3><p>The option bits that can be set in a compile context by calling the | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_set_compile_extra_options()</span></code> function are as follows:</p> | |
| <dl class="options spaced" style="--tab-width: 14"><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_ALLOW_LOOKAROUND_BSK</span></code></span></dt><dd>Since release 10.38 PCRE2 has forbidden the use of <code class="regex rouge"><span class="pcre2-semantic">\K</span></code> within lookaround | |
| assertions, following Perl’s lead. This option is provided to re-enable the | |
| previous behaviour (act in positive lookarounds, ignore in negative ones) in | |
| case anybody is relying on it.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_ALLOW_SURROGATE_ESCAPES</span></code></span></dt><dd><p>This option applies when compiling a pattern in UTF-8 or UTF-32 mode. It is | |
| forbidden in UTF-16 mode, and ignored in non-UTF modes. Unicode "surrogate" | |
| code points in the range <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-24"><code class="character pcre2-api rouge"><span class="sc">0xd800</span></code><span class="character-card" id="pcre2-character-24" role="tooltip" aria-label="Surrogate code point (U+D800)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="Surrogate code point"></span><span class="character-codepoint" data-codepoint="U+D800"></span></span></span> to <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-25"><code class="character pcre2-api rouge"><span class="sc">0xdfff</span></code><span class="character-card" id="pcre2-character-25" role="tooltip" aria-label="Surrogate code point (U+DFFF)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="Surrogate code point"></span><span class="character-codepoint" data-codepoint="U+DFFF"></span></span></span> are used in pairs in UTF-16 to encode | |
| code points with values in the range <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-26"><code class="character pcre2-api rouge"><span class="sc">0x10000</span></code><span class="character-card" id="pcre2-character-26" role="tooltip" aria-label="LINEAR B SYLLABLE B008 A (U+10000)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character="𐀀"></span><span class="character-name" data-character-name="LINEAR B SYLLABLE B008 A"></span><span class="character-codepoint" data-codepoint="U+10000"></span></span></span> to <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-27"><code class="character pcre2-api rouge"><span class="sc">0x10ffff</span></code><span class="character-card" id="pcre2-character-27" role="tooltip" aria-label="<noncharacter-10FFFF> (U+10FFFF)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="<noncharacter-10FFFF>"></span><span class="character-codepoint" data-codepoint="U+10FFFF"></span></span></span>. The surrogates cannot | |
| therefore be represented in UTF-16. They can be represented in UTF-8 and | |
| UTF-32, but are defined as invalid code points, and cause errors if encountered | |
| in a UTF-8 or UTF-32 string that is being checked for validity by PCRE2.</p><p>These values also cause errors if encountered in escape sequences such as | |
| <code class="regex rouge"><span class="pcre2-semantic">\x{d912}</span></code> within a pattern. However, it seems that some applications, when | |
| using PCRE2 to check for unwanted characters in UTF-8 strings, explicitly test | |
| for the surrogates using escape sequences. The <code class="constant pcre2-api rouge"><span class="no">PCRE2_NO_UTF_CHECK</span></code> option does | |
| not disable the error that occurs, because it applies only to the testing of | |
| input strings for UTF validity.</p> | |
| <p>If the extra option <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_ALLOW_SURROGATE_ESCAPES</span></code> is set, surrogate code | |
| point values in UTF-8 and UTF-32 patterns no longer provoke errors and are | |
| incorporated in the compiled pattern. However, they can only match subject | |
| characters if the matching function is called with <code class="constant pcre2-api rouge"><span class="no">PCRE2_NO_UTF_CHECK</span></code> set.</p></dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_ALT_BSUX</span></code></span></dt><dd>The original option <code class="constant pcre2-api rouge"><span class="no">PCRE2_ALT_BSUX</span></code> causes PCRE2 to process <code class="regex rouge"><span class="pcre2-semantic">\U</span></code>, <code class="regex rouge"><span class="pcre2-semantic">\u</span></code>, and <code class="regex rouge"><span class="pcre2-semantic">\x</span></code> in | |
| the way that ECMAScript (JavaScript) does. Additional functionality was | |
| defined by ECMAScript 6; setting <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_ALT_BSUX</span></code> has the effect of | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_ALT_BSUX</span></code>, but in addition it recognizes <code class="regex rouge"><span class="pcre2-semantic">\u{hhh..}</span></code> as a hexadecimal | |
| character code, where hhh.. is any number of hexadecimal digits.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_ASCII_BSD</span></code></span></dt><dd>This option forces <code class="regex rouge"><span class="pcre2-semantic">\d</span></code> to match only ASCII digits, even when <code class="constant pcre2-api rouge"><span class="no">PCRE2_UCP</span></code> is set. | |
| It can be changed within a pattern by means of the <code class="regex rouge"><span class="pcre2-semantic">(?aD)</span></code> option setting.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_ASCII_BSS</span></code></span></dt><dd>This option forces <code class="regex rouge"><span class="pcre2-semantic">\s</span></code> to match only ASCII space characters, even when | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_UCP</span></code> is set. It can be changed within a pattern by means of the <code class="regex rouge"><span class="pcre2-semantic">(?aS)</span></code> | |
| option setting.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_ASCII_BSW</span></code></span></dt><dd>This option forces <code class="regex rouge"><span class="pcre2-semantic">\w</span></code> to match only ASCII word characters, even when <code class="constant pcre2-api rouge"><span class="no">PCRE2_UCP</span></code> | |
| is set. It can be changed within a pattern by means of the <code class="regex rouge"><span class="pcre2-semantic">(?aW)</span></code> option | |
| setting.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_ASCII_DIGIT</span></code></span></dt><dd>This option forces the POSIX character classes <code class="regex rouge"><span class="pcre2-semantic">[:digit:]</span></code> and <code class="regex rouge"><span class="pcre2-semantic">[:xdigit:]</span></code> to | |
| match only ASCII digits, even when <code class="constant pcre2-api rouge"><span class="no">PCRE2_UCP</span></code> is set. It can be changed within | |
| a pattern by means of the <code class="regex rouge"><span class="pcre2-semantic">(?aT)</span></code> option setting.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_ASCII_POSIX</span></code></span></dt><dd>This option forces all the POSIX character classes, including <code class="regex rouge"><span class="pcre2-semantic">[:digit:]</span></code> and | |
| <code class="regex rouge"><span class="pcre2-semantic">[:xdigit:]</span></code>, to match only ASCII characters, even when <code class="constant pcre2-api rouge"><span class="no">PCRE2_UCP</span></code> is set. It can | |
| be changed within a pattern by means of the <code class="regex rouge"><span class="pcre2-semantic">(?aP)</span></code> option setting, but note that | |
| this also sets <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_ASCII_DIGIT</span></code> in order to ensure that <code class="regex rouge"><span class="pcre2-semantic">(?-aP)</span></code> unsets | |
| all ASCII restrictions for POSIX classes.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_BAD_ESCAPE_IS_LITERAL</span></code></span></dt><dd><p>This is a dangerous option. Use with care. By default, an unrecognized escape | |
| such as <code class="regex rouge"><span class="pcre2-semantic">\j</span></code> or a malformed one such as <code class="regex rouge"><span class="pcre2-semantic">\x{2z}</span></code> causes a compile-time error when | |
| detected by <code class="function pcre2-api rouge"><span class="nf">pcre2_compile()</span></code>. Perl is somewhat inconsistent in handling | |
| such items: for example, <code class="regex rouge"><span class="pcre2-semantic">\j</span></code> is treated as a literal <code>j</code>, and non-hexadecimal | |
| digits in <code class="regex rouge"><span class="pcre2-semantic">\x{}</span></code> are just ignored, though warnings are given in both cases if | |
| Perl’s warning switch is enabled. However, a malformed octal number after <code class="regex rouge"><span class="pcre2-semantic">\o{</span></code> | |
| always causes an error in Perl.</p><p>If the <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_BAD_ESCAPE_IS_LITERAL</span></code> extra option is passed to | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_compile()</span></code>, all unrecognized or malformed escape sequences are | |
| treated as single-character escapes. For example, <code class="regex rouge"><span class="pcre2-semantic">\j</span></code> is a literal <code>j</code> and | |
| <code class="regex rouge"><span class="pcre2-semantic">\x{2z}</span></code> is treated as the literal string <code>x{2z}</code>. Setting this option means | |
| that typos in patterns may go undetected and have unexpected results. Also note | |
| that a sequence such as <code class="regex rouge"><span class="pcre2-semantic">[\N{]</span></code> is interpreted as a malformed attempt at | |
| <code class="regex rouge"><span class="pcre2-semantic">[\N{...}]</span></code> and so is treated as <code class="regex rouge"><span class="pcre2-semantic">[N{]</span></code> whereas <code class="regex rouge"><span class="pcre2-semantic">[\N]</span></code> gives an error because an | |
| unqualified <code class="regex rouge"><span class="pcre2-semantic">\N</span></code> is a valid escape sequence but is not supported in a character | |
| class. To reiterate: this is a dangerous option. Use with great care.</p></dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_CASELESS_RESTRICT</span></code></span></dt><dd>When either <code class="constant pcre2-api rouge"><span class="no">PCRE2_UCP</span></code> or <code class="constant pcre2-api rouge"><span class="no">PCRE2_UTF</span></code> is set, caseless matching follows Unicode | |
| rules, which allow for more than two cases per character. There are two | |
| case-equivalent character sets that contain both ASCII and non-ASCII | |
| characters. The ASCII letter S is case-equivalent to <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-28"><code class="character pcre2-api rouge"><span class="sc">U+017f</span></code><span class="character-card" id="pcre2-character-28" role="tooltip" aria-label="LATIN SMALL LETTER LONG S (U+017F)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character="ſ"></span><span class="character-name" data-character-name="LATIN SMALL LETTER LONG S"></span><span class="character-codepoint" data-codepoint="U+017F"></span></span></span> (long S) and the | |
| ASCII letter K is case-equivalent to <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-29"><code class="character pcre2-api rouge"><span class="sc">U+212a</span></code><span class="character-card" id="pcre2-character-29" role="tooltip" aria-label="KELVIN SIGN (U+212A)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character="K"></span><span class="character-name" data-character-name="KELVIN SIGN"></span><span class="character-codepoint" data-codepoint="U+212A"></span></span></span> (Kelvin sign). This option disables | |
| recognition of case-equivalences that cross the ASCII/non-ASCII boundary. In a | |
| caseless match, both characters must either be ASCII or non-ASCII. The option | |
| can be changed within a pattern by the <code class="regex rouge"><span class="pcre2-semantic">(*CASELESS_RESTRICT)</span></code> or <code class="regex rouge"><span class="pcre2-semantic">(?r)</span></code> option | |
| settings.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_ESCAPED_CR_IS_LF</span></code></span></dt><dd>There are some legacy applications where the escape sequence <code class="regex rouge"><span class="pcre2-semantic">\r</span></code> in a pattern | |
| is expected to match a newline. If this option is set, <code class="regex rouge"><span class="pcre2-semantic">\r</span></code> in a pattern is | |
| converted to <code class="regex rouge"><span class="pcre2-semantic">\n</span></code> so that it matches a LF (linefeed) instead of a CR (carriage | |
| return) character. The option does not affect a literal CR in the pattern, nor | |
| does it affect CR specified as an explicit code point such as <code class="regex rouge"><span class="pcre2-semantic">\x{0D}</span></code>.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_MATCH_LINE</span></code></span></dt><dd>This option is provided for use by the <code>-x</code> option of <code>pcre2grep</code>. It | |
| causes the pattern only to match complete lines. This is achieved by | |
| automatically inserting the code for <code class="regex rouge"><span class="pcre2-semantic">^(?:</span></code> at the start of the compiled | |
| pattern and <code class="regex rouge"><span class="pcre2-semantic">)$</span></code> at the end. Thus, when <code class="constant pcre2-api rouge"><span class="no">PCRE2_MULTILINE</span></code> is set, the matched | |
| line may be in the middle of the subject string. This option can be used with | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_LITERAL</span></code>.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_MATCH_WORD</span></code></span></dt><dd>This option is provided for use by the <code>-w</code> option of <code>pcre2grep</code>. It | |
| causes the pattern only to match strings that have a word boundary at the start | |
| and the end. This is achieved by automatically inserting the code for <code class="regex rouge"><span class="pcre2-semantic">\b(?:</span></code> | |
| at the start of the compiled pattern and <code class="regex rouge"><span class="pcre2-semantic">)\b</span></code> at the end. The option may be | |
| used with <code class="constant pcre2-api rouge"><span class="no">PCRE2_LITERAL</span></code>. However, it is ignored if <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_MATCH_LINE</span></code> is | |
| also set.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_NO_BS0</span></code></span></dt><dd>If this option is set (note that its final character is the digit zero) it locks | |
| out the use of the sequence <code class="regex rouge"><span class="pcre2-semantic">\0</span></code> unless at least one more octal digit follows.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_PYTHON_OCTAL</span></code></span></dt><dd>If this option is set, PCRE2 follows Python’s rules for interpreting octal | |
| escape sequences. The rules for handling sequences such as <code class="regex rouge"><span class="pcre2-semantic">\14</span></code>, which could | |
| be an octal number or a back reference are different. Details are given in the | |
| <a href="./pcre2pattern.html"><code>pcre2pattern</code></a> | |
| documentation.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_NEVER_CALLOUT</span></code></span></dt><dd>If this option is set, PCRE2 treats callouts in the pattern as a syntax error, | |
| returning <code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_CALLOUT_CALLER_DISABLED</span></code>. This is useful if the application | |
| knows that a callout will not be provided to <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code>, so that | |
| callouts in the pattern are not silently ignored.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_TURKISH_CASING</span></code></span></dt><dd>This option alters case-equivalence of the 'i' letters to follow the | |
| alphabet used by Turkish and Azeri languages. The option can be changed within | |
| a pattern by the <code class="regex rouge"><span class="pcre2-semantic">(*TURKISH_CASING)</span></code> start-of-pattern setting. Either the UTF or | |
| UCP options must be set. In the 8-bit library, UTF must be set. This option | |
| cannot be combined with <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_CASELESS_RESTRICT</span></code>.</dd></div></dl></section></section> | |
| <section class="doc-section level-1"><h2 id="_just_in_time_jit_compilation">Just-in-time (JIT) compilation</h2><div class="listing-block prototype"><pre class="rouge highlight"><code data-lang="c"><span class="kt">int</span> <span class="nf">pcre2_jit_compile</span><span class="p">(</span><span class="kt">pcre2_code</span> <span class="p">*</span><span class="nv">code</span><span class="p">,</span> <span class="kt">uint32_t</span> <span class="nv">options</span><span class="p">);</span> | |
| <span class="kt">int</span> <span class="nf">pcre2_jit_match</span><span class="p">(</span><span class="kt">const</span> <span class="kt">pcre2_code</span> <span class="p">*</span><span class="nv">code</span><span class="p">,</span> <span class="kt">PCRE2_SPTR</span> <span class="nv">subject</span><span class="p">,</span> | |
| <span class="kt">PCRE2_SIZE</span> <span class="nv">length</span><span class="p">,</span> <span class="kt">PCRE2_SIZE</span> <span class="nv">start_offset</span><span class="p">,</span> | |
| <span class="kt">uint32_t</span> <span class="nv">options</span><span class="p">,</span> <span class="kt">pcre2_match_data</span> <span class="p">*</span><span class="nv">match_data</span><span class="p">,</span> | |
| <span class="kt">pcre2_match_context</span> <span class="p">*</span><span class="nv">mcontext</span><span class="p">);</span> | |
| <span class="kt">void</span> <span class="nf">pcre2_jit_free_unused_memory</span><span class="p">(</span><span class="kt">pcre2_general_context</span> <span class="p">*</span><span class="nv">gcontext</span><span class="p">);</span> | |
| <span class="kt">pcre2_jit_stack</span> <span class="p">*</span><span class="nf">pcre2_jit_stack_create</span><span class="p">(</span> | |
| <span class="kt">size_t</span> <span class="nv">startsize</span><span class="p">,</span> <span class="kt">size_t</span> <span class="nv">maxsize</span><span class="p">,</span> | |
| <span class="kt">pcre2_general_context</span> <span class="p">*</span><span class="nv">gcontext</span><span class="p">);</span> | |
| <span class="kt">void</span> <span class="nf">pcre2_jit_stack_assign</span><span class="p">(</span><span class="kt">pcre2_match_context</span> <span class="p">*</span><span class="nv">mcontext</span><span class="p">,</span> | |
| <span class="kt">pcre2_jit_callback</span> <span class="nv">callback</span><span class="p">,</span> | |
| <span class="kt">void</span> <span class="p">*</span><span class="nv">callback_data</span><span class="p">);</span> | |
| <span class="kt">void</span> <span class="nf">pcre2_jit_stack_free</span><span class="p">(</span><span class="kt">pcre2_jit_stack</span> <span class="p">*</span><span class="nv">jit_stack</span><span class="p">);</span></code></pre></div> | |
| <p>These functions provide support for JIT compilation, which, if the just-in-time | |
| compiler is available, further processes a compiled pattern into machine code | |
| that executes much faster than the <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> interpretive matching | |
| function. Full details are given in the | |
| <a href="./pcre2jit.html"><code>pcre2jit</code></a> | |
| documentation.</p> | |
| <p>JIT compilation is a heavyweight optimization. It can take some time for | |
| patterns to be analyzed, and for one-off matches and simple patterns the | |
| benefit of faster execution might be offset by a much slower compilation time. | |
| Most (but not all) patterns can be optimized by the JIT compiler.</p></section> | |
| <section class="doc-section level-1"><h2 id="locale-support">Locale support</h2><div class="listing-block prototype"><pre class="rouge highlight"><code data-lang="c"><span class="kt">const</span> <span class="kt">uint8_t</span> <span class="p">*</span><span class="nf">pcre2_maketables</span><span class="p">(</span><span class="kt">pcre2_general_context</span> <span class="p">*</span><span class="nv">gcontext</span><span class="p">);</span> | |
| <span class="kt">void</span> <span class="nf">pcre2_maketables_free</span><span class="p">(</span><span class="kt">pcre2_general_context</span> <span class="p">*</span><span class="nv">gcontext</span><span class="p">,</span> | |
| <span class="kt">const</span> <span class="kt">uint8_t</span> <span class="p">*</span><span class="nv">tables</span><span class="p">);</span></code></pre></div> | |
| <p>PCRE2 handles caseless matching, and determines whether characters are letters, | |
| digits, or whatever, by reference to a set of tables, indexed by character code | |
| point. However, this applies only to characters whose code points are less than | |
| 256. By default, higher-valued code points never match escapes such as <code class="regex rouge"><span class="pcre2-semantic">\w</span></code> or | |
| <code class="regex rouge"><span class="pcre2-semantic">\d</span></code>.</p> | |
| <p>When PCRE2 is built with Unicode support (the default), certain Unicode | |
| character properties can be tested with <code class="regex rouge"><span class="pcre2-semantic">\p</span></code> and <code class="regex rouge"><span class="pcre2-semantic">\P</span></code>, or, alternatively, the | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_UCP</span></code> option can be set when a pattern is compiled; this causes <code class="regex rouge"><span class="pcre2-semantic">\w</span></code> and | |
| friends to use Unicode property support instead of the built-in tables. | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_UCP</span></code> also causes upper/lower casing operations on characters with code | |
| points greater than 127 to use Unicode properties. These effects apply even | |
| when <code class="constant pcre2-api rouge"><span class="no">PCRE2_UTF</span></code> is not set. There are, however, some PCRE2_EXTRA options (see | |
| above) that can be used to modify or suppress them.</p> | |
| <p>The use of locales with Unicode is discouraged. If you are handling characters | |
| with code points greater than 127, you should either use Unicode support, or | |
| use locales, but not try to mix the two.</p> | |
| <p>PCRE2 contains a built-in set of character tables that are used by default. | |
| These are sufficient for many applications. Normally, the internal tables | |
| recognize only ASCII characters. However, when PCRE2 is built, it is possible | |
| to cause the internal tables to be rebuilt in the default "C" locale of the | |
| local system, which may cause them to be different.</p> | |
| <p>The built-in tables can be overridden by tables supplied by the application | |
| that calls PCRE2. These may be created in a different locale from the default. | |
| As more and more applications change to using Unicode, the need for this locale | |
| support is expected to die away.</p> | |
| <p>External tables are built by calling the <code class="function pcre2-api rouge"><span class="nf">pcre2_maketables()</span></code> function, in | |
| the relevant locale. The only argument to this function is a general context, | |
| which can be used to pass a custom memory allocator. If the argument is <code class="constant pcre2-api rouge"><span class="kc">NULL</span></code>, | |
| the system <code class="c rouge" data-lang="c"><span class="nf">malloc</span><span class="p">()</span></code> is used. The result can be passed to | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_compile()</span></code> as often as necessary, by creating a compile context and | |
| calling <code class="function pcre2-api rouge"><span class="nf">pcre2_set_character_tables()</span></code> to set the tables pointer therein.</p> | |
| <p>For example, to build and use tables that are appropriate for the French locale | |
| (where accented characters with values greater than 127 are treated as | |
| letters), the following code could be used:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="c"><span class="nf">setlocale</span><span class="p">(</span><span class="no">LC_CTYPE</span><span class="p">,</span> <span class="s">"fr_FR"</span><span class="p">);</span> | |
| <span class="nv">tables</span> <span class="o">=</span> <span class="nf">pcre2_maketables</span><span class="p">(</span><span class="kc">NULL</span><span class="p">);</span> | |
| <span class="nv">ccontext</span> <span class="o">=</span> <span class="nf">pcre2_compile_context_create</span><span class="p">(</span><span class="kc">NULL</span><span class="p">);</span> | |
| <span class="nf">pcre2_set_character_tables</span><span class="p">(</span><span class="nv">ccontext</span><span class="p">,</span> <span class="nv">tables</span><span class="p">);</span> | |
| <span class="nv">re</span> <span class="o">=</span> <span class="nf">pcre2_compile</span><span class="p">(...,</span> <span class="nv">ccontext</span><span class="p">);</span></code></pre></div> | |
| <p>The locale name "fr_FR" is used on Linux and other Unix-like systems; if you | |
| are using Windows, the name for the French locale is "french".</p> | |
| <p>The pointer that is passed (via the compile context) to <code class="function pcre2-api rouge"><span class="nf">pcre2_compile()</span></code> | |
| is saved with the compiled pattern, and the same tables are used by the | |
| matching functions. Thus, for any single pattern, compilation and matching both | |
| happen in the same locale, but different patterns can be processed in different | |
| locales.</p> | |
| <p>It is the caller’s responsibility to ensure that the memory containing the | |
| tables remains available while they are still in use. When they are no longer | |
| needed, you can discard them using <code class="function pcre2-api rouge"><span class="nf">pcre2_maketables_free()</span></code>, which should | |
| pass as its first parameter the same global context that was used to create the | |
| tables.</p> | |
| <section class="doc-section level-2"><h3 id="_saving_locale_tables">Saving locale tables</h3><p>The tables described above are just a sequence of binary bytes, which makes | |
| them independent of hardware characteristics such as endianness or whether the | |
| processor is 32-bit or 64-bit. A copy of the result of <code class="function pcre2-api rouge"><span class="nf">pcre2_maketables()</span></code> | |
| can therefore be saved in a file or elsewhere and re-used later, even in a | |
| different program or on another computer. The size of the tables (number of | |
| bytes) must be obtained by calling <code class="function pcre2-api rouge"><span class="nf">pcre2_config()</span></code> with the | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_CONFIG_TABLES_LENGTH</span></code> option because <code class="function pcre2-api rouge"><span class="nf">pcre2_maketables()</span></code> does not | |
| return this value. Note that the <code>pcre2_dftables</code> program, which is part of | |
| the PCRE2 build system, can be used stand-alone to create a file that contains | |
| a set of binary tables. See the | |
| <code>pcre2build</code> | |
| documentation for details.</p></section></section> | |
| <section class="doc-section level-1"><h2 id="information-about-compiled-pattern">Information about a compiled pattern</h2><div class="listing-block prototype"><pre class="rouge highlight"><code data-lang="c"><span class="kt">int</span> <span class="nf">pcre2_pattern_info</span><span class="p">(</span><span class="kt">const</span> <span class="kt">pcre2_code</span> <span class="p">*</span><span class="nv">code</span><span class="p">,</span> <span class="kt">uint32_t</span> <span class="nv">what</span><span class="p">,</span> | |
| <span class="kt">void</span> <span class="p">*</span><span class="nv">where</span><span class="p">);</span></code></pre></div> | |
| <p>The <code class="function pcre2-api rouge"><span class="nf">pcre2_pattern_info()</span></code> function returns general information about a | |
| compiled pattern. For information about callouts, see the | |
| section <a href="#information-about-pattern-callouts">Information about a pattern’s callouts</a>. | |
| The first argument for <code class="function pcre2-api rouge"><span class="nf">pcre2_pattern_info()</span></code> is a pointer to the compiled | |
| pattern. The second argument specifies which piece of information is required, | |
| and the third argument is a pointer to a variable to receive the data. If the | |
| third argument is <code class="constant pcre2-api rouge"><span class="kc">NULL</span></code>, the first argument is ignored, and the function returns | |
| the size in bytes of the variable that is required for the information | |
| requested. Otherwise, the yield of the function is zero for success, or one of | |
| the following negative numbers:</p> | |
| <dl class="errors compact" style="--tab-width: 12"><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_NULL</span></code></span></dt><dd>the argument <code class="parameter pcre2-api rouge"><span class="nv">code</span></code> was <code class="constant pcre2-api rouge"><span class="kc">NULL</span></code></dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_BADMAGIC</span></code></span></dt><dd>the "magic number" was not found</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_BADOPTION</span></code></span></dt><dd>the value of <code class="parameter pcre2-api rouge"><span class="nv">what</span></code> was invalid</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_UNSET</span></code></span></dt><dd>the requested field is not set</dd></div></dl> | |
| <p>The "magic number" is placed at the start of each compiled pattern as a simple | |
| check against passing an arbitrary memory pointer. Here is a typical call of | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_pattern_info()</span></code>, to obtain the length of the compiled pattern:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="c"><span class="kt">int</span> <span class="nv">rc</span><span class="p">;</span> | |
| <span class="kt">size_t</span> <span class="nv">length</span><span class="p">;</span> | |
| <span class="nv">rc</span> <span class="o">=</span> <span class="nf">pcre2_pattern_info</span><span class="p">(</span> | |
| <span class="nv">re</span><span class="p">,</span> <span class="cm">/* result of pcre2_compile() */</span> | |
| <span class="no">PCRE2_INFO_SIZE</span><span class="p">,</span> <span class="cm">/* what is required */</span> | |
| <span class="p">&</span><span class="nv">length</span><span class="p">);</span> <span class="cm">/* where to put the data */</span></code></pre></div> | |
| <p>The possible values for the second argument are defined in <code>pcre2.h</code>, and | |
| are as follows:</p> | |
| <dl class="values spaced" style="--tab-width: 14"><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_INFO_ALLOPTIONS</span></code><br><code class="constant pcre2-api rouge"><span class="no">PCRE2_INFO_ARGOPTIONS</span></code><br><code class="constant pcre2-api rouge"><span class="no">PCRE2_INFO_EXTRAOPTIONS</span></code></span></dt><dd><p>Return copies of the pattern’s options. The third argument should point to a | |
| <code class="type pcre2-api rouge"><span class="kt">uint32_t</span></code> variable. <code class="constant pcre2-api rouge"><span class="no">PCRE2_INFO_ARGOPTIONS</span></code> returns exactly the options that | |
| were passed to <code class="function pcre2-api rouge"><span class="nf">pcre2_compile()</span></code>, whereas <code class="constant pcre2-api rouge"><span class="no">PCRE2_INFO_ALLOPTIONS</span></code> returns | |
| the compile options as modified by any top-level <code class="regex rouge"><span class="pcre2-semantic">(*<em>XXX</em>)</span></code> option settings such as | |
| <code class="regex rouge"><span class="pcre2-semantic">(*UTF)</span></code> at the start of the pattern itself. <code class="constant pcre2-api rouge"><span class="no">PCRE2_INFO_EXTRAOPTIONS</span></code> returns the | |
| extra options that were set in the compile context by calling the | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_set_compile_extra_options()</span></code> function.</p> | |
| <p>For example, if the pattern <code class="regex rouge"><span class="pcre2-semantic">(*UTF)abc</span></code> is compiled with the <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTENDED</span></code> | |
| option, the result for <code class="constant pcre2-api rouge"><span class="no">PCRE2_INFO_ALLOPTIONS</span></code> is <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTENDED</span></code> and <code class="constant pcre2-api rouge"><span class="no">PCRE2_UTF</span></code>. | |
| Option settings such as <code class="regex rouge"><span class="pcre2-semantic">(?i)</span></code> that can change within a pattern do not affect the | |
| result of <code class="constant pcre2-api rouge"><span class="no">PCRE2_INFO_ALLOPTIONS</span></code>, even if they appear right at the start of the | |
| pattern. (This was different in some earlier releases.)</p> | |
| <p>A pattern compiled without <code class="constant pcre2-api rouge"><span class="no">PCRE2_ANCHORED</span></code> is automatically anchored by PCRE2 if | |
| the first significant item in every top-level branch is one of the following:</p> | |
| <div class="open-block"><div class="content"><dl class="compact" style="--tab-width: 4"><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">^</span></code> </span></dt><dd>unless <code class="constant pcre2-api rouge"><span class="no">PCRE2_MULTILINE</span></code> is set</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">\A</span></code> </span></dt><dd>always</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">\G</span></code> </span></dt><dd>always</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">.*</span></code> </span></dt><dd>sometimes — see below</dd></div></dl></div></div> | |
| <p>When <code class="regex rouge"><span class="pcre2-semantic">.*</span></code> is the first significant item, anchoring is possible only when all the | |
| following are true:</p> | |
| <ol class="loweralpha compact" type="a"><li><code class="regex rouge"><span class="pcre2-semantic">.*</span></code> is not in an atomic group</li><li><code class="regex rouge"><span class="pcre2-semantic">.*</span></code> is not in a capture group that is the subject of a backreference</li><li><code class="constant pcre2-api rouge"><span class="no">PCRE2_DOTALL</span></code> is in force for <code class="regex rouge"><span class="pcre2-semantic">.*</span></code></li><li>Neither <code class="regex rouge"><span class="pcre2-semantic">(*PRUNE)</span></code> nor <code class="regex rouge"><span class="pcre2-semantic">(*SKIP)</span></code> appears in the pattern</li><li><code class="constant pcre2-api rouge"><span class="no">PCRE2_NO_DOTSTAR_ANCHOR</span></code> is not set</li><li>Dotstar anchoring has not been disabled with <code class="constant pcre2-api rouge"><span class="no">PCRE2_DOTSTAR_ANCHOR_OFF</span></code></li></ol> | |
| <p>For patterns that are auto-anchored, the <code class="constant pcre2-api rouge"><span class="no">PCRE2_ANCHORED</span></code> bit is set in the | |
| options returned for <code class="constant pcre2-api rouge"><span class="no">PCRE2_INFO_ALLOPTIONS</span></code>.</p></dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_INFO_BACKREFMAX</span></code></span></dt><dd>Return the number of the highest backreference in the pattern. The third | |
| argument should point to a <code class="type pcre2-api rouge"><span class="kt">uint32_t</span></code> variable. Named capture groups | |
| acquire numbers as well as names, and these count towards the highest | |
| backreference. Backreferences such as <code class="regex rouge"><span class="pcre2-semantic">\4</span></code> or <code class="regex rouge"><span class="pcre2-semantic">\g{12}</span></code> match the captured | |
| characters of the given group, but in addition, the check that a capture | |
| group is set in a conditional group such as <code class="regex rouge"><span class="pcre2-semantic">(?(3)a|b)</span></code> is also a backreference. | |
| Zero is returned if there are no backreferences.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_INFO_BSR</span></code></span></dt><dd>The output is a <code class="type pcre2-api rouge"><span class="kt">uint32_t</span></code> integer whose value indicates what character sequences | |
| the <code class="regex rouge"><span class="pcre2-semantic">\R</span></code> escape sequence matches. A value of <code class="constant pcre2-api rouge"><span class="no">PCRE2_BSR_UNICODE</span></code> means that <code class="regex rouge"><span class="pcre2-semantic">\R</span></code> | |
| matches any Unicode line ending sequence; a value of <code class="constant pcre2-api rouge"><span class="no">PCRE2_BSR_ANYCRLF</span></code> means | |
| that <code class="regex rouge"><span class="pcre2-semantic">\R</span></code> matches only CR, LF, or CRLF.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_INFO_CAPTURECOUNT</span></code></span></dt><dd>Return the highest capture group number in the pattern. In patterns where <code class="regex rouge"><span class="pcre2-semantic">(?|</span></code> | |
| is not used, this is also the total number of capture groups. The third | |
| argument should point to a <code class="type pcre2-api rouge"><span class="kt">uint32_t</span></code> variable.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_INFO_DEPTHLIMIT</span></code></span></dt><dd>If the pattern set a backtracking depth limit by including an item of the form | |
| <code class="regex rouge"><span class="pcre2-semantic">(*LIMIT_DEPTH=<em>nnnn</em>)</span></code> at the start, the value is returned. The third argument | |
| should point to a <code class="type pcre2-api rouge"><span class="kt">uint32_t</span></code> integer. If no such value has been set, the call to | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_pattern_info()</span></code> returns the error <code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_UNSET</span></code>. Note that this | |
| limit will only be used during matching if it is less than the limit set or | |
| defaulted by the caller of the match function.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_INFO_FIRSTBITMAP</span></code></span></dt><dd>In the absence of a single first code unit for a non-anchored pattern, | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_compile()</span></code> may construct a 256-bit table that defines a fixed set of | |
| values for the first code unit in any match. For example, a pattern that starts | |
| with <code class="regex rouge"><span class="pcre2-semantic">[abc]</span></code> results in a table with three bits set. When code unit values | |
| greater than 255 are supported, the flag bit for 255 means "any code unit of | |
| value 255 or above". If such a table was constructed, a pointer to it is | |
| returned. Otherwise <code class="constant pcre2-api rouge"><span class="kc">NULL</span></code> is returned. The third argument should point to a | |
| <code class="c rouge" data-lang="c"><span class="kt">const</span> <span class="kt">uint8_t</span> <span class="p">*</span></code> variable.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_INFO_FIRSTCODETYPE</span></code></span></dt><dd>Return information about the first code unit of any matched string, for a | |
| non-anchored pattern. The third argument should point to a <code class="type pcre2-api rouge"><span class="kt">uint32_t</span></code> | |
| variable. If there is a fixed first value, for example, the letter "c" from a | |
| pattern such as <code class="regex rouge"><span class="pcre2-semantic">(cat|cow|coyote)</span></code>, 1 is returned, and the value can be retrieved | |
| using <code class="constant pcre2-api rouge"><span class="no">PCRE2_INFO_FIRSTCODEUNIT</span></code>. If there is no fixed first value, but it is | |
| known that a match can occur only at the start of the subject or following a | |
| newline in the subject, 2 is returned. Otherwise, and for anchored patterns, 0 | |
| is returned.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_INFO_FIRSTCODEUNIT</span></code></span></dt><dd>Return the value of the first code unit of any matched string for a pattern | |
| where <code class="constant pcre2-api rouge"><span class="no">PCRE2_INFO_FIRSTCODETYPE</span></code> returns 1; otherwise return 0. The third | |
| argument should point to a <code class="type pcre2-api rouge"><span class="kt">uint32_t</span></code> variable. In the 8-bit library, the | |
| value is always less than 256. In the 16-bit library the value can be up to | |
| <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-30"><code class="character pcre2-api rouge"><span class="sc">0xffff</span></code><span class="character-card" id="pcre2-character-30" role="tooltip" aria-label="<noncharacter-FFFF> (U+FFFF)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="<noncharacter-FFFF>"></span><span class="character-codepoint" data-codepoint="U+FFFF"></span></span></span>. In the 32-bit library in UTF-32 mode the value can be up to <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-31"><code class="character pcre2-api rouge"><span class="sc">0x10ffff</span></code><span class="character-card" id="pcre2-character-31" role="tooltip" aria-label="<noncharacter-10FFFF> (U+10FFFF)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="<noncharacter-10FFFF>"></span><span class="character-codepoint" data-codepoint="U+10FFFF"></span></span></span>, | |
| and up to <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-32"><code class="character pcre2-api rouge"><span class="sc">0xffffffff</span></code><span class="character-card" id="pcre2-character-32" role="tooltip" aria-label="Outside Unicode range (0xffffffff)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="Outside Unicode range"></span><span class="character-codepoint" data-codepoint="0xffffffff"></span></span></span> when not using UTF-32 mode.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_INFO_FRAMESIZE</span></code></span></dt><dd>Return the size (in bytes) of the data frames that are used to remember | |
| backtracking positions when the pattern is processed by <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> | |
| without the use of JIT. The third argument should point to a <code class="type pcre2-api rouge"><span class="kt">size_t</span></code> | |
| variable. The frame size depends on the number of capturing parentheses in the | |
| pattern. Each additional capture group adds two <code class="type pcre2-api rouge"><span class="kt">PCRE2_SIZE</span></code> variables.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_INFO_HASBACKSLASHC</span></code></span></dt><dd>Return 1 if the pattern contains any instances of <code class="regex rouge"><span class="pcre2-semantic">\C</span></code>, otherwise 0. The third | |
| argument should point to a <code class="type pcre2-api rouge"><span class="kt">uint32_t</span></code> variable.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_INFO_HASCRORLF</span></code></span></dt><dd>Return 1 if the pattern contains any explicit matches for CR or LF characters, | |
| otherwise 0. The third argument should point to a <code class="type pcre2-api rouge"><span class="kt">uint32_t</span></code> variable. An | |
| explicit match is either a literal CR or LF character, or <code class="regex rouge"><span class="pcre2-semantic">\r</span></code> or <code class="regex rouge"><span class="pcre2-semantic">\n</span></code> or one of | |
| the equivalent hexadecimal or octal escape sequences.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_INFO_HEAPLIMIT</span></code></span></dt><dd>If the pattern set a heap memory limit by including an item of the form | |
| <code class="regex rouge"><span class="pcre2-semantic">(*LIMIT_HEAP=<em>nnnn</em>)</span></code> at the start, the value is returned. The third argument | |
| should point to a <code class="type pcre2-api rouge"><span class="kt">uint32_t</span></code> integer. If no such value has been set, the call to | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_pattern_info()</span></code> returns the error <code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_UNSET</span></code>. Note that this | |
| limit will only be used during matching if it is less than the limit set or | |
| defaulted by the caller of the match function.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_INFO_JCHANGED</span></code></span></dt><dd>Return 1 if the <code class="regex rouge"><span class="pcre2-semantic">(?J)</span></code> or <code class="regex rouge"><span class="pcre2-semantic">(?-J)</span></code> option setting is used in the pattern, otherwise 0. | |
| The third argument should point to a <code class="type pcre2-api rouge"><span class="kt">uint32_t</span></code> variable. <code class="regex rouge"><span class="pcre2-semantic">(?J)</span></code> and | |
| <code class="regex rouge"><span class="pcre2-semantic">(?-J)</span></code> set and unset the local <code class="constant pcre2-api rouge"><span class="no">PCRE2_DUPNAMES</span></code> option, respectively.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_INFO_JITSIZE</span></code></span></dt><dd>If the compiled pattern was successfully processed by | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_jit_compile()</span></code>, return the size of the JIT compiled code, otherwise | |
| return zero. The third argument should point to a <code class="type pcre2-api rouge"><span class="kt">size_t</span></code> variable.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_INFO_LASTCODETYPE</span></code></span></dt><dd>Returns 1 if there is a rightmost literal code unit that must exist in any | |
| matched string, other than at its start. The third argument should point to a | |
| <code class="type pcre2-api rouge"><span class="kt">uint32_t</span></code> variable. If there is no such value, 0 is returned. When 1 is | |
| returned, the code unit value itself can be retrieved using | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_INFO_LASTCODEUNIT</span></code>. For anchored patterns, a last literal value is | |
| recorded only if it follows something of variable length. For example, for the | |
| pattern <code class="regex rouge"><span class="pcre2-semantic">^a\d+z\d+</span></code> the returned value is 1 (with "z" returned from | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_INFO_LASTCODEUNIT</span></code>), but for <code class="regex rouge"><span class="pcre2-semantic">^a\dz\d</span></code> the returned value is 0.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_INFO_LASTCODEUNIT</span></code></span></dt><dd>Return the value of the rightmost literal code unit that must exist in any | |
| matched string, other than at its start, for a pattern where | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_INFO_LASTCODETYPE</span></code> returns 1. Otherwise, return 0. The third argument | |
| should point to a <code class="type pcre2-api rouge"><span class="kt">uint32_t</span></code> variable.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_INFO_MATCHEMPTY</span></code></span></dt><dd>Return 1 if the pattern might match an empty string, otherwise 0. The third | |
| argument should point to a <code class="type pcre2-api rouge"><span class="kt">uint32_t</span></code> variable. When a pattern contains | |
| recursive subroutine calls it is not always possible to determine whether or | |
| not it can match an empty string. PCRE2 takes a cautious approach and returns 1 | |
| in such cases.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_INFO_MATCHLIMIT</span></code></span></dt><dd>If the pattern set a match limit by including an item of the form | |
| <code class="regex rouge"><span class="pcre2-semantic">(*LIMIT_MATCH=<em>nnnn</em>)</span></code> at the start, the value is returned. The third argument | |
| should point to a <code class="type pcre2-api rouge"><span class="kt">uint32_t</span></code> integer. If no such value has been set, the call to | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_pattern_info()</span></code> returns the error <code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_UNSET</span></code>. Note that this | |
| limit will only be used during matching if it is less than the limit set or | |
| defaulted by the caller of the match function.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_INFO_MAXLOOKBEHIND</span></code></span></dt><dd><p>A lookbehind assertion moves back a certain number of characters (not code | |
| units) when it starts to process each of its branches. This request returns the | |
| largest of these backward moves. The third argument should point to a <code class="type pcre2-api rouge"><span class="kt">uint32_t</span></code> | |
| integer. The simple assertions <code class="regex rouge"><span class="pcre2-semantic">\b</span></code> and <code class="regex rouge"><span class="pcre2-semantic">\B</span></code> require a one-character lookbehind | |
| and cause <code class="constant pcre2-api rouge"><span class="no">PCRE2_INFO_MAXLOOKBEHIND</span></code> to return 1 in the absence of anything | |
| longer. <code class="regex rouge"><span class="pcre2-semantic">\A</span></code> also registers a one-character lookbehind, though it does not | |
| actually inspect the previous character.</p><p>Note that this information is useful for multi-segment matching only | |
| if the pattern contains no nested lookbehinds. For example, the pattern | |
| <code class="regex rouge"><span class="pcre2-semantic">(?<=a(?<=ba)c)</span></code> returns a maximum lookbehind of 2, but when it is processed, the | |
| first lookbehind moves back by two characters, matches one character, then the | |
| nested lookbehind also moves back by two characters. This puts the matching | |
| point three characters earlier than it was at the start. | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_INFO_MAXLOOKBEHIND</span></code> is really only useful as a debugging tool. See the | |
| <a href="./pcre2partial.html"><code>pcre2partial</code></a> | |
| documentation for a discussion of multi-segment matching.</p></dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_INFO_MINLENGTH</span></code></span></dt><dd>If a minimum length for matching subject strings was computed, its value is | |
| returned. Otherwise the returned value is 0. This value is not computed when | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_NO_START_OPTIMIZE</span></code> is set. The value is a number of characters, which in | |
| UTF mode may be different from the number of code units. The third argument | |
| should point to a <code class="type pcre2-api rouge"><span class="kt">uint32_t</span></code> variable. The value is a lower bound to the | |
| length of any matching string. There may not be any strings of that length that | |
| do actually match, but every string that does match is at least that long.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_INFO_NAMECOUNT</span></code><br><code class="constant pcre2-api rouge"><span class="no">PCRE2_INFO_NAMEENTRYSIZE</span></code><br><code class="constant pcre2-api rouge"><span class="no">PCRE2_INFO_NAMETABLE</span></code></span></dt><dd><p>PCRE2 supports the use of named as well as numbered capturing parentheses. The | |
| names are just an additional way of identifying the parentheses, which still | |
| acquire numbers. Several convenience functions such as | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_substring_get_byname()</span></code> are provided for extracting captured | |
| substrings by name. It is also possible to extract the data directly, by first | |
| converting the name to a number in order to access the correct pointers in the | |
| output vector (described with <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> below). To do the conversion, | |
| you need to use the name-to-number map, which is described by these three | |
| values.</p><p>The map consists of a number of fixed-size entries. <code class="constant pcre2-api rouge"><span class="no">PCRE2_INFO_NAMECOUNT</span></code> gives the number of entries, and <code class="constant pcre2-api rouge"><span class="no">PCRE2_INFO_NAMEENTRYSIZE</span></code> gives the size of each entry in code units; both of these return a <code class="type pcre2-api rouge"><span class="kt">uint32_t</span></code> value. The entry size depends on the length of the longest name.</p> | |
| <p><code class="constant pcre2-api rouge"><span class="no">PCRE2_INFO_NAMETABLE</span></code> returns a pointer to the first entry of the table. This is a <code class="type pcre2-api rouge"><span class="kt">PCRE2_SPTR</span></code> pointer to a block of code units. In the 8-bit library, the first two bytes of each entry are the number of the capturing parenthesis, most significant byte first. In the 16-bit library, the pointer points to 16-bit code units, the first of which contains the parenthesis number. In the 32-bit library, the pointer points to 32-bit code units, the first of which contains the parenthesis number. The rest of the entry is the corresponding name, zero terminated.</p> | |
| <p>The names are in alphabetical order. If <code class="regex rouge"><span class="pcre2-semantic">(?|</span></code> is used to create multiple capture | |
| groups with the same number, as described in the | |
| section <a href="./pcre2pattern.html#duplicate-group-numbers">Duplicate group numbers</a> | |
| in the | |
| <a href="./pcre2pattern.html"><code>pcre2pattern</code></a> | |
| page, the groups may be given the same name, but there is only one entry in the | |
| table. Different names for groups of the same number are not permitted.</p> | |
| <p>Duplicate names for capture groups with different numbers are permitted, but | |
| only if <code class="constant pcre2-api rouge"><span class="no">PCRE2_DUPNAMES</span></code> is set. They appear in the table in the order in which | |
| they were found in the pattern. In the absence of <code class="regex rouge"><span class="pcre2-semantic">(?|</span></code> this is the order of | |
| increasing number; when <code class="regex rouge"><span class="pcre2-semantic">(?|</span></code> is used this is not necessarily the case because | |
| later capture groups may have lower numbers.</p> | |
| <p>As a simple example of the name/number table, consider the following pattern | |
| after compilation by the 8-bit library (assume <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTENDED</span></code> is set, so white | |
| space — including newlines — is ignored):</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(?<date> (?<year>(\d\d)?\d\d) - | |
| (?<month>\d\d) - (?<day>\d\d) )</span></code></pre></div> | |
| <p>There are four named capture groups, so the table has four entries, and each | |
| entry in the table is eight bytes long. The table is as follows, with | |
| non-printing bytes shows in hexadecimal, and undefined bytes shown as ??:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="text">00 01 d a t e 00 ?? | |
| 00 05 d a y 00 ?? ?? | |
| 00 04 m o n t h 00 | |
| 00 02 y e a r 00 ??</code></pre></div> | |
| <p>When writing code to extract data from named capture groups using the | |
| name-to-number map, remember that the length of the entries is likely to be | |
| different for each compiled pattern.</p></dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_INFO_NEWLINE</span></code></span></dt><dd><p>The output is one of the following <code class="type pcre2-api rouge"><span class="kt">uint32_t</span></code> values:</p><dl class="compact" style="--tab-width: 12"><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_NEWLINE_CR</span></code></span></dt><dd>Carriage return (CR)</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_NEWLINE_LF</span></code></span></dt><dd>Linefeed (LF)</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_NEWLINE_CRLF</span></code></span></dt><dd>Carriage return, linefeed (CRLF)</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_NEWLINE_ANY</span></code></span></dt><dd>Any Unicode line ending</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_NEWLINE_ANYCRLF</span></code></span></dt><dd>Any of CR, LF, or CRLF</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_NEWLINE_NUL</span></code></span></dt><dd>The NUL character (binary zero)</dd></div></dl> | |
| <p>This identifies the character sequence that will be recognized as meaning | |
| "newline" while matching.</p></dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_INFO_SIZE</span></code></span></dt><dd>Return the size of the compiled pattern in bytes (for all three libraries). The | |
| third argument should point to a <code class="type pcre2-api rouge"><span class="kt">size_t</span></code> variable. This value includes the | |
| size of the general data block that precedes the code units of the compiled | |
| pattern itself. The value that is used when <code class="function pcre2-api rouge"><span class="nf">pcre2_compile()</span></code> is getting | |
| memory in which to place the compiled pattern may be slightly larger than the | |
| value returned by this option, because there are cases where the code that | |
| calculates the size has to over-estimate. Processing a pattern with the JIT | |
| compiler does not alter the value returned by this option.</dd></div></dl></section> | |
| <section class="doc-section level-1"><h2 id="information-about-pattern-callouts">Information about a pattern’s callouts</h2><div class="listing-block prototype"><pre class="rouge highlight"><code data-lang="c"><span class="kt">int</span> <span class="nf">pcre2_callout_enumerate</span><span class="p">(</span> | |
| <span class="kt">const</span> <span class="kt">pcre2_code</span> <span class="p">*</span><span class="nv">code</span><span class="p">,</span> | |
| <span class="kt">int</span> <span class="p">(</span><span class="p">*</span><span class="nv">callback</span><span class="p">)(</span><span class="kt">pcre2_callout_enumerate_block</span> <span class="p">*</span><span class="nv">callout_block</span><span class="p">,</span> | |
| <span class="kt">void</span> <span class="p">*</span><span class="nv">callout_data</span><span class="p">),</span> | |
| <span class="kt">void</span> <span class="p">*</span><span class="nv">callout_data</span><span class="p">);</span></code></pre></div> | |
| <p>A script language that supports the use of string arguments in callouts might | |
| like to scan all the callouts in a pattern before running the match. This can | |
| be done by calling <code class="function pcre2-api rouge"><span class="nf">pcre2_callout_enumerate()</span></code>. The first argument is a | |
| pointer to a compiled pattern, the second points to a callback function, and | |
| the third is arbitrary user data. The callback function is called for every | |
| callout in the pattern in the order in which they appear. Its first argument is | |
| a pointer to a callout enumeration block, and its second argument is the | |
| <code class="parameter pcre2-api rouge"><span class="nv">user_data</span></code> value that was passed to <code class="function pcre2-api rouge"><span class="nf">pcre2_callout_enumerate()</span></code>. The | |
| contents of the callout enumeration block are described in the | |
| <a href="./pcre2callout.html"><code>pcre2callout</code></a> | |
| documentation, which also gives further details about callouts.</p></section> | |
| <section class="doc-section level-1"><h2 id="_serialization_and_precompiling">Serialization and precompiling</h2><p>It is possible to save compiled patterns on disc or elsewhere, and reload them | |
| later, subject to a number of restrictions. The host on which the patterns are | |
| reloaded must be running the same version of PCRE2, with the same code unit | |
| width, and must also have the same endianness, pointer width, and <code class="type pcre2-api rouge"><span class="kt">PCRE2_SIZE</span></code> | |
| type. Before compiled patterns can be saved, they must be converted to a | |
| "serialized" form, which in the case of PCRE2 is really just a bytecode dump. | |
| The functions whose names begin with <code class="c rouge" data-lang="c"><span class="kt">pcre2_serialize_</span></code> are used for | |
| converting to and from the serialized form. They are described in the | |
| <a href="./pcre2serialize.html"><code>pcre2serialize</code></a> | |
| documentation. Note that PCRE2 serialization does not convert compiled patterns | |
| to an abstract format like Java or .NET serialization.</p></section> | |
| <section class="doc-section level-1"><h2 id="_the_match_data_block">The match data block</h2><div class="listing-block prototype"><pre class="rouge highlight"><code data-lang="c"><span class="kt">pcre2_match_data</span> <span class="p">*</span><span class="nf">pcre2_match_data_create</span><span class="p">(</span> | |
| <span class="kt">uint32_t</span> <span class="nv">oveccount</span><span class="p">,</span> <span class="kt">pcre2_general_context</span> <span class="p">*</span><span class="nv">gcontext</span><span class="p">);</span> | |
| <span class="kt">pcre2_match_data</span> <span class="p">*</span><span class="nf">pcre2_match_data_create_from_pattern</span><span class="p">(</span> | |
| <span class="kt">const</span> <span class="kt">pcre2_code</span> <span class="p">*</span><span class="nv">code</span><span class="p">,</span> <span class="kt">pcre2_general_context</span> <span class="p">*</span><span class="nv">gcontext</span><span class="p">);</span> | |
| <span class="kt">void</span> <span class="nf">pcre2_match_data_free</span><span class="p">(</span><span class="kt">pcre2_match_data</span> <span class="p">*</span><span class="nv">match_data</span><span class="p">);</span></code></pre></div> | |
| <p>Information about a successful or unsuccessful match is placed in a match | |
| data block, which is an opaque structure that is accessed by function calls. In | |
| particular, the match data block contains a vector of offsets into the subject | |
| string that define the matched parts of the subject. This is known as the | |
| "ovector".</p> | |
| <p>Before calling <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code>, <code class="function pcre2-api rouge"><span class="nf">pcre2_dfa_match()</span></code>, or | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_jit_match()</span></code> you must create a match data block by calling one of | |
| the creation functions above. For <code class="function pcre2-api rouge"><span class="nf">pcre2_match_data_create()</span></code>, the first | |
| argument is the number of pairs of offsets in the ovector.</p> | |
| <p>When using <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code>, one pair of offsets is required to identify the | |
| string that matched the whole pattern, with an additional pair for each | |
| captured substring. For example, a value of 4 creates enough space to record | |
| the matched portion of the subject plus three captured substrings.</p> | |
| <p>When using <code class="function pcre2-api rouge"><span class="nf">pcre2_dfa_match()</span></code> there may be multiple matched substrings of | |
| different lengths at the same point in the subject. The ovector should be made | |
| large enough to hold as many as are expected.</p> | |
| <p>A minimum of at least 1 pair is imposed by <code class="function pcre2-api rouge"><span class="nf">pcre2_match_data_create()</span></code>, so | |
| it is always possible to return the overall matched string in the case of | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> or the longest match in the case of | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_dfa_match()</span></code>. The maximum number of pairs is 65,535; if the first | |
| argument of <code class="function pcre2-api rouge"><span class="nf">pcre2_match_data_create()</span></code> is greater than this, 65,535 is | |
| used.</p> | |
| <p>The second argument of <code class="function pcre2-api rouge"><span class="nf">pcre2_match_data_create()</span></code> is a pointer to a | |
| general context, which can specify custom memory management for obtaining the | |
| memory for the match data block. If you are not using custom memory management, | |
| pass <code class="constant pcre2-api rouge"><span class="kc">NULL</span></code>, which causes <code class="c rouge" data-lang="c"><span class="nf">malloc</span><span class="p">()</span></code> to be used.</p> | |
| <p>For <code class="function pcre2-api rouge"><span class="nf">pcre2_match_data_create_from_pattern()</span></code>, the first argument is a | |
| pointer to a compiled pattern. The ovector is created to be exactly the right | |
| size to hold all the substrings a pattern might capture when matched using | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code>. You should not use this call when matching with | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_dfa_match()</span></code>. The second argument is again a pointer to a general | |
| context, but in this case if <code class="constant pcre2-api rouge"><span class="kc">NULL</span></code> is passed, the memory is obtained using the | |
| same allocator that was used for the compiled pattern (custom or default).</p> | |
| <p>A match data block can be used many times, with the same or different compiled | |
| patterns. You can extract information from a match data block after a match | |
| operation has finished, using functions that are described in the sections | |
| <a href="#matched-strings">How <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> returns a string and captured substrings</a> | |
| and | |
| <a href="#other-match-information">Other information about a match</a> | |
| below.</p> | |
| <p>When a call of <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> fails, valid data is available in the match | |
| block only when the error is <code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_NOMATCH</span></code>, <code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_PARTIAL</span></code>, or one | |
| of the error codes for an invalid UTF string. Exactly what is available depends | |
| on the error, and is detailed below.</p> | |
| <p>When one of the matching functions is called, pointers to the compiled pattern | |
| and the subject string are set in the match data block so that they can be | |
| referenced by the extraction functions after a successful match. After running | |
| a match, you must not free a compiled pattern or a subject string until after | |
| all operations on the match data block (for that match) have taken place, | |
| unless, in the case of the subject string, you have used the | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_COPY_MATCHED_SUBJECT</span></code> option, which is described in the section | |
| <a href="#match-option-bits">Option bits for <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code></a> | |
| below.</p> | |
| <p>When a match data block itself is no longer needed, it should be freed by | |
| calling <code class="function pcre2-api rouge"><span class="nf">pcre2_match_data_free()</span></code>. If this function is called with a <code class="constant pcre2-api rouge"><span class="kc">NULL</span></code> | |
| argument, it returns immediately, without doing anything.</p></section> | |
| <section class="doc-section level-1"><h2 id="_memory_use_for_match_data_blocks">Memory use for match data blocks</h2><div class="listing-block prototype"><pre class="rouge highlight"><code data-lang="c"><span class="kt">PCRE2_SIZE</span> <span class="nf">pcre2_get_match_data_size</span><span class="p">(</span><span class="kt">pcre2_match_data</span> <span class="p">*</span><span class="nv">match_data</span><span class="p">);</span> | |
| <span class="kt">PCRE2_SIZE</span> <span class="nf">pcre2_get_match_data_heapframes_size</span><span class="p">(</span> | |
| <span class="kt">pcre2_match_data</span> <span class="p">*</span><span class="nv">match_data</span><span class="p">);</span></code></pre></div> | |
| <p>The size of a match data block depends on the size of the ovector that it | |
| contains. The function <code class="function pcre2-api rouge"><span class="nf">pcre2_get_match_data_size()</span></code> returns the size, in | |
| bytes, of the block that is its argument.</p> | |
| <p>When <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> runs interpretively (that is, without using JIT), it | |
| makes use of a vector of data frames for remembering backtracking positions. | |
| The size of each individual frame depends on the number of capturing | |
| parentheses in the pattern and can be obtained by calling | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_pattern_info()</span></code> with the <code class="constant pcre2-api rouge"><span class="no">PCRE2_INFO_FRAMESIZE</span></code> option (see the | |
| section <a href="#information-about-compiled-pattern">Information about a compiled pattern</a> | |
| above).</p> | |
| <p>Heap memory is used for the frames vector; if the initial memory block turns | |
| out to be too small during matching, it is automatically expanded. When | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> returns, the memory is not freed, but remains attached to | |
| the match data block, for use by any subsequent matches that use the same | |
| block. It is automatically freed when the match data block itself is freed.</p> | |
| <p>You can find the current size of the frames vector that a match data block owns | |
| by calling <code class="function pcre2-api rouge"><span class="nf">pcre2_get_match_data_heapframes_size()</span></code>. For a newly created | |
| match data block the size will be zero. Some types of match may require a lot | |
| of frames and thus a large vector; applications that run in environments where | |
| memory is constrained can check this and free the match data block if the heap | |
| frames vector has become too big.</p></section> | |
| <section class="doc-section level-1"><h2 id="_matching_a_pattern_the_traditional_function">Matching a pattern: the traditional function</h2><div class="listing-block prototype"><pre class="rouge highlight"><code data-lang="c"><span class="kt">int</span> <span class="nf">pcre2_match</span><span class="p">(</span><span class="kt">const</span> <span class="kt">pcre2_code</span> <span class="p">*</span><span class="nv">code</span><span class="p">,</span> <span class="kt">PCRE2_SPTR</span> <span class="nv">subject</span><span class="p">,</span> | |
| <span class="kt">PCRE2_SIZE</span> <span class="nv">length</span><span class="p">,</span> <span class="kt">PCRE2_SIZE</span> <span class="nv">start_offset</span><span class="p">,</span> | |
| <span class="kt">uint32_t</span> <span class="nv">options</span><span class="p">,</span> <span class="kt">pcre2_match_data</span> <span class="p">*</span><span class="nv">match_data</span><span class="p">,</span> | |
| <span class="kt">pcre2_match_context</span> <span class="p">*</span><span class="nv">mcontext</span><span class="p">);</span></code></pre></div> | |
| <p>The function <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> is called to match a subject string against a | |
| compiled pattern, which is passed in the <code class="parameter pcre2-api rouge"><span class="nv">code</span></code> argument. You can call | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> with the same <code class="parameter pcre2-api rouge"><span class="nv">code</span></code> argument as many times as you | |
| like, in order to find multiple matches in the subject string or to match | |
| different subject strings with the same pattern.</p> | |
| <p>This function is the main matching facility of the library, and it operates in | |
| a Perl-like manner. For specialist use there is also an alternative matching | |
| function, which is described | |
| below | |
| in the section about the <code class="function pcre2-api rouge"><span class="nf">pcre2_dfa_match()</span></code> function.</p> | |
| <p>Here is an example of a simple call to <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code>:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="c"><span class="kt">pcre2_match_data</span> <span class="p">*</span><span class="nv">md</span> <span class="o">=</span> <span class="nf">pcre2_match_data_create</span><span class="p">(</span><span class="mi">4</span><span class="p">,</span> <span class="kc">NULL</span><span class="p">);</span> | |
| <span class="kt">int</span> <span class="nv">rc</span> <span class="o">=</span> <span class="nf">pcre2_match</span><span class="p">(</span> | |
| <span class="nv">re</span><span class="p">,</span> <span class="cm">/* result of pcre2_compile() */</span> | |
| <span class="s">"some string"</span><span class="p">,</span> <span class="cm">/* the subject string */</span> | |
| <span class="mi">11</span><span class="p">,</span> <span class="cm">/* the length of the subject string */</span> | |
| <span class="mi">0</span><span class="p">,</span> <span class="cm">/* start at offset 0 in the subject */</span> | |
| <span class="mi">0</span><span class="p">,</span> <span class="cm">/* default options */</span> | |
| <span class="nv">md</span><span class="p">,</span> <span class="cm">/* the match data block */</span> | |
| <span class="kc">NULL</span><span class="p">);</span> <span class="cm">/* a match context; NULL means use defaults */</span></code></pre></div> | |
| <p>If the subject string is zero-terminated, the length can be given as | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_ZERO_TERMINATED</span></code>. A match context must be provided if certain less common | |
| matching parameters are to be changed. For details, see the section | |
| <a href="#match-context">The match context</a> | |
| above.</p> | |
| <section class="doc-section level-2"><h3 id="_the_string_to_be_matched_by_pcre2_match">The string to be matched by <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code></h3><p>The subject string is passed to <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> as a pointer in | |
| <code class="parameter pcre2-api rouge"><span class="nv">subject</span></code>, a length in <code class="parameter pcre2-api rouge"><span class="nv">length</span></code>, and a starting offset in | |
| <code class="parameter pcre2-api rouge"><span class="nv">start_offset</span></code>. The length and offset are in code units, not characters. | |
| That is, they are in bytes for the 8-bit library, 16-bit code units for the | |
| 16-bit library, and 32-bit code units for the 32-bit library, whether or not | |
| UTF processing is enabled. As a special case, if <code class="parameter pcre2-api rouge"><span class="nv">subject</span></code> is <code class="constant pcre2-api rouge"><span class="kc">NULL</span></code> and | |
| <code class="parameter pcre2-api rouge"><span class="nv">length</span></code> is zero, the subject is assumed to be an empty string. If | |
| <code class="parameter pcre2-api rouge"><span class="nv">length</span></code> is non-zero, an error occurs if <code class="parameter pcre2-api rouge"><span class="nv">subject</span></code> is <code class="constant pcre2-api rouge"><span class="kc">NULL</span></code>.</p> | |
| <p>If <code class="parameter pcre2-api rouge"><span class="nv">start_offset</span></code> is greater than the length of the subject, | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> returns <code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_BADOFFSET</span></code>. When the starting offset is | |
| zero, the search for a match starts at the beginning of the subject, and this | |
| is by far the most common case. In UTF-8 or UTF-16 mode, the starting offset | |
| must point to the start of a character, or to the end of the subject (in UTF-32 | |
| mode, one code unit equals one character, so all offsets are valid). Like the | |
| pattern string, the subject may contain binary zeros.</p> | |
| <p>A non-zero starting offset is useful when searching for another match in the | |
| same subject by calling <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> again after a previous success. | |
| Setting <code class="parameter pcre2-api rouge"><span class="nv">start_offset</span></code> differs from passing over a shortened string and | |
| setting <code class="constant pcre2-api rouge"><span class="no">PCRE2_NOTBOL</span></code> in the case of a pattern that begins with any kind of | |
| lookbehind. For example, consider the pattern</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">\Biss\B</span></code></pre></div> | |
| <p>which finds occurrences of <code class="subject rouge"><span class="pcre2-semantic">iss</span></code> in the middle of words. (<code class="regex rouge"><span class="pcre2-semantic">\B</span></code> matches only if | |
| the current position in the subject is not a word boundary.) When applied to | |
| the string <code class="subject rouge"><span class="pcre2-semantic">Mississippi</span></code> the first call to <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> finds the first | |
| occurrence. If <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> is called again with just the remainder of | |
| the subject, namely <code class="subject rouge"><span class="pcre2-semantic">issippi</span></code>, it does not match, because <code class="regex rouge"><span class="pcre2-semantic">\B</span></code> is always false | |
| at the start of the subject, which is deemed to be a word boundary. However, if | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> is passed the entire string again, but with | |
| <code class="parameter pcre2-api rouge"><span class="nv">start_offset</span></code> set to 4, it finds the second occurrence of <code class="subject rouge"><span class="pcre2-semantic">iss</span></code> because it | |
| is able to look behind the starting point to discover that it is preceded by a | |
| letter.</p> | |
| <p>Finding all the matches in a subject is tricky when the pattern can match an | |
| empty string. PCRE2 includes a helper API to assist with this; see the | |
| section <a href="#iterating-over-matches">Iterating over all matches</a> | |
| below | |
| for details.</p> | |
| <p>If a non-zero starting offset is passed when the pattern is anchored, a single | |
| attempt to match at the given offset is made. This can only succeed if the | |
| pattern does not require the match to be at the start of the subject. In other | |
| words, the anchoring must be the result of setting the <code class="constant pcre2-api rouge"><span class="no">PCRE2_ANCHORED</span></code> option or | |
| the use of <code class="regex rouge"><span class="pcre2-semantic">.*</span></code> with <code class="constant pcre2-api rouge"><span class="no">PCRE2_DOTALL</span></code>, not by starting the pattern with <code class="regex rouge"><span class="pcre2-semantic">^</span></code> or <code class="regex rouge"><span class="pcre2-semantic">\A</span></code>.</p></section> | |
| <section class="doc-section level-2"><h3 id="match-option-bits">Option bits for <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code></h3><p>The unused bits of the <code class="parameter pcre2-api rouge"><span class="nv">options</span></code> argument for <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> must be | |
| zero. The only bits that may be set are <code class="constant pcre2-api rouge"><span class="no">PCRE2_ANCHORED</span></code>, | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_COPY_MATCHED_SUBJECT</span></code>, <code class="constant pcre2-api rouge"><span class="no">PCRE2_DISABLE_RECURSELOOP_CHECK</span></code>, <code class="constant pcre2-api rouge"><span class="no">PCRE2_ENDANCHORED</span></code>, | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_NOTBOL</span></code>, <code class="constant pcre2-api rouge"><span class="no">PCRE2_NOTEOL</span></code>, <code class="constant pcre2-api rouge"><span class="no">PCRE2_NOTEMPTY</span></code>, <code class="constant pcre2-api rouge"><span class="no">PCRE2_NOTEMPTY_ATSTART</span></code>, | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_NO_JIT</span></code>, <code class="constant pcre2-api rouge"><span class="no">PCRE2_NO_UTF_CHECK</span></code>, <code class="constant pcre2-api rouge"><span class="no">PCRE2_PARTIAL_HARD</span></code>, and <code class="constant pcre2-api rouge"><span class="no">PCRE2_PARTIAL_SOFT</span></code>. | |
| Their action is described below.</p> | |
| <p>Setting <code class="constant pcre2-api rouge"><span class="no">PCRE2_ANCHORED</span></code> or <code class="constant pcre2-api rouge"><span class="no">PCRE2_ENDANCHORED</span></code> at match time is not supported by | |
| the just-in-time (JIT) compiler. If it is set, JIT matching is disabled and the | |
| interpretive code in <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> is run. | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_DISABLE_RECURSELOOP_CHECK</span></code> is ignored by JIT, but apart from <code class="constant pcre2-api rouge"><span class="no">PCRE2_NO_JIT</span></code> | |
| (obviously), the remaining options are supported for JIT matching.</p> | |
| <dl class="options spaced" style="--tab-width: 12"><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_ANCHORED</span></code></span></dt><dd>The <code class="constant pcre2-api rouge"><span class="no">PCRE2_ANCHORED</span></code> option limits <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> to matching at the first | |
| matching position. If a pattern was compiled with <code class="constant pcre2-api rouge"><span class="no">PCRE2_ANCHORED</span></code>, or turned out | |
| to be anchored by virtue of its contents, it cannot be made unanchored at | |
| matching time. Note that setting the option at match time disables JIT | |
| matching.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_COPY_MATCHED_SUBJECT</span></code></span></dt><dd>By default, a pointer to the subject is remembered in the match data block so | |
| that, after a successful match, it can be referenced by the substring | |
| extraction functions. This means that the subject’s memory must not be freed | |
| until all such operations are complete. For some applications where the | |
| lifetime of the subject string is not guaranteed, it may be necessary to make a | |
| copy of the subject string, but it is wasteful to do this unless the match is | |
| successful. After a successful match, if <code class="constant pcre2-api rouge"><span class="no">PCRE2_COPY_MATCHED_SUBJECT</span></code> is set, the | |
| subject is copied and the new pointer is remembered in the match data block | |
| instead of the original subject pointer. The memory allocator that was used for | |
| the match block itself is used. The copy is automatically freed when | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_match_data_free()</span></code> is called to free the match data block. It is also | |
| automatically freed if the match data block is re-used for another match | |
| operation.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_DISABLE_RECURSELOOP_CHECK</span></code></span></dt><dd><p>This option is relevant only to <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> for interpretive matching. | |
| It is ignored when JIT is used, and is forbidden for <code class="function pcre2-api rouge"><span class="nf">pcre2_dfa_match()</span></code>.</p><p>The use of recursion in patterns can lead to infinite loops. In the | |
| interpretive matcher these would be eventually caught by the match or heap | |
| limits, but this could take a long time and/or use a lot of memory if the | |
| limits are large. There is therefore a check at the start of each recursion. | |
| If the same group is still active from a previous call, and the current subject | |
| pointer is the same as it was at the start of that group, and the furthest | |
| inspected character of the subject has not changed, an error is generated.</p> | |
| <p>There are rare cases of matches that would complete, but nevertheless trigger | |
| this error. This option disables the check. It is provided mainly for testing | |
| when comparing JIT and interpretive behaviour.</p></dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_ENDANCHORED</span></code></span></dt><dd>If the <code class="constant pcre2-api rouge"><span class="no">PCRE2_ENDANCHORED</span></code> option is set, any string that <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> | |
| matches must be right at the end of the subject string. Note that setting the | |
| option at match time disables JIT matching.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_NOTBOL</span></code></span></dt><dd>This option specifies that first character of the subject string is not the | |
| beginning of a line, so the circumflex metacharacter should not match before | |
| it. Setting this without having set <code class="constant pcre2-api rouge"><span class="no">PCRE2_MULTILINE</span></code> at compile time causes | |
| circumflex never to match. This option affects only the behaviour of the | |
| circumflex metacharacter. It does not affect <code class="regex rouge"><span class="pcre2-semantic">\A</span></code>.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_NOTEOL</span></code></span></dt><dd>This option specifies that the end of the subject string is not the end of a | |
| line, so the dollar metacharacter should not match it nor (except in multiline | |
| mode) a newline immediately before it. Setting this without having set | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_MULTILINE</span></code> at compile time causes dollar never to match. This option | |
| affects only the behaviour of the dollar metacharacter. It does not affect <code class="regex rouge"><span class="pcre2-semantic">\Z</span></code> | |
| or <code class="regex rouge"><span class="pcre2-semantic">\z</span></code>.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_NOTEMPTY</span></code></span></dt><dd><p>An empty string is not considered to be a valid match if this option is set. If | |
| there are alternatives in the pattern, they are tried. If all the alternatives | |
| match the empty string, the entire match fails. For example, if the pattern</p><p><code class="regex rouge"><span class="pcre2-semantic">a?b?</span></code></p> | |
| <p>is applied to a string not beginning with <code class="subject rouge"><span class="pcre2-semantic">a</span></code> or <code class="subject rouge"><span class="pcre2-semantic">b</span></code>, it matches an empty | |
| string at the start of the subject. With <code class="constant pcre2-api rouge"><span class="no">PCRE2_NOTEMPTY</span></code> set, this match is not | |
| valid, so <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> searches further into the string for occurrences | |
| of <code class="subject rouge"><span class="pcre2-semantic">a</span></code> or <code class="subject rouge"><span class="pcre2-semantic">b</span></code>.</p></dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_NOTEMPTY_ATSTART</span></code></span></dt><dd>This is like <code class="constant pcre2-api rouge"><span class="no">PCRE2_NOTEMPTY</span></code>, except that it locks out an empty string match | |
| only at the first matching position, that is, at the start of the subject plus | |
| the starting offset. An empty string match later in the subject is permitted. | |
| If the pattern is anchored, such a match can occur only if the pattern contains | |
| <code class="regex rouge"><span class="pcre2-semantic">\K</span></code>.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_NO_JIT</span></code></span></dt><dd>By default, if a pattern has been successfully processed by | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_jit_compile()</span></code>, JIT is automatically used when <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> | |
| is called with options that JIT supports. Setting <code class="constant pcre2-api rouge"><span class="no">PCRE2_NO_JIT</span></code> disables the use | |
| of JIT; it forces matching to be done by the interpreter.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_NO_UTF_CHECK</span></code></span></dt><dd><p>When <code class="constant pcre2-api rouge"><span class="no">PCRE2_UTF</span></code> is set at compile time, the validity of the subject as a UTF | |
| string is checked unless <code class="constant pcre2-api rouge"><span class="no">PCRE2_NO_UTF_CHECK</span></code> is passed to <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> or | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_MATCH_INVALID_UTF</span></code> was passed to <code class="function pcre2-api rouge"><span class="nf">pcre2_compile()</span></code>. The latter special | |
| case is discussed in detail in the | |
| <a href="./pcre2unicode.html"><code>pcre2unicode</code></a> | |
| documentation.</p><p>In the default case, if a non-zero starting offset is given, the check is | |
| applied only to that part of the subject that could be inspected during | |
| matching, and there is a check that the starting offset points to the first | |
| code unit of a character or to the end of the subject. If there are no | |
| lookbehind assertions in the pattern, the check starts at the starting offset. | |
| Otherwise, it starts at the length of the longest lookbehind before the | |
| starting offset, or at the start of the subject if there are not that many | |
| characters before the starting offset. Note that the sequences <code class="regex rouge"><span class="pcre2-semantic">\b</span></code> and <code class="regex rouge"><span class="pcre2-semantic">\B</span></code> are | |
| one-character lookbehinds.</p> | |
| <p>The check is carried out before any other processing takes place, and a | |
| negative error code is returned if the check fails. There are several UTF error | |
| codes for each code unit width, corresponding to different problems with the | |
| code unit sequence. There are discussions about the validity of | |
| UTF-8 strings, | |
| UTF-16 strings, | |
| and | |
| UTF-32 strings | |
| in the | |
| <a href="./pcre2unicode.html"><code>pcre2unicode</code></a> | |
| documentation.</p> | |
| <p>If you know that your subject is valid, and you want to skip this check for | |
| performance reasons, you can set the <code class="constant pcre2-api rouge"><span class="no">PCRE2_NO_UTF_CHECK</span></code> option when calling | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code>. You might want to do this for the second and subsequent | |
| calls to <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> if you are making repeated calls to find multiple | |
| matches in the same subject string.</p> | |
| <section class="admonition-block warning" role="doc-notice"><h6 class="block-title label-only"><span class="title-label">Warning: </span></h6><p>Unless <code class="constant pcre2-api rouge"><span class="no">PCRE2_MATCH_INVALID_UTF</span></code> was set at compile time, when | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_NO_UTF_CHECK</span></code> is set at match time the effect of passing an invalid | |
| string as a subject, or an invalid value of <code class="parameter pcre2-api rouge"><span class="nv">start_offset</span></code>, is undefined. | |
| Your program may crash or loop indefinitely or give wrong results.</p></section></dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_PARTIAL_HARD</span></code><br><code class="constant pcre2-api rouge"><span class="no">PCRE2_PARTIAL_SOFT</span></code></span></dt><dd><p>These options turn on the partial matching feature. A partial match occurs if | |
| the end of the subject string is reached successfully, but there are not enough | |
| subject characters to complete the match. In addition, either at least one | |
| character must have been inspected or the pattern must contain a lookbehind, or | |
| the pattern must be one that could match an empty string.</p><p>If this situation arises when <code class="constant pcre2-api rouge"><span class="no">PCRE2_PARTIAL_SOFT</span></code> (but not <code class="constant pcre2-api rouge"><span class="no">PCRE2_PARTIAL_HARD</span></code>) | |
| is set, matching continues by testing any remaining alternatives. Only if no | |
| complete match can be found is <code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_PARTIAL</span></code> returned instead of | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_NOMATCH</span></code>. In other words, <code class="constant pcre2-api rouge"><span class="no">PCRE2_PARTIAL_SOFT</span></code> specifies that the | |
| caller is prepared to handle a partial match, but only if no complete match can | |
| be found.</p> | |
| <p>If <code class="constant pcre2-api rouge"><span class="no">PCRE2_PARTIAL_HARD</span></code> is set, it overrides <code class="constant pcre2-api rouge"><span class="no">PCRE2_PARTIAL_SOFT</span></code>. In this case, if | |
| a partial match is found, <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> immediately returns | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_PARTIAL</span></code>, without considering any other alternatives. In other | |
| words, when <code class="constant pcre2-api rouge"><span class="no">PCRE2_PARTIAL_HARD</span></code> is set, a partial match is considered to be more | |
| important than an alternative complete match.</p> | |
| <p>There is a more detailed discussion of partial and multi-segment matching, with | |
| examples, in the | |
| <a href="./pcre2partial.html"><code>pcre2partial</code></a> | |
| documentation.</p></dd></div></dl></section></section> | |
| <section class="doc-section level-1"><h2 id="_newline_handling_when_matching">Newline handling when matching</h2><p>When PCRE2 is built, a default newline convention is set; this is usually the | |
| standard convention for the operating system. The default can be overridden in | |
| a | |
| compile context | |
| by calling <code class="function pcre2-api rouge"><span class="nf">pcre2_set_newline()</span></code>. It can also be overridden by starting a | |
| pattern string with, for example, <code class="regex rouge"><span class="pcre2-semantic">(*CRLF)</span></code>, as described in the | |
| section <a href="./pcre2pattern.html#newline-conventions">Newline conventions</a> | |
| in the | |
| <a href="./pcre2pattern.html"><code>pcre2pattern</code></a> | |
| page. During matching, the newline choice affects the behaviour of the dot, | |
| circumflex, and dollar metacharacters. It may also alter the way the match | |
| starting position is advanced after a match failure for an unanchored pattern.</p> | |
| <p>When <code class="constant pcre2-api rouge"><span class="no">PCRE2_NEWLINE_CRLF</span></code>, <code class="constant pcre2-api rouge"><span class="no">PCRE2_NEWLINE_ANYCRLF</span></code>, or <code class="constant pcre2-api rouge"><span class="no">PCRE2_NEWLINE_ANY</span></code> is set as | |
| the newline convention, and a match attempt for an unanchored pattern fails | |
| when the current starting position is at a CRLF sequence, and the pattern | |
| contains no explicit matches for CR or LF characters, the match position is | |
| advanced by two characters instead of one, in other words, to after the CRLF.</p> | |
| <p>The above rule is a compromise that makes the most common cases work as | |
| expected. For example, if the pattern is <code class="regex rouge"><span class="pcre2-semantic">.+A</span></code> (and the <code class="constant pcre2-api rouge"><span class="no">PCRE2_DOTALL</span></code> option is | |
| not set), it does not match the string <code class="subject rouge"><span class="pcre2-semantic">\r\nA</span></code> because, after failing at the | |
| start, it skips both the CR and the LF before retrying. However, the pattern | |
| <code class="regex rouge"><span class="pcre2-semantic">[\r\n]A</span></code> does match that string, because it contains an explicit CR or LF | |
| reference, and so advances only by one character after the first failure.</p> | |
| <p>An explicit match for CR of LF is either a literal appearance of one of those | |
| characters in the pattern, or one of the <code class="regex rouge"><span class="pcre2-semantic">\r</span></code> or <code class="regex rouge"><span class="pcre2-semantic">\n</span></code> or equivalent octal or | |
| hexadecimal escape sequences. Implicit matches such as <code class="regex rouge"><span class="pcre2-semantic">[^X]</span></code> do not count, nor | |
| does <code class="regex rouge"><span class="pcre2-semantic">\s</span></code>, even though it includes CR and LF in the characters that it matches.</p> | |
| <p>Notwithstanding the above, anomalous effects may still occur when CRLF is a | |
| valid newline sequence and explicit <code class="regex rouge"><span class="pcre2-semantic">\r</span></code> or <code class="regex rouge"><span class="pcre2-semantic">\n</span></code> escapes appear in the pattern.</p></section> | |
| <section class="doc-section level-1"><h2 id="matched-strings">How <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> returns a string and captured substrings</h2><div class="listing-block prototype"><pre class="rouge highlight"><code data-lang="c"><span class="kt">uint32_t</span> <span class="nf">pcre2_get_ovector_count</span><span class="p">(</span><span class="kt">pcre2_match_data</span> <span class="p">*</span><span class="nv">match_data</span><span class="p">);</span> | |
| <span class="kt">PCRE2_SIZE</span> <span class="p">*</span><span class="nf">pcre2_get_ovector_pointer</span><span class="p">(</span><span class="kt">pcre2_match_data</span> <span class="p">*</span><span class="nv">match_data</span><span class="p">);</span></code></pre></div> | |
| <p>In general, a pattern matches a certain portion of the subject, and in | |
| addition, further substrings from the subject may be picked out by | |
| parenthesized parts of the pattern. Following the usage in Jeffrey Friedl’s | |
| book, this is called "capturing" in what follows, and the phrase "capture | |
| group" (Perl terminology) is used for a fragment of a pattern that picks out a | |
| substring. PCRE2 supports several other kinds of parenthesized group that do | |
| not cause substrings to be captured. The <code class="function pcre2-api rouge"><span class="nf">pcre2_pattern_info()</span></code> function | |
| can be used to find out how many capture groups there are in a compiled | |
| pattern.</p> | |
| <p>You can use auxiliary functions for accessing captured substrings | |
| by number | |
| or | |
| by name, | |
| as described in sections below.</p> | |
| <p>Alternatively, you can make direct use of the vector of <code class="type pcre2-api rouge"><span class="kt">PCRE2_SIZE</span></code> values, | |
| called the ovector, which contains the offsets of captured strings. It is | |
| part of the | |
| match data block. | |
| The function <code class="function pcre2-api rouge"><span class="nf">pcre2_get_ovector_pointer()</span></code> returns the address of the | |
| ovector, and <code class="function pcre2-api rouge"><span class="nf">pcre2_get_ovector_count()</span></code> returns the number of pairs of | |
| values it contains.</p> | |
| <p>Within the ovector, the first in each pair of values is set to the offset of | |
| the first code unit of a substring, and the second is set to the offset of the | |
| first code unit after the end of a substring. These values are always code unit | |
| offsets, not character offsets. That is, they are byte offsets in the 8-bit | |
| library, 16-bit offsets in the 16-bit library, and 32-bit offsets in the 32-bit | |
| library.</p> | |
| <p>After a partial match (error return <code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_PARTIAL</span></code>), only the first pair | |
| of offsets (that is, <code class="c rouge" data-lang="c"><span class="nv">ovector</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span></code> and <code class="c rouge" data-lang="c"><span class="nv">ovector</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span></code>) are set. They | |
| identify the part of the subject that was partially matched. See the | |
| <a href="./pcre2partial.html"><code>pcre2partial</code></a> | |
| documentation for details of partial matching.</p> | |
| <p>After a fully successful match, the first pair of offsets identifies the | |
| portion of the subject string that was matched by the entire pattern. The next | |
| pair is used for the first captured substring, and so on. The value returned by | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> is one more than the highest numbered pair that has been | |
| set. For example, if two substrings have been captured, the returned value is | |
| 3. If there are no captured substrings, the return value from a successful | |
| match is 1, indicating that just the first pair of offsets has been set.</p> | |
| <p>If a pattern uses the <code class="regex rouge"><span class="pcre2-semantic">\K</span></code> escape sequence within a positive lookahead assertion, | |
| the reported start of a successful match can be greater than the end of the | |
| match. For example, if the pattern <code class="regex rouge"><span class="pcre2-semantic">(?=ab\K)</span></code> is matched against <code class="subject rouge"><span class="pcre2-semantic">ab</span></code>, the start | |
| and end offset values for the match are 2 and 0.</p> | |
| <p>If a capture group is matched repeatedly within a single match operation, it is | |
| the last portion of the subject that it matched that is returned.</p> | |
| <p>If the ovector is too small to hold all the captured substring offsets, as much | |
| as possible is filled in, and the function returns a value of zero. If captured | |
| substrings are not of interest, <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> may be called with a match | |
| data block whose ovector is of minimum length (that is, one pair).</p> | |
| <p>It is possible for capture group number <em>n+1</em> to match some part of the | |
| subject when group <em>n</em> has not been used at all. For example, if the string | |
| <code class="subject rouge"><span class="pcre2-semantic">abc</span></code> is matched against the pattern <code class="regex rouge"><span class="pcre2-semantic">(a|(z))(bc)</span></code> the return from the function | |
| is 4, and groups 1 and 3 are matched, but 2 is not. When this happens, both | |
| values in the offset pairs corresponding to unused groups are set to | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_UNSET</span></code>.</p> | |
| <p>Offset values that correspond to unused groups at the end of the expression are | |
| also set to <code class="constant pcre2-api rouge"><span class="no">PCRE2_UNSET</span></code>. For example, if the string <code class="subject rouge"><span class="pcre2-semantic">abc</span></code> is matched against | |
| the pattern <code class="regex rouge"><span class="pcre2-semantic">(abc)(x(yz)?)?</span></code> groups 2 and 3 are not matched. The return from the | |
| function is 2, because the highest used capture group number is 1. The offsets | |
| for the second and third capture groups (assuming the vector is large enough, | |
| of course) are set to <code class="constant pcre2-api rouge"><span class="no">PCRE2_UNSET</span></code>.</p> | |
| <p>Elements in the ovector that do not correspond to capturing parentheses in the | |
| pattern are never changed. That is, if a pattern contains <em>n</em> capturing | |
| parentheses, no more than <code class="c rouge" data-lang="c"><span class="nv">ovector</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span></code> to <code class="c rouge" data-lang="c"><span class="nv">ovector</span><span class="p">[</span><span class="mi">2</span><em><span class="nv">n</span></em><span class="o">+</span><span class="mi">1</span><span class="p">]</span></code> are set by | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code>. The other elements retain whatever values they previously | |
| had. After a failed match attempt, the contents of the ovector are unchanged.</p></section> | |
| <section class="doc-section level-1"><h2 id="other-match-information">Other information about a match</h2><div class="listing-block prototype"><pre class="rouge highlight"><code data-lang="c"><span class="kt">PCRE2_SPTR</span> <span class="nf">pcre2_get_mark</span><span class="p">(</span><span class="kt">pcre2_match_data</span> <span class="p">*</span><span class="nv">match_data</span><span class="p">);</span> | |
| <span class="kt">PCRE2_SIZE</span> <span class="nf">pcre2_get_startchar</span><span class="p">(</span><span class="kt">pcre2_match_data</span> <span class="p">*</span><span class="nv">match_data</span><span class="p">);</span> | |
| <span class="kt">PCRE2_SPTR</span> <span class="nf">pcre2_get_subject</span><span class="p">(</span><span class="kt">pcre2_match_data</span> <span class="p">*</span><span class="nv">match_data</span><span class="p">,</span> | |
| <span class="kt">PCRE2_SIZE</span> <span class="p">*</span><span class="nv">lengthptr</span><span class="p">);</span></code></pre></div> | |
| <p>As well as the offsets in the ovector, other information about a match is | |
| retained in the match data block and can be retrieved by the above functions in | |
| appropriate circumstances. If they are called at other times, the result is | |
| undefined.</p> | |
| <p>After a successful match, a partial match (<code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_PARTIAL</span></code>), or a | |
| failure to match (<code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_NOMATCH</span></code>), <code class="function pcre2-api rouge"><span class="nf">pcre2_get_subject()</span></code> returns | |
| the subject pointer that was passed to the matching function. For a successful | |
| match with <code class="constant pcre2-api rouge"><span class="no">PCRE2_COPY_MATCHED_SUBJECT</span></code>, it returns a pointer to a copy of | |
| the subject that is owned by the match data block instead (except for | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_jit_match()</span></code> which ignores <code class="constant pcre2-api rouge"><span class="no">PCRE2_COPY_MATCHED_SUBJECT</span></code>). The copy | |
| is exactly the same length as the subject that was passed to the matching | |
| function and is additionally zero-terminated. The copy is freed when the match | |
| data block is reused for another match or is freed. If there is any match error | |
| other than <code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_NOMATCH</span></code> or <code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_PARTIAL</span></code>, | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_get_subject()</span></code> may return <code class="constant pcre2-api rouge"><span class="kc">NULL</span></code>. If the <code class="parameter pcre2-api rouge"><span class="nv">lengthptr</span></code> argument | |
| is not <code class="constant pcre2-api rouge"><span class="kc">NULL</span></code>, it receives the length in code units of the string which is | |
| returned, excluding the terminating zero (the subject string may contain | |
| embedded NUL characters).</p> | |
| <p>After a successful match, a partial match (<code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_PARTIAL</span></code>), or a failure | |
| to match (<code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_NOMATCH</span></code>), a mark name may be available. The function | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_get_mark()</span></code> can be called to access this name, which can be | |
| specified in the pattern by any of the backtracking control verbs, not just | |
| <code class="regex rouge"><span class="pcre2-semantic">(*MARK)</span></code>. The same function applies to all the verbs. It returns a pointer to | |
| the zero-terminated name, which is within the compiled pattern. If no name is | |
| available, <code class="constant pcre2-api rouge"><span class="kc">NULL</span></code> is returned. The length of the name (excluding the terminating | |
| zero) is stored in the code unit that precedes the name. You should use this | |
| length instead of relying on the terminating zero if the name might contain a | |
| binary zero.</p> | |
| <p>After a successful match, the name that is returned is the last mark name | |
| encountered on the matching path through the pattern. Instances of backtracking | |
| verbs without names do not count. Thus, for example, if the matching path | |
| contains <code class="regex rouge"><span class="pcre2-semantic">(*MARK:A)(*PRUNE)</span></code>, the name <code class="regex rouge"><span class="pcre2-semantic">A</span></code> is returned. After a "no match" or a | |
| partial match, the last encountered name is returned. For example, consider | |
| this pattern:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">^(*MARK:A)((*MARK:B)a|b)c</span></code></pre></div> | |
| <p>When it matches <code class="subject rouge"><span class="pcre2-semantic">bc</span></code>, the returned name is <code class="regex rouge"><span class="pcre2-semantic">A</span></code>. The <code class="regex rouge"><span class="pcre2-semantic">B</span></code> mark is "seen" in the first | |
| branch of the group, but it is not on the matching path. On the other hand, | |
| when this pattern fails to match <code class="subject rouge"><span class="pcre2-semantic">bx</span></code>, the returned name is <code class="regex rouge"><span class="pcre2-semantic">B</span></code>.</p> | |
| <section class="admonition-block warning" role="doc-notice"><h6 class="block-title label-only"><span class="title-label">Warning: </span></h6><p>By default, certain start-of-match optimizations are used to | |
| give a fast "no match" result in some situations. For example, if the anchoring | |
| is removed from the pattern above, there is an initial check for the presence | |
| of <code class="subject rouge"><span class="pcre2-semantic">c</span></code> in the subject before running the matching engine. This check fails for | |
| <code class="subject rouge"><span class="pcre2-semantic">bx</span></code>, causing a match failure without seeing any marks. You can disable the | |
| start-of-match optimizations by setting the <code class="constant pcre2-api rouge"><span class="no">PCRE2_NO_START_OPTIMIZE</span></code> option for | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_compile()</span></code> or by starting the pattern with <code class="regex rouge"><span class="pcre2-semantic">(*NO_START_OPT)</span></code>.</p></section> | |
| <p>After a successful match, a partial match, or one of the invalid UTF errors | |
| (for example, <code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_UTF8_ERR5</span></code>), <code class="function pcre2-api rouge"><span class="nf">pcre2_get_startchar()</span></code> can be | |
| called. After a successful or partial match it returns the code unit offset of | |
| the character at which the match started. For a non-partial match, this can be | |
| different to the value of <code class="c rouge" data-lang="c"><span class="nv">ovector</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span></code> if the pattern contains the <code class="regex rouge"><span class="pcre2-semantic">\K</span></code> | |
| escape sequence. After a partial match, however, this value is always the same | |
| as <code class="c rouge" data-lang="c"><span class="nv">ovector</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span></code> because <code class="regex rouge"><span class="pcre2-semantic">\K</span></code> does not affect the result of a partial match.</p> | |
| <p>After a UTF check failure, <code class="function pcre2-api rouge"><span class="nf">pcre2_get_startchar()</span></code> can be used to obtain | |
| the code unit offset of the invalid UTF character. Details are given in the | |
| <a href="./pcre2unicode.html"><code>pcre2unicode</code></a> | |
| page.</p></section> | |
| <section class="doc-section level-1"><h2 id="_error_returns_from_pcre2_match">Error returns from <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code></h2><p>If <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> fails, it returns a negative number. This can be | |
| converted to a text string by calling the <code class="function pcre2-api rouge"><span class="nf">pcre2_get_error_message()</span></code> | |
| function (see "Obtaining a textual error message" | |
| below). | |
| Negative error codes are also returned by other functions, and are documented | |
| with them. The codes are given names in the header file. If UTF checking is in | |
| force and an invalid UTF subject string is detected, one of a number of | |
| UTF-specific negative error codes is returned. Details are given in the | |
| <a href="./pcre2unicode.html"><code>pcre2unicode</code></a> | |
| page. The following are the other errors that may be returned by | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code>:</p> | |
| <dl class="errors compact" style="--tab-width: 14"><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_NOMATCH</span></code></span></dt><dd>The subject string did not match the pattern.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_PARTIAL</span></code></span></dt><dd>The subject string did not match, but it did match partially. See the | |
| <a href="./pcre2partial.html"><code>pcre2partial</code></a> | |
| documentation for details of partial matching.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_BADMAGIC</span></code></span></dt><dd>PCRE2 stores a 4-byte "magic number" at the start of the compiled code, to | |
| catch the case when it is passed a junk pointer. This is the error that is | |
| returned when the magic number is not present.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_BADMODE</span></code></span></dt><dd>This error is given when a compiled pattern is passed to a function in a | |
| library of a different code unit width, for example, a pattern compiled by | |
| the 8-bit library is passed to a 16-bit or 32-bit library function.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_BADOFFSET</span></code></span></dt><dd>The value of <code class="parameter pcre2-api rouge"><span class="nv">start_offset</span></code> was greater than the length of the subject.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_BADOFFSETLIMIT</span></code></span></dt><dd>A non-default offset limit was set without compiling the pattern with | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_USE_OFFSET_LIMIT</span></code>.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_BADOFFSETLIMITVALUE</span></code></span></dt><dd>The offset limit in the match context was greater than the length of the | |
| subject and was not <code class="constant pcre2-api rouge"><span class="no">PCRE2_UNSET</span></code>.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_BADOPTION</span></code></span></dt><dd>An unrecognized bit was set in the <code class="parameter pcre2-api rouge"><span class="nv">options</span></code> argument.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_BADUTFOFFSET</span></code></span></dt><dd>The UTF code unit sequence that was passed as a subject was checked and found | |
| to be valid (the <code class="constant pcre2-api rouge"><span class="no">PCRE2_NO_UTF_CHECK</span></code> option was not set), but the value of | |
| <code class="parameter pcre2-api rouge"><span class="nv">start_offset</span></code> did not point to the beginning of a UTF character or the end | |
| of the subject.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_CALLOUT</span></code></span></dt><dd>This error is never generated by <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> itself. It is provided for | |
| use by callout functions that want to cause <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> or | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_callout_enumerate()</span></code> to return a distinctive error code. See the | |
| <a href="./pcre2callout.html"><code>pcre2callout</code></a> | |
| documentation for details.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_DEPTHLIMIT</span></code></span></dt><dd>The nested backtracking depth limit was reached.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_HEAPLIMIT</span></code></span></dt><dd>The heap limit was reached.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_INTERNAL</span></code></span></dt><dd>An unexpected internal error has occurred. This error could be caused by a bug | |
| in PCRE2 or by overwriting of the compiled pattern.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_JIT_STACKLIMIT</span></code></span></dt><dd>This error is returned when a pattern that was successfully studied using JIT | |
| is being matched, but the memory available for the just-in-time processing | |
| stack is not large enough. See the | |
| <a href="./pcre2jit.html"><code>pcre2jit</code></a> | |
| documentation for more details.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_MATCHLIMIT</span></code></span></dt><dd>The backtracking match limit was reached.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_NOMEMORY</span></code></span></dt><dd>Heap memory is used to remember backtracking points. This error is given when | |
| the memory allocation function (default or custom) fails. Note that a different | |
| error, <code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_HEAPLIMIT</span></code>, is given if the amount of memory needed exceeds | |
| the heap limit. <code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_NOMEMORY</span></code> is also returned if | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_COPY_MATCHED_SUBJECT</span></code> is set and memory allocation fails.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_NULL</span></code></span></dt><dd>Either the <code class="parameter pcre2-api rouge"><span class="nv">code</span></code>, <code class="parameter pcre2-api rouge"><span class="nv">subject</span></code>, or <code class="parameter pcre2-api rouge"><span class="nv">match_data</span></code> argument was passed | |
| as <code class="constant pcre2-api rouge"><span class="kc">NULL</span></code>.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_RECURSELOOP</span></code></span></dt><dd>This error is returned when <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> detects a recursion loop within | |
| the pattern. Specifically, it means that either the whole pattern or a | |
| capture group has been called recursively for the second time at the same | |
| position in the subject string. Some simple patterns that might do this are | |
| detected and faulted at compile time, but more complicated cases, in particular | |
| mutual recursions between two different groups, cannot be detected until | |
| matching is attempted.</dd></div></dl></section> | |
| <section class="doc-section level-1"><h2 id="_obtaining_a_textual_error_message">Obtaining a textual error message</h2><div class="listing-block prototype"><pre class="rouge highlight"><code data-lang="c"><span class="kt">int</span> <span class="nf">pcre2_get_error_message</span><span class="p">(</span><span class="kt">int</span> <span class="nv">errorcode</span><span class="p">,</span> <span class="kt">PCRE2_UCHAR</span> <span class="p">*</span><span class="nv">buffer</span><span class="p">,</span> | |
| <span class="kt">PCRE2_SIZE</span> <span class="nv">bufflen</span><span class="p">);</span></code></pre></div> | |
| <p>A text message for an error code from any PCRE2 function (compile, match, or | |
| auxiliary) can be obtained by calling <code class="function pcre2-api rouge"><span class="nf">pcre2_get_error_message()</span></code>. The code | |
| is passed as the first argument, with the remaining two arguments specifying a | |
| code unit buffer and its length in code units, into which the text message is | |
| placed. The message is returned in code units of the appropriate width for the | |
| library that is being used. An error code of zero is also recognized.</p> | |
| <p>The returned message is terminated with a trailing zero, and the function | |
| returns the number of code units used, excluding the trailing zero. If the | |
| error number is unknown, the negative error code <code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_BADDATA</span></code> is | |
| returned without changing the buffer, even when <code class="parameter pcre2-api rouge"><span class="nv">bufflen</span></code> is zero. | |
| If the buffer is too small, the message is truncated (but still with | |
| a trailing zero, assuming <code class="parameter pcre2-api rouge"><span class="nv">bufflen</span></code> is not zero), and the negative error code | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_NOMEMORY</span></code> is returned. | |
| With a recognized code and zero capacity, no output is written. The buffer | |
| pointer may be <code class="constant pcre2-api rouge"><span class="kc">NULL</span></code> only when its capacity is zero. | |
| None of the messages is very long; a buffer size of 120 code units is ample.</p> | |
| <p>No arithmetic (including unary negation) should ever be performed on error codes | |
| by clients. For any PCRE2 function that returns error codes, that code should be | |
| handled as-is.</p></section> | |
| <section class="doc-section level-1"><h2 id="iterating-over-matches">Iterating over all matches</h2><div class="listing-block prototype"><pre class="rouge highlight"><code data-lang="c"><span class="kt">int</span> <span class="nf">pcre2_next_match</span><span class="p">(</span><span class="kt">pcre2_match_data</span> <span class="p">*</span><span class="nv">match_data</span><span class="p">,</span> | |
| <span class="kt">PCRE2_SIZE</span> <span class="p">*</span><span class="nv">pstart_offset</span><span class="p">,</span> <span class="kt">uint32_t</span> <span class="p">*</span><span class="nv">poptions</span><span class="p">);</span></code></pre></div> | |
| <p>A common task for applications is to implement "global" matching behaviour, | |
| for example, replacing all matches in the subject; splitting the subject on all | |
| matches; or simply counting the number of matches. The <code class="function pcre2-api rouge"><span class="nf">pcre2_next_match()</span></code> | |
| function helps with this task by providing the appropriate parameters for the | |
| next match attempt (available since PCRE2 10.47).</p> | |
| <p>First, a match attempt should be made using one of the matching functions | |
| (<code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code>, <code class="function pcre2-api rouge"><span class="nf">pcre2_dfa_match()</span></code>, or <code class="function pcre2-api rouge"><span class="nf">pcre2_jit_match()</span></code>). | |
| Then, <code class="function pcre2-api rouge"><span class="nf">pcre2_next_match()</span></code> can be called, providing the same | |
| <code class="parameter pcre2-api rouge"><span class="nv">match_data</span></code> parameter.</p> | |
| <p>It returns 0 ("false") if there is no need to make a further match attempt, or | |
| 1 ("true") if another match should be attempted. Returning 1 does not imply that | |
| there is another match, only that another match should be attempted (which may | |
| return <code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_NOMATCH</span></code>).</p> | |
| <p>The <code class="c rouge" data-lang="c"><span class="p">*</span><span class="nv">pstart_offset</span></code> and <code class="c rouge" data-lang="c"><span class="p">*</span><span class="nv">poptions</span></code> are set if the function returns 1. | |
| The <code class="c rouge" data-lang="c"><span class="p">*</span><span class="nv">pstart_offset</span></code> should be passed to the next match attempt directly, | |
| and the <code class="c rouge" data-lang="c"><span class="p">*</span><span class="nv">poptions</span></code> should be passed to the next match attempt by combining | |
| with the application’s match options using OR.</p> | |
| <p>There is some code that demonstrates how to do this in the | |
| <a href="./pcre2demo.html"><code>pcre2demo</code></a> | |
| sample program. The general pattern is:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="c"><span class="kt">uint32_t</span> <span class="nv">app_options</span> <span class="o">=</span> <span class="p">...;</span> | |
| <span class="kt">uint32_t</span> <span class="nv">global_options</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> | |
| <span class="kt">PCRE2_SIZE</span> <span class="nv">start_offset</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> | |
| <span class="k">while</span> <span class="p">(</span><span class="mi">1</span><span class="p">)</span> | |
| <span class="p">{</span> | |
| <span class="kt">int</span> <span class="nv">rc</span> <span class="o">=</span> <span class="nf">pcre2_match</span><span class="p">(</span><span class="nv">re</span><span class="p">,</span> <span class="nv">subject</span><span class="p">,</span> <span class="nv">subject_len</span><span class="p">,</span> <span class="nv">start_offset</span><span class="p">,</span> | |
| <span class="nv">app_options</span> <span class="o">|</span> <span class="nv">global_options</span><span class="p">,</span> <span class="nv">match_data</span><span class="p">,</span> | |
| <span class="nv">match_context</span><span class="p">);</span> | |
| <span class="k">if</span> <span class="p">(</span><span class="nv">rc</span> <span class="o">==</span> <span class="no">PCRE2_ERROR_NOMATCH</span><span class="p">)</span> | |
| <span class="k">break</span><span class="p">;</span> <span class="cm">/* no match, and no more attempts */</span> | |
| <span class="k">if</span> <span class="p">(</span><span class="nv">rc</span> <span class="o"><</span> <span class="mi">0</span><span class="p">)</span> | |
| <span class="p">{</span> <span class="cm">/* ... exit */</span> <span class="p">}</span> | |
| <span class="cm">/* ...handle the match */</span> | |
| <span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="nf">pcre2_next_match</span><span class="p">(</span><span class="nv">match_data</span><span class="p">,</span> <span class="p">&</span><span class="nv">start_offset</span><span class="p">,</span> <span class="p">&</span><span class="nv">global_options</span><span class="p">))</span> | |
| <span class="k">break</span><span class="p">;</span> <span class="cm">/* no more attempts */</span> | |
| <span class="p">}</span></code></pre></div> | |
| <p>The guarantees provided by <code class="function pcre2-api rouge"><span class="nf">pcre2_next_match()</span></code> are that the <code class="parameter pcre2-api rouge"><span class="nv">start_offset</span></code> | |
| will advance, so the loop will definitely terminate. The conditions which | |
| ensure this are that either:</p> | |
| <ol class="loweralpha compact" type="a"><li><code class="function pcre2-api rouge"><span class="nf">pcre2_next_match()</span></code> returns 0 (false); or</li><li>the returned <code class="c rouge" data-lang="c"><span class="p">*</span><span class="nv">pstart_offset</span></code> is strictly greater than the previous | |
| <code class="c rouge" data-lang="c"><span class="nv">start_offset</span></code>; or</li><li>if the previous match was a successful match of the empty string, the returned | |
| <code class="c rouge" data-lang="c"><span class="p">*</span><span class="nv">pstart_offset</span></code> is equal to the previous <code class="c rouge" data-lang="c"><span class="nv">ovector</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span></code>, and <code class="c rouge" data-lang="c"><span class="p">*</span><span class="nv">poptions</span></code> | |
| will be set to <code class="constant pcre2-api rouge"><span class="no">PCRE2_NOTEMPTY_ATSTART</span></code> to prevent another empty match from | |
| being returned.</li></ol> | |
| <p>A loop implemented as shown above will always terminate, unless there is a bug | |
| in PCRE2. As a measure of "defensive programming", applications are encouraged | |
| to add an assertion or check to break their loop if it does not make progress | |
| (and report the issue as a bug).</p> | |
| <p>If an application does not use the flag <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_ALLOW_LOOKAROUND_BSK</span></code>, then | |
| each match is "well-behaved" and satisfies:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="c"><span class="nv">start_offset</span> <span class="o"><=</span> <span class="nv">ovector</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="o"><=</span> <span class="nv">ovector</span><span class="p">[</span><span class="mi">1</span><span class="p">].</span></code></pre></div> | |
| <p>In this case, the matches found by <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> with <code class="function pcre2-api rouge"><span class="nf">pcre2_next_match()</span></code> will be | |
| sorted, non-overlapping (possibly touching), and with no duplicates.</p> | |
| <p>Otherwise, if <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_ALLOW_LOOKAROUND_BSK</span></code> is used, then the guarantees are | |
| considerably weaker. We do not guarantee that the matches will always advance: | |
| only that the <code class="parameter pcre2-api rouge"><span class="nv">start_offset</span></code> will. The matches found by <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> with | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_next_match()</span></code> will be a finite sequence (as <code class="function pcre2-api rouge"><span class="nf">pcre2_next_match()</span></code> ensures that | |
| <code class="parameter pcre2-api rouge"><span class="nv">start_offset</span></code> advances, so the search will terminate). The matches can however be | |
| overlapping, can contain duplicates, and (in truly pathological examples) may | |
| not even be sorted by <code class="c rouge" data-lang="c"><span class="nv">ovector</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span></code>. Additionally, each match itself can end before | |
| it starts (<code class="c rouge" data-lang="c"><span class="nv">ovector</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span> <span class="o"><</span> <span class="nv">ovector</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span></code>). We recommend that applications do not set | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_ALLOW_LOOKAROUND_BSK</span></code>.</p></section> | |
| <section class="doc-section level-1"><h2 id="_extracting_captured_substrings_by_number">Extracting captured substrings by number</h2><div class="listing-block prototype"><pre class="rouge highlight"><code data-lang="c"><span class="kt">int</span> <span class="nf">pcre2_substring_length_bynumber</span><span class="p">(</span><span class="kt">pcre2_match_data</span> <span class="p">*</span><span class="nv">match_data</span><span class="p">,</span> | |
| <span class="kt">uint32_t</span> <span class="nv">stringnumber</span><span class="p">,</span> | |
| <span class="kt">PCRE2_SIZE</span> <span class="p">*</span><span class="nv">sizeptr</span><span class="p">);</span> | |
| <span class="kt">int</span> <span class="nf">pcre2_substring_copy_bynumber</span><span class="p">(</span><span class="kt">pcre2_match_data</span> <span class="p">*</span><span class="nv">match_data</span><span class="p">,</span> | |
| <span class="kt">uint32_t</span> <span class="nv">stringnumber</span><span class="p">,</span> | |
| <span class="kt">PCRE2_UCHAR</span> <span class="p">*</span><span class="nv">buffer</span><span class="p">,</span> | |
| <span class="kt">PCRE2_SIZE</span> <span class="p">*</span><span class="nv">sizeptr</span><span class="p">);</span> | |
| <span class="kt">int</span> <span class="nf">pcre2_substring_get_bynumber</span><span class="p">(</span><span class="kt">pcre2_match_data</span> <span class="p">*</span><span class="nv">match_data</span><span class="p">,</span> | |
| <span class="kt">uint32_t</span> <span class="nv">stringnumber</span><span class="p">,</span> | |
| <span class="kt">PCRE2_UCHAR</span> <span class="p">*</span><span class="p">*</span><span class="nv">stringptr</span><span class="p">,</span> | |
| <span class="kt">PCRE2_SIZE</span> <span class="p">*</span><span class="nv">sizeptr</span><span class="p">);</span> | |
| <span class="kt">void</span> <span class="nf">pcre2_substring_free</span><span class="p">(</span><span class="kt">PCRE2_UCHAR</span> <span class="p">*</span><span class="nv">string</span><span class="p">);</span></code></pre></div> | |
| <p>Captured substrings can be accessed directly by using the ovector as described | |
| above. | |
| For convenience, auxiliary functions are provided for extracting captured | |
| substrings as new, separate, zero-terminated strings. A substring that contains | |
| a binary zero is correctly extracted and has a further zero added on the end, | |
| but the result is not, of course, a C string.</p> | |
| <p>The functions in this section identify substrings by number. The number zero | |
| refers to the entire matched substring, with higher numbers referring to | |
| substrings captured by parenthesized groups. After a partial match, only | |
| substring zero is available. An attempt to extract any other substring gives | |
| the error <code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_PARTIAL</span></code>. The section | |
| <a href="#extracting-substrings-by-name">Extracting a list of all captured substrings</a> describes similar functions for | |
| extracting captured substrings by name.</p> | |
| <p>If a pattern uses the <code class="regex rouge"><span class="pcre2-semantic">\K</span></code> escape sequence within a positive lookahead assertion, | |
| the reported start of a successful match can be greater than the end of the | |
| match. For example, if the pattern <code class="regex rouge"><span class="pcre2-semantic">(?=ab\K)</span></code> is matched against <code class="subject rouge"><span class="pcre2-semantic">ab</span></code>, the start | |
| and end offset values for the match are 2 and 0. In this situation, calling | |
| these functions with a zero substring number extracts a zero-length empty | |
| string.</p> | |
| <p>You can find the length in code units of a captured substring without | |
| extracting it by calling <code class="function pcre2-api rouge"><span class="nf">pcre2_substring_length_bynumber()</span></code>. The first | |
| argument is a pointer to the match data block, the second is the group number, | |
| and the third is a pointer to a variable into which the length is placed. If | |
| you just want to know whether or not the substring has been captured, you can | |
| pass the third argument as <code class="constant pcre2-api rouge"><span class="kc">NULL</span></code>.</p> | |
| <p>The <code class="function pcre2-api rouge"><span class="nf">pcre2_substring_copy_bynumber()</span></code> function copies a captured substring | |
| into a supplied buffer, whereas <code class="function pcre2-api rouge"><span class="nf">pcre2_substring_get_bynumber()</span></code> copies it | |
| into new memory, obtained using the same memory allocation function that was | |
| used for the match data block. The first two arguments of these functions are a | |
| pointer to the match data block and a capture group number.</p> | |
| <p>The final arguments of <code class="function pcre2-api rouge"><span class="nf">pcre2_substring_copy_bynumber()</span></code> are a pointer to | |
| the buffer and a pointer to a variable that contains its length in code units. | |
| This is updated to contain the actual number of code units used for the | |
| extracted substring, excluding the terminating zero.</p> | |
| <p>For <code class="function pcre2-api rouge"><span class="nf">pcre2_substring_get_bynumber()</span></code> the third and fourth arguments point | |
| to variables that are updated with a pointer to the new memory and the number | |
| of code units that comprise the substring, again excluding the terminating | |
| zero. When the substring is no longer needed, the memory should be freed by | |
| calling <code class="function pcre2-api rouge"><span class="nf">pcre2_substring_free()</span></code>.</p> | |
| <p>The return value from all these functions is zero for success, or a negative | |
| error code. If the pattern match failed, the match failure code is returned. | |
| If a substring number greater than zero is used after a partial match, | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_PARTIAL</span></code> is returned. Other possible error codes are:</p> | |
| <dl class="compact" style="--tab-width: 14"><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_NOMEMORY</span></code></span></dt><dd>The buffer was too small for <code class="function pcre2-api rouge"><span class="nf">pcre2_substring_copy_bynumber()</span></code>, or the | |
| attempt to get memory failed for <code class="function pcre2-api rouge"><span class="nf">pcre2_substring_get_bynumber()</span></code>.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_NOSUBSTRING</span></code></span></dt><dd>There is no substring with that number in the pattern, that is, the number is | |
| greater than the number of capturing parentheses.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_UNAVAILABLE</span></code></span></dt><dd>The substring number, though not greater than the number of captures in the | |
| pattern, is greater than the number of slots in the ovector, so the substring | |
| could not be captured.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_UNSET</span></code></span></dt><dd>The substring did not participate in the match. For example, if the pattern is | |
| <code class="regex rouge"><span class="pcre2-semantic">(abc)|(def)</span></code> and the subject is <code class="subject rouge"><span class="pcre2-semantic">def</span></code>, and the ovector contains at least two | |
| capturing slots, substring number 1 is unset.</dd></div></dl></section> | |
| <section class="doc-section level-1"><h2 id="extracting-substrings-by-name">Extracting a list of all captured substrings</h2><div class="listing-block prototype"><pre class="rouge highlight"><code data-lang="c"><span class="kt">int</span> <span class="nf">pcre2_substring_list_get</span><span class="p">(</span><span class="kt">pcre2_match_data</span> <span class="p">*</span><span class="nv">match_data</span><span class="p">,</span> | |
| <span class="kt">PCRE2_UCHAR</span> <span class="p">*</span><span class="p">*</span><span class="p">*</span><span class="nv">listptr</span><span class="p">,</span> | |
| <span class="kt">PCRE2_SIZE</span> <span class="p">*</span><span class="p">*</span><span class="nv">lengthsptr</span><span class="p">);</span> | |
| <span class="kt">void</span> <span class="nf">pcre2_substring_list_free</span><span class="p">(</span><span class="kt">PCRE2_UCHAR</span> <span class="p">*</span><span class="p">*</span><span class="nv">list</span><span class="p">);</span></code></pre></div> | |
| <p>The <code class="function pcre2-api rouge"><span class="nf">pcre2_substring_list_get()</span></code> function extracts all available substrings | |
| and builds a list of pointers to them. It also (optionally) builds a second | |
| list that contains their lengths (in code units), excluding a terminating zero | |
| that is added to each of them. All this is done in a single block of memory | |
| that is obtained using the same memory allocation function that was used to get | |
| the match data block.</p> | |
| <p>This function must be called only after a successful match. If called after a | |
| partial match, the error code <code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_PARTIAL</span></code> is returned.</p> | |
| <p>The address of the memory block is returned via <code class="parameter pcre2-api rouge"><span class="nv">listptr</span></code>, which is also | |
| the start of the list of string pointers. The end of the list is marked by a | |
| <code class="constant pcre2-api rouge"><span class="kc">NULL</span></code> pointer. The address of the list of lengths is returned via | |
| <code class="parameter pcre2-api rouge"><span class="nv">lengthsptr</span></code>. If your strings do not contain binary zeros and you do not | |
| therefore need the lengths, you may supply <code class="constant pcre2-api rouge"><span class="kc">NULL</span></code> as the <code class="parameter pcre2-api rouge"><span class="nv">lengthsptr</span></code> | |
| argument to disable the creation of a list of lengths. The yield of the | |
| function is zero if all went well, or <code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_NOMEMORY</span></code> if the memory block | |
| could not be obtained. When the list is no longer needed, it should be freed by | |
| calling <code class="function pcre2-api rouge"><span class="nf">pcre2_substring_list_free()</span></code>.</p> | |
| <p>If this function encounters a substring that is unset, which can happen when | |
| capture group number <em>n+1</em> matches some part of the subject, but group | |
| <em>n</em> has not been used at all, it returns an empty string. This can be | |
| distinguished from a genuine zero-length substring by inspecting the | |
| appropriate offset in the <code class="parameter pcre2-api rouge"><span class="nv">ovector</span></code>, which contain <code class="constant pcre2-api rouge"><span class="no">PCRE2_UNSET</span></code> for unset | |
| substrings, or by calling <code class="function pcre2-api rouge"><span class="nf">pcre2_substring_length_bynumber()</span></code>.</p></section> | |
| <section class="doc-section level-1"><h2 id="_extracting_captured_substrings_by_name">Extracting captured substrings by name</h2><div class="listing-block prototype"><pre class="rouge highlight"><code data-lang="c"><span class="kt">int</span> <span class="nf">pcre2_substring_number_from_name</span><span class="p">(</span><span class="kt">const</span> <span class="kt">pcre2_code</span> <span class="p">*</span><span class="nv">code</span><span class="p">,</span> | |
| <span class="kt">PCRE2_SPTR</span> <span class="nv">stringname</span><span class="p">);</span> | |
| <span class="kt">int</span> <span class="nf">pcre2_substring_length_byname</span><span class="p">(</span><span class="kt">pcre2_match_data</span> <span class="p">*</span><span class="nv">match_data</span><span class="p">,</span> | |
| <span class="kt">PCRE2_SPTR</span> <span class="nv">stringname</span><span class="p">,</span> | |
| <span class="kt">PCRE2_SIZE</span> <span class="p">*</span><span class="nv">sizeptr</span><span class="p">);</span> | |
| <span class="kt">int</span> <span class="nf">pcre2_substring_copy_byname</span><span class="p">(</span><span class="kt">pcre2_match_data</span> <span class="p">*</span><span class="nv">match_data</span><span class="p">,</span> | |
| <span class="kt">PCRE2_SPTR</span> <span class="nv">stringname</span><span class="p">,</span> | |
| <span class="kt">PCRE2_UCHAR</span> <span class="p">*</span><span class="nv">buffer</span><span class="p">,</span> | |
| <span class="kt">PCRE2_SIZE</span> <span class="p">*</span><span class="nv">sizeptr</span><span class="p">);</span> | |
| <span class="kt">int</span> <span class="nf">pcre2_substring_get_byname</span><span class="p">(</span><span class="kt">pcre2_match_data</span> <span class="p">*</span><span class="nv">match_data</span><span class="p">,</span> | |
| <span class="kt">PCRE2_SPTR</span> <span class="nv">stringname</span><span class="p">,</span> | |
| <span class="kt">PCRE2_UCHAR</span> <span class="p">*</span><span class="p">*</span><span class="nv">stringptr</span><span class="p">,</span> | |
| <span class="kt">PCRE2_SIZE</span> <span class="p">*</span><span class="nv">sizeptr</span><span class="p">);</span> | |
| <span class="kt">void</span> <span class="nf">pcre2_substring_free</span><span class="p">(</span><span class="kt">PCRE2_UCHAR</span> <span class="p">*</span><span class="nv">string</span><span class="p">);</span></code></pre></div> | |
| <p>To extract a substring by name, you first have to find associated number. | |
| For example, for this pattern:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(a+)b(?<xxx>\d+)...</span></code></pre></div> | |
| <p>the number of the capture group called "xxx" is 2. If the name is known to be | |
| unique (<code class="constant pcre2-api rouge"><span class="no">PCRE2_DUPNAMES</span></code> was not set), you can find the number from the name by | |
| calling <code class="function pcre2-api rouge"><span class="nf">pcre2_substring_number_from_name()</span></code>. The first argument is the | |
| compiled pattern, and the second is the name. The yield of the function is the | |
| group number, <code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_NOSUBSTRING</span></code> if there is no group with that name, or | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_NOUNIQUESUBSTRING</span></code> if there is more than one group with that name. | |
| Given the number, you can extract the substring directly from the ovector, or | |
| use one of the "bynumber" functions described above.</p> | |
| <p>For convenience, there are also "byname" functions that correspond to the | |
| "bynumber" functions, the only difference being that the second argument is a | |
| name instead of a number. If <code class="constant pcre2-api rouge"><span class="no">PCRE2_DUPNAMES</span></code> is set and there are duplicate | |
| names, these functions scan all the groups with the given name, and return the | |
| captured substring from the first named group that is set.</p> | |
| <p>If there are no groups with the given name, <code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_NOSUBSTRING</span></code> is | |
| returned. If all groups with the name have numbers that are greater than the | |
| number of slots in the ovector, <code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_UNAVAILABLE</span></code> is returned. If there | |
| is at least one group with a slot in the ovector, but no group is found to be | |
| set, <code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_UNSET</span></code> is returned.</p> | |
| <section class="admonition-block warning" role="doc-notice"><h6 class="block-title label-only"><span class="title-label">Warning: </span></h6><p>If the pattern uses the <code class="regex rouge"><span class="pcre2-semantic">(?|</span></code> feature to set up multiple | |
| capture groups with the same number, as described in the | |
| section <a href="./pcre2pattern.html#duplicate-group-numbers">Duplicate group numbers</a> | |
| in the | |
| <a href="./pcre2pattern.html"><code>pcre2pattern</code></a> | |
| page, you cannot use names to distinguish the different capture groups, because | |
| names are not included in the compiled code. The matching process uses only | |
| numbers. For this reason, the use of different names for groups with the | |
| same number causes an error at compile time.</p></section></section> | |
| <section class="doc-section level-1"><h2 id="creating-substitution-string">Creating a new string with substitutions</h2><div class="listing-block prototype"><pre class="rouge highlight"><code data-lang="c"><span class="kt">int</span> <span class="nf">pcre2_substitute</span><span class="p">(</span><span class="kt">const</span> <span class="kt">pcre2_code</span> <span class="p">*</span><span class="nv">code</span><span class="p">,</span> <span class="kt">PCRE2_SPTR</span> <span class="nv">subject</span><span class="p">,</span> | |
| <span class="kt">PCRE2_SIZE</span> <span class="nv">length</span><span class="p">,</span> <span class="kt">PCRE2_SIZE</span> <span class="nv">start_offset</span><span class="p">,</span> | |
| <span class="kt">uint32_t</span> <span class="nv">options</span><span class="p">,</span> <span class="kt">pcre2_match_data</span> <span class="p">*</span><span class="nv">match_data</span><span class="p">,</span> | |
| <span class="kt">pcre2_match_context</span> <span class="p">*</span><span class="nv">mcontext</span><span class="p">,</span> | |
| <span class="kt">PCRE2_SPTR</span> <span class="nv">replacement</span><span class="p">,</span> <span class="kt">PCRE2_SIZE</span> <span class="nv">rlength</span><span class="p">,</span> | |
| <span class="kt">PCRE2_UCHAR</span> <span class="p">*</span><span class="nv">buffer</span><span class="p">,</span> <span class="kt">PCRE2_SIZE</span> <span class="p">*</span><span class="nv">blength</span><span class="p">);</span></code></pre></div> | |
| <p>This function optionally calls <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> and then makes a copy of the | |
| subject string in <code class="parameter pcre2-api rouge"><span class="nv">buffer</span></code>, replacing parts that were matched with | |
| the <code class="parameter pcre2-api rouge"><span class="nv">replacement</span></code> string, whose length is supplied in <code class="parameter pcre2-api rouge"><span class="nv">rlength</span></code>, which | |
| can be given as <code class="constant pcre2-api rouge"><span class="no">PCRE2_ZERO_TERMINATED</span></code> for a zero-terminated string. As a | |
| special case, if <code class="parameter pcre2-api rouge"><span class="nv">replacement</span></code> is <code class="constant pcre2-api rouge"><span class="kc">NULL</span></code> and <code class="parameter pcre2-api rouge"><span class="nv">rlength</span></code> is zero, the | |
| replacement is assumed to be an empty string. If <code class="parameter pcre2-api rouge"><span class="nv">rlength</span></code> is non-zero, an | |
| error occurs if <code class="parameter pcre2-api rouge"><span class="nv">replacement</span></code> is <code class="constant pcre2-api rouge"><span class="kc">NULL</span></code>.</p> | |
| <p>There is an option (see <code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_REPLACEMENT_ONLY</span></code> below) to return just | |
| the replacement string(s). The default action is to perform just one | |
| replacement if the pattern matches, but there is an option that requests | |
| multiple replacements (see <code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_GLOBAL</span></code> below).</p> | |
| <p>If successful, <code class="function pcre2-api rouge"><span class="nf">pcre2_substitute()</span></code> returns the number of substitutions | |
| that were carried out. This may be zero if no match was found, and is never | |
| greater than one unless <code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_GLOBAL</span></code> is set. A negative value is | |
| returned if an error is detected.</p> | |
| <p>Matches in which a <code class="regex rouge"><span class="pcre2-semantic">\K</span></code> item in a lookahead in the pattern causes the match to | |
| end before it starts are not supported, and give rise to an error return. For | |
| global replacements, matches in which <code class="regex rouge"><span class="pcre2-semantic">\K</span></code> in a lookbehind causes the match to | |
| start earlier than the point that was reached in the previous iteration are | |
| also not supported. (These cases are only possible if the pattern was compiled | |
| with the backwards-compatibility option <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_ALLOW_LOOKAROUND_BSK</span></code>.)</p> | |
| <p>The first seven arguments of <code class="function pcre2-api rouge"><span class="nf">pcre2_substitute()</span></code> are the same as for | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code>, except that the partial matching options are not | |
| permitted, and <code class="parameter pcre2-api rouge"><span class="nv">match_data</span></code> may be passed as <code class="constant pcre2-api rouge"><span class="kc">NULL</span></code>, in which case a match | |
| data block is obtained and freed within this function, using memory management | |
| functions from the match context, if provided, or else those that were used to | |
| allocate memory for the compiled code.</p> | |
| <p>If <code class="parameter pcre2-api rouge"><span class="nv">match_data</span></code> is not <code class="constant pcre2-api rouge"><span class="kc">NULL</span></code> and <code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_MATCHED</span></code> is not set, the | |
| provided block is used for all calls to <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code>, and its contents | |
| afterwards are the result of the final call made internally by | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_substitute()</span></code> to the matching function. For global changes, this will | |
| always be a no-match error. The contents of the ovector within the match data | |
| block may or may not have been changed.</p> | |
| <p>As well as the usual options for <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code>, a number of additional | |
| options can be set in the <code class="parameter pcre2-api rouge"><span class="nv">options</span></code> argument of <code class="function pcre2-api rouge"><span class="nf">pcre2_substitute()</span></code>. | |
| One such option is <code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_MATCHED</span></code>. When this is set, an external | |
| <code class="parameter pcre2-api rouge"><span class="nv">match_data</span></code> block must be provided, and it must have already been used for | |
| an external call to <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> (or <code class="function pcre2-api rouge"><span class="nf">pcre2_jit_match()</span></code>) with the | |
| same pattern, subject pointer, effective subject length, start offset, and match | |
| option arguments (substitute-specific options can be added to the <code class="parameter pcre2-api rouge"><span class="nv">options</span></code> | |
| argument). If any of these parameters is changed, <code class="function pcre2-api rouge"><span class="nf">pcre2_substitute()</span></code> | |
| returns an error. The data in the <code class="parameter pcre2-api rouge"><span class="nv">match_data</span></code> block (return code, offset | |
| vector) is used for the first substitution instead of calling | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> from within <code class="function pcre2-api rouge"><span class="nf">pcre2_substitute()</span></code>. This allows an | |
| application to check for a match before choosing to substitute, without having | |
| to repeat the match.</p> | |
| <p>If the contents of the subject buffer are mutated in between <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> | |
| and a call to <code class="function pcre2-api rouge"><span class="nf">pcre2_substitute()</span></code> with <code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_MATCHED</span></code>, the | |
| behaviour is unsafe; in particular, in this case, PCRE2 is unable to ensure that | |
| the offsets in the ovector point to the start of characters (with UTF-encoded | |
| input).</p> | |
| <p>The contents of the externally supplied match data block are not changed when | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_MATCHED</span></code> is set, and so the match block is permitted for use in | |
| another call using <code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_MATCHED</span></code>. If <code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_GLOBAL</span></code> is also | |
| set, <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> is called after the first substitution to check for | |
| furthe matches, but this is done using an internally obtained match data block, | |
| thus always leaving the external block unchanged.</p> | |
| <p>The <code class="parameter pcre2-api rouge"><span class="nv">code</span></code> argument is not used for matching before the first substitution | |
| when <code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_MATCHED</span></code> is set, but it must be provided, even when | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_GLOBAL</span></code> is not set, because it contains information such as the | |
| UTF setting and the number of capturing parentheses in the pattern.</p> | |
| <p>When using <code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_MATCHED</span></code>, you should not modify the subject string | |
| in between the prior call to <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> and <code class="function pcre2-api rouge"><span class="nf">pcre2_substitute()</span></code>, | |
| as the substitution assumes that the passed-in ovector is compatible with the | |
| subject string. Although PCRE2 does verify that the subject is a pointer to the | |
| same buffer, it cannot in general verify whether the contents of the buffer have | |
| changed. For example, if the subject buffer is mutated from one valid UTF-8 | |
| string to another valid string, of the same length in code units, the ovector | |
| offsets are no longer guaranteed to point to the start of a character. Beware | |
| that with <code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_MATCHED</span></code> in UTF mode, the subject string is not | |
| re-scanned for UTF validity when <code class="function pcre2-api rouge"><span class="nf">pcre2_substitute()</span></code> first uses it.</p> | |
| <p>The default action of <code class="function pcre2-api rouge"><span class="nf">pcre2_substitute()</span></code> is to return a copy of the | |
| subject string with matched substrings replaced. However, if | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_REPLACEMENT_ONLY</span></code> is set, only the replacement substrings are | |
| returned. In the global case, multiple replacements are concatenated in the | |
| output buffer. Substitution callouts (see | |
| below) | |
| can be used to separate them if necessary.</p> | |
| <p>Partial matching is supported, with limitations: if matching succeeds but with a | |
| partial match, then <code class="function pcre2-api rouge"><span class="nf">pcre2_substitute()</span></code> returns <code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_PARTIAL</span></code>. When | |
| partial-matching (either of <code class="constant pcre2-api rouge"><span class="no">PCRE2_PARTIAL_HARD</span></code> or <code class="constant pcre2-api rouge"><span class="no">PCRE2_PARTIAL_SOFT</span></code> is passed), | |
| then <code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_REPLACEMENT_ONLY</span></code> must also be set, or else | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_BADOPTION</span></code> is returned. Similarly, certain replacement items | |
| (<code class="repl rouge"><span class="pcre2-semantic">$'</span></code> and <code class="repl rouge"><span class="pcre2-semantic">$_</span></code>) cause <code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_PARTIALSUBS</span></code> to be returned when partial-matching, | |
| even if a complete match is found.</p> | |
| <p>The <code class="parameter pcre2-api rouge"><span class="nv">blength</span></code> argument of <code class="function pcre2-api rouge"><span class="nf">pcre2_substitute()</span></code> must point to a | |
| variable that contains the length, in code units, of the output buffer. If the | |
| function is successful, the value is updated to contain the length in code | |
| units of the new string, excluding the trailing zero that is automatically | |
| added.</p> | |
| <p>If the function is not successful, the value set via <code class="parameter pcre2-api rouge"><span class="nv">blength</span></code> depends | |
| on the type of error. For syntax errors in the replacement string, the value is | |
| the offset in the replacement string where the error was detected. For other | |
| errors, the value is <code class="constant pcre2-api rouge"><span class="no">PCRE2_UNSET</span></code> by default. This includes the case of the | |
| output buffer being too small, unless <code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_OVERFLOW_LENGTH</span></code> is set.</p> | |
| <p><code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_OVERFLOW_LENGTH</span></code> changes what happens when the output buffer is | |
| too small. The default action is to return <code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_NOMEMORY</span></code> immediately. If | |
| this option is set, however, <code class="function pcre2-api rouge"><span class="nf">pcre2_substitute()</span></code> continues to go through | |
| the motions of matching and substituting (without, of course, writing anything) | |
| in order to compute the size of buffer that is needed, which will include the | |
| extra space for the terminating NUL. This value is passed back via the | |
| <code class="parameter pcre2-api rouge"><span class="nv">blength</span></code> variable, with the result of the function still being | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_NOMEMORY</span></code>.</p> | |
| <p>Passing a buffer size of zero (with <code class="parameter pcre2-api rouge"><span class="nv">buffer</span></code> optionally <code class="constant pcre2-api rouge"><span class="kc">NULL</span></code>) is a | |
| permitted way of finding out how much memory is needed for given substitution. | |
| However, this does mean that the entire operation is carried out twice. | |
| Depending on the application, it may be more efficient to allocate a large | |
| buffer and free the excess afterwards, instead of using | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_OVERFLOW_LENGTH</span></code>.</p> | |
| <p>The replacement string, which is interpreted as a UTF string in UTF mode, is | |
| checked for UTF validity unless <code class="constant pcre2-api rouge"><span class="no">PCRE2_NO_UTF_CHECK</span></code> is set. An invalid UTF | |
| replacement string causes an immediate return with the relevant UTF error code.</p> | |
| <p>If <code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_LITERAL</span></code> is set, the replacement string is not interpreted | |
| in any way. By default, however, a dollar character is an escape character that | |
| can specify the insertion of characters from capture groups and names from | |
| <code class="regex rouge"><span class="pcre2-semantic">(*MARK)</span></code> or other control verbs in the pattern. Dollar is the only escape | |
| character (backslash is treated as literal). The following forms are | |
| recognized:</p> | |
| <dl class="compact" style="--tab-width: 10"><div class="dlist-item"><dt><span><code class="repl rouge"><span class="pcre2-semantic">$$</span></code></span></dt><dd>Insert a dollar character</dd></div><div class="dlist-item"><dt><span><code class="repl rouge"><span class="pcre2-semantic">$<em>n</em></span></code> or <code class="repl rouge"><span class="pcre2-semantic">${<em>n</em>}</span></code></span></dt><dd>Insert the contents of group <em>n</em></dd></div><div class="dlist-item"><dt><span><code class="repl rouge"><span class="pcre2-semantic">$<<em>name</em>></span></code></span></dt><dd>Insert the contents of named group</dd></div><div class="dlist-item"><dt><span><code class="repl rouge"><span class="pcre2-semantic">$0</span></code> or <code class="repl rouge"><span class="pcre2-semantic">$&</span></code></span></dt><dd>Insert the entire matched substring</dd></div><div class="dlist-item"><dt><span><code class="repl rouge"><span class="pcre2-semantic">$`</span></code></span></dt><dd>Insert the substring that precedes the match</dd></div><div class="dlist-item"><dt><span><code class="repl rouge"><span class="pcre2-semantic">$'</span></code></span></dt><dd>Insert the substring that follows the match</dd></div><div class="dlist-item"><dt><span><code class="repl rouge"><span class="pcre2-semantic">$_</span></code></span></dt><dd>Insert the entire input string</dd></div><div class="dlist-item"><dt><span><code class="repl rouge"><span class="pcre2-semantic">$+</span></code></span></dt><dd>Insert the highest-numbered capture group which matched</dd></div><div class="dlist-item"><dt><span><code class="repl rouge"><span class="pcre2-semantic">$*MARK</span></code> or <code class="repl rouge"><span class="pcre2-semantic">${*MARK}</span></code></span></dt><dd>Insert a control verb name</dd></div></dl> | |
| <p>Either a group number or a group name can be given for <em>n</em>, for example <code class="repl rouge"><span class="pcre2-semantic">$2</span></code> | |
| or <code class="repl rouge"><span class="pcre2-semantic">$NAME</span></code>. Curly brackets are required only if the following character would be | |
| interpreted as part of the number or name. The number may be zero to include | |
| the entire matched string. For example, if the pattern <code class="regex rouge"><span class="pcre2-semantic">a(b)c</span></code> is matched with | |
| <code class="subject rouge"><span class="pcre2-semantic">=abc=</span></code> and the replacement string <code class="repl rouge"><span class="pcre2-semantic">+$1$0$1+</span></code>, the result is <code class="repl rouge"><span class="pcre2-semantic">=+babcb+=</span></code>.</p> | |
| <p>The JavaScript form <code class="repl rouge"><span class="pcre2-semantic">$<<em>name</em>></span></code>, where the angle brackets are part of the syntax, | |
| is also recognized for group names, but not for group numbers or <code class="repl rouge"><span class="pcre2-semantic">*MARK</span></code>.</p> | |
| <p><code class="repl rouge"><span class="pcre2-semantic">$*MARK</span></code> inserts the name from the last encountered backtracking control verb on | |
| the matching path that has a name. <code class="regex rouge"><span class="pcre2-semantic">(*MARK)</span></code> must always include a name, but the | |
| other verbs need not. For example, in the case of <code class="regex rouge"><span class="pcre2-semantic">(*MARK:A)(*PRUNE)</span></code> the name | |
| inserted is <code class="repl rouge"><span class="pcre2-semantic">A</span></code>, but for <code class="regex rouge"><span class="pcre2-semantic">(*MARK:A)(*PRUNE:B)</span></code> the relevant name is <code class="repl rouge"><span class="pcre2-semantic">B</span></code>. This | |
| facility can be used to perform simple simultaneous substitutions, as this | |
| <code>pcre2test</code> example shows:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="text">/(*MARK:pear)apple|(*MARK:orange)lemon/g,replace=${*MARK} | |
| apple lemon | |
| 2: pear orange</code></pre></div> | |
| <p><code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_GLOBAL</span></code> causes the function to iterate over the subject string, | |
| replacing every matching substring. If this option is not set, only the first | |
| matching substring is replaced. The search for matches takes place in the | |
| original subject string (that is, previous replacements do not affect it). | |
| Iteration is implemented by advancing the <code class="parameter pcre2-api rouge"><span class="nv">start_offset</span></code> value for each | |
| search, which is always passed the entire subject string. If an offset limit is | |
| set in the match context, searching stops when that limit is reached.</p> | |
| <p>Because global substitutions apply the pattern repeatedly to the subject string, | |
| and always iterate over non-overlapping matches, the substitutions done by | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_substitute()</span></code> do not match and substitute text inside the replacement | |
| strings themselves (no recursive/iterative substitution). However, applications | |
| can easily implement other alternative replacement strategies, such as | |
| iteratively replacing, then matching and replacing on the result. The | |
| replacement loop inside <code class="function pcre2-api rouge"><span class="nf">pcre2_substitute()</span></code> is simple and can be emulated | |
| in client code by allocating a buffer, searching for matches in a loop, and | |
| calling <code class="function pcre2-api rouge"><span class="nf">pcre2_substitute()</span></code> with <code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_REPLACEMENT_ONLY</span></code> an | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_MATCHED</span></code>, and without <code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_GLOBAL</span></code>.</p> | |
| <p>You can restrict the effect of a global substitution to a portion of the | |
| subject string by setting either or both of <code class="parameter pcre2-api rouge"><span class="nv">start_offset</span></code> and an offset | |
| limit. Here is a <code>pcre2test</code> example:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="text">/B/g,replace=!,use_offset_limit | |
| ABC ABC ABC ABC\=offset=3,offset_limit=12 | |
| 2: ABC A!C A!C ABC</code></pre></div> | |
| <p>When continuing with global substitutions after matching a substring with zero | |
| length, an attempt to find a non-empty match at the same offset is performed. | |
| If this is not successful, the offset is advanced by one character except when | |
| CRLF is a valid newline sequence and the next two characters are CR, LF. In | |
| this case, the offset is advanced by two characters.</p> | |
| <p><code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_UNKNOWN_UNSET</span></code> causes references to capture groups that do | |
| not appear in the pattern to be treated as unset groups. This option should be | |
| used with care, because it means that a typo in a group name or number no | |
| longer causes the <code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_NOSUBSTRING</span></code> error.</p> | |
| <p><code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_UNSET_EMPTY</span></code> causes unset capture groups (including unknown | |
| groups when <code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_UNKNOWN_UNSET</span></code> is set) to be treated as empty | |
| strings when inserted as described above. If this option is not set, an attempt | |
| to insert an unset group causes the <code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_UNSET</span></code> error. This option does | |
| not influence the extended substitution syntax described below.</p> | |
| <p><code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_EXTENDED</span></code> causes extra processing to be applied to the | |
| replacement string. Without this option, only the dollar character is special, | |
| and only the group insertion forms listed above are valid. When | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_EXTENDED</span></code> is set, several things change:</p> | |
| <p>Firstly, backslash in a replacement string is interpreted as an escape | |
| character. The usual forms such as <code class="repl rouge"><span class="pcre2-semantic">\x{<em>ddd</em>}</span></code> can be used to specify particular | |
| character codes, and backslash followed by any non-alphanumeric character | |
| quotes that character. Extended quoting can be coded using <code class="repl rouge"><span class="pcre2-semantic">\Q...\E</span></code>, exactly | |
| as in pattern strings. The escapes <code class="repl rouge"><span class="pcre2-semantic">\b</span></code> and <code class="repl rouge"><span class="pcre2-semantic">\v</span></code> are interpreted as the | |
| characters backspace and vertical tab, respectively.</p> | |
| <p>The interpretation of backslash followed by one or more digits is the same as | |
| in a pattern, which in Perl has some ambiguities. Details are given in the | |
| <a href="./pcre2pattern.html"><code>pcre2pattern</code></a> | |
| page.</p> | |
| <p>The Python form <code class="repl rouge"><span class="pcre2-semantic">\g<<em>n</em>></span></code>, where the angle brackets are part of the syntax and | |
| <em>n</em> is either a group name or number, is recognized as an alternative way | |
| of inserting the contents of a group, for example <code class="repl rouge"><span class="pcre2-semantic">\g<3></span></code>.</p> | |
| <p>There are also four escape sequences for forcing the case of inserted letters. | |
| Case forcing applies to all inserted characters, including those from capture | |
| groups and letters within <code class="repl rouge"><span class="pcre2-semantic">\Q...\E</span></code> quoted sequences. The insertion mechanism | |
| has three states: no case forcing, force upper case, and force lower case. The | |
| escape sequences change the current state: <code class="repl rouge"><span class="pcre2-semantic">\U</span></code> and <code class="repl rouge"><span class="pcre2-semantic">\L</span></code> change to upper or lower | |
| case forcing, respectively, and <code class="repl rouge"><span class="pcre2-semantic">\E</span></code> (when not terminating a <code class="repl rouge"><span class="pcre2-semantic">\Q</span></code> quoted | |
| sequence) reverts to no case forcing. The sequences <code class="repl rouge"><span class="pcre2-semantic">\u</span></code> and <code class="repl rouge"><span class="pcre2-semantic">\l</span></code> force the next | |
| character (if it is a letter) to upper or lower case, respectively, and then | |
| the state automatically reverts to no case forcing.</p> | |
| <p>However, if <code class="repl rouge"><span class="pcre2-semantic">\u</span></code> is immediately followed by <code class="repl rouge"><span class="pcre2-semantic">\L</span></code> or <code class="repl rouge"><span class="pcre2-semantic">\l</span></code> is immediately followed | |
| by <code class="repl rouge"><span class="pcre2-semantic">\U</span></code>, the next character’s case is forced by the first escape sequence, and | |
| subsequent characters by the second. This provides a "title casing" facility | |
| that can be applied to group captures. For example, if group 1 has captured | |
| <code class="subject rouge"><span class="pcre2-semantic">heLLo</span></code>, the replacement string <code class="repl rouge"><span class="pcre2-semantic">\u\L$1</span></code> becomes <code class="repl rouge"><span class="pcre2-semantic">Hello</span></code>.</p> | |
| <p>If either <code class="constant pcre2-api rouge"><span class="no">PCRE2_UTF</span></code> or <code class="constant pcre2-api rouge"><span class="no">PCRE2_UCP</span></code> was set when the pattern was compiled, Unicode | |
| properties are used for case forcing characters whose code points are greater | |
| than 127. However, only simple case folding, as determined by the Unicode file | |
| <code>CaseFolding.txt</code> is supported. PCRE2 does not support language-specific | |
| special casing rules such as using different lower case Greek sigmas in the | |
| middle and ends of words (as defined in the Unicode file | |
| <code>SpecialCasing.txt</code>).</p> | |
| <p>Note that case forcing sequences such as <code class="repl rouge"><span class="pcre2-semantic">\U...\E</span></code> do not nest. For example, | |
| the result of processing <code class="repl rouge"><span class="pcre2-semantic">\Uaa\LBB\Ecc\E</span></code> is <code class="repl rouge"><span class="pcre2-semantic">AAbbcc</span></code>; the final <code class="repl rouge"><span class="pcre2-semantic">\E</span></code> has no | |
| effect. Note also that the <code class="constant pcre2-api rouge"><span class="no">PCRE2_ALT_BSUX</span></code> and <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_ALT_BSUX</span></code> options do | |
| not apply to replacement strings.</p> | |
| <p>The final effect of setting <code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_EXTENDED</span></code> is to add more | |
| flexibility to capture group substitution. The syntax is similar to that used | |
| by Bash:</p> | |
| <dl class="compact" style="--tab-width: 4"><div class="dlist-item"><dt><span><code class="repl rouge"><span class="pcre2-semantic">${<em>n</em>:-<em>string</em>}</span></code> </span></dt><dd>insert a default value when group <em>n</em> is unset</dd></div><div class="dlist-item"><dt><span><code class="repl rouge"><span class="pcre2-semantic">${<em>n</em>:+<em>string1</em>:<em>string2</em>}</span></code> </span></dt><dd>insert <em>string1</em> when group <em>n</em> is set, otherwise <em>string2</em></dd></div></dl> | |
| <p>As in the simple case, <em>n</em> may be a group number or a name. The first form | |
| specifies a default value. If group <em>n</em> is set, its value is inserted; if | |
| not, the string is expanded and the result inserted. The second form specifies | |
| strings that are expanded and inserted when group <em>n</em> is set or unset, | |
| respectively. The first form is just a convenient shorthand for</p> | |
| <p><code class="repl rouge"><span class="pcre2-semantic">${<em>n</em>:+${<em>n</em>}:<em>string</em>}</span></code></p> | |
| <p>Backslash can be used to escape colons and closing curly brackets in the | |
| replacement strings. A change of the case forcing state within a replacement | |
| string remains in force afterwards, as shown in this <code>pcre2test</code> example:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="text">/(some)?(body)/substitute_extended,replace=${1:+\U:\L}HeLLo | |
| body | |
| 1: hello | |
| somebody | |
| 1: HELLO</code></pre></div> | |
| <p>The <code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_UNSET_EMPTY</span></code> option does not affect these extended | |
| substitutions. However, <code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_UNKNOWN_UNSET</span></code> does cause unknown | |
| groups in the extended syntax forms to be treated as unset.</p> | |
| <p>If <code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_LITERAL</span></code> is set, <code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_UNKNOWN_UNSET</span></code>, | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_UNSET_EMPTY</span></code>, and <code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_EXTENDED</span></code> are irrelevant and | |
| are ignored.</p> | |
| <section class="doc-section level-2"><h3 id="_substitution_errors">Substitution errors</h3><p>In the event of an error, <code class="function pcre2-api rouge"><span class="nf">pcre2_substitute()</span></code> returns a negative error | |
| code. Except for <code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_NOMATCH</span></code> (which is never returned), errors from | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> are passed straight back.</p> | |
| <dl class="errors compact" style="--tab-width: 14"><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_NOSUBSTRING</span></code></span></dt><dd>is returned for a non-existent substring insertion, | |
| unless <code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_UNKNOWN_UNSET</span></code> is set.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_UNSET</span></code></span></dt><dd>is returned for an unset substring insertion (including an | |
| unknown substring when <code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_UNKNOWN_UNSET</span></code> is set) when the simple | |
| (non-extended) syntax is used and <code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_UNSET_EMPTY</span></code> is not set.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_NOMEMORY</span></code></span></dt><dd>is returned if the output buffer is not big enough. If the | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_OVERFLOW_LENGTH</span></code> option is set, the size of buffer that is | |
| needed is returned via <code class="parameter pcre2-api rouge"><span class="nv">blength</span></code>. Note that this does not happen by | |
| default.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_NULL</span></code></span></dt><dd>is returned if <code class="parameter pcre2-api rouge"><span class="nv">code</span></code> or <code class="parameter pcre2-api rouge"><span class="nv">blength</span></code> is <code class="constant pcre2-api rouge"><span class="kc">NULL</span></code>; or if | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_MATCHED</span></code> is set but the <code class="parameter pcre2-api rouge"><span class="nv">match_data</span></code> argument is | |
| <code class="constant pcre2-api rouge"><span class="kc">NULL</span></code>; or if the <code class="parameter pcre2-api rouge"><span class="nv">subject</span></code> or <code class="parameter pcre2-api rouge"><span class="nv">replacement</span></code> or <code class="parameter pcre2-api rouge"><span class="nv">buffer</span></code> | |
| argument is <code class="constant pcre2-api rouge"><span class="kc">NULL</span></code>. However, a <code class="constant pcre2-api rouge"><span class="kc">NULL</span></code> <code class="parameter pcre2-api rouge"><span class="nv">replacement</span></code> argument is | |
| allowed if the <code class="parameter pcre2-api rouge"><span class="nv">rlength</span></code> argument is zero; and similarly for <code class="parameter pcre2-api rouge"><span class="nv">subject</span></code> | |
| with zero <code class="parameter pcre2-api rouge"><span class="nv">length</span></code> and <code class="parameter pcre2-api rouge"><span class="nv">buffer</span></code> with zero <code class="parameter pcre2-api rouge"><span class="nv">blength</span></code>.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_BADMAGIC</span></code></span></dt><dd>the magic number in the compiled code was not recognized.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_BADMODE</span></code></span></dt><dd>the pattern was compiled for a different code unit width.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_BADREPLACEMENT</span></code></span></dt><dd>is used for miscellaneous syntax errors in the | |
| replacement string, with more particular errors being <code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_BADREPESCAPE</span></code> | |
| (invalid escape sequence), <code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_REPMISSINGBRACE</span></code> (closing curly bracket | |
| not found), <code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_BADSUBSTITUTION</span></code> (syntax error in extended group | |
| substitution), and <code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_BADSUBSPATTERN</span></code> (the pattern match ended before | |
| it started or the match started earlier than the current position in the | |
| subject, which can happen if <code class="regex rouge"><span class="pcre2-semantic">\K</span></code> is used in a lookaround assertion).</dd></div></dl> | |
| <p>As for all PCRE2 errors, a text message that describes the error can be | |
| obtained by calling the <code class="function pcre2-api rouge"><span class="nf">pcre2_get_error_message()</span></code> function (see | |
| "Obtaining a textual error message" | |
| above).</p></section> | |
| <section class="doc-section level-2"><h3 id="_substitution_callouts">Substitution callouts</h3><div class="listing-block prototype"><pre class="rouge highlight"><code data-lang="c"><span class="kt">int</span> <span class="nf">pcre2_set_substitute_callout</span><span class="p">(</span> | |
| <span class="kt">pcre2_match_context</span> <span class="p">*</span><span class="nv">mcontext</span><span class="p">,</span> | |
| <span class="kt">int</span> <span class="p">(</span><span class="p">*</span><span class="nv">substitute_callout</span><span class="p">)(</span> | |
| <span class="kt">pcre2_substitute_callout_block</span> <span class="p">*</span><span class="nv">callout_block</span><span class="p">,</span> | |
| <span class="kt">void</span> <span class="p">*</span><span class="nv">substitute_callout_data</span><span class="p">),</span> | |
| <span class="kt">void</span> <span class="p">*</span><span class="nv">substitute_callout_data</span><span class="p">);</span></code></pre></div> | |
| <p>The <code class="function pcre2-api rouge"><span class="nf">pcre2_set_substitute_callout()</span></code> function can be used to specify a | |
| callout function for <code class="function pcre2-api rouge"><span class="nf">pcre2_substitute()</span></code>. This information is passed in | |
| a match context. The callout function is called after each substitution has | |
| been processed, but it can cause the replacement not to happen.</p> | |
| <p>The callout function is not called for simulated substitutions that happen as a | |
| result of the <code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_OVERFLOW_LENGTH</span></code> option. In this mode, when | |
| substitution processing exceeds the buffer space provided by the caller, | |
| processing continues by counting code units. The simulation is unable to | |
| populate the callout block, and so the simulation is pessimistic about the | |
| required buffer size. Whichever is larger of accepted or rejected substitution | |
| is reported as the required size. Therefore, the returned buffer length may be | |
| an overestimate (without a substitution callout, it is normally an exact | |
| measurement).</p> | |
| <p>The first argument of the callout function is a pointer to a substitute callout | |
| block structure, which contains the following fields, not necessarily in this | |
| order:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="c"><span class="kt">uint32_t</span> <span class="nv">version</span><span class="p">;</span> | |
| <span class="kt">uint32_t</span> <span class="nv">subscount</span><span class="p">;</span> | |
| <span class="kt">PCRE2_SPTR</span> <span class="nv">input</span><span class="p">;</span> | |
| <span class="kt">PCRE2_SPTR</span> <span class="nv">output</span><span class="p">;</span> | |
| <span class="kt">PCRE2_SIZE</span> <span class="p">*</span><span class="nv">ovector</span><span class="p">;</span> | |
| <span class="kt">uint32_t</span> <span class="nv">oveccount</span><span class="p">;</span> | |
| <span class="kt">PCRE2_SIZE</span> <span class="nv">output_offsets</span><span class="p">[</span><span class="mi">2</span><span class="p">];</span></code></pre></div> | |
| <p>The <code class="parameter pcre2-api rouge"><span class="nv">version</span></code> field contains the version number of the block format. The | |
| current version is 0. The version number will increase in future if more fields | |
| are added, but the intention is never to remove any of the existing fields.</p> | |
| <p>The <code class="parameter pcre2-api rouge"><span class="nv">subscount</span></code> field is the number of the current match. It is 1 for the | |
| first callout, 2 for the second, and so on. The <code class="parameter pcre2-api rouge"><span class="nv">input</span></code> and <code class="parameter pcre2-api rouge"><span class="nv">output</span></code> | |
| pointers are copies of the values passed to <code class="function pcre2-api rouge"><span class="nf">pcre2_substitute()</span></code>.</p> | |
| <p>The <code class="parameter pcre2-api rouge"><span class="nv">ovector</span></code> field points to the ovector, which contains the result of the | |
| most recent match. The <code class="parameter pcre2-api rouge"><span class="nv">oveccount</span></code> field contains the number of pairs that | |
| are set in the ovector, and is always greater than zero.</p> | |
| <p>The <code class="parameter pcre2-api rouge"><span class="nv">output_offsets</span></code> vector contains the offsets of the replacement in the | |
| output string. This has already been processed for dollar and (if requested) | |
| backslash substitutions as described above.</p> | |
| <p>The second argument of the callout function is the value passed as | |
| <code class="parameter pcre2-api rouge"><span class="nv">callout_data</span></code> when the function was registered. The value returned by the | |
| callout function is interpreted as follows:</p> | |
| <p>If the value is zero, the replacement is accepted, and, if | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_GLOBAL</span></code> is set, processing continues with a search for the next | |
| match. If the value is not zero, the current replacement is not accepted. If | |
| the value is greater than zero, processing continues when | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_GLOBAL</span></code> is set. Otherwise (the value is less than zero or | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_GLOBAL</span></code> is not set), the rest of the input is copied to the | |
| output and the call to <code class="function pcre2-api rouge"><span class="nf">pcre2_substitute()</span></code> exits, returning the number of | |
| matches so far.</p></section> | |
| <section class="doc-section level-2"><h3 id="_substitution_case_callouts">Substitution case callouts</h3><div class="listing-block prototype"><pre class="rouge highlight"><code data-lang="c"><span class="kt">int</span> <span class="nf">pcre2_set_substitute_case_callout</span><span class="p">(</span> | |
| <span class="kt">pcre2_match_context</span> <span class="p">*</span><span class="nv">mcontext</span><span class="p">,</span> | |
| <span class="nf">PCRE2_SIZE</span> <span class="p">(</span><span class="p">*</span><span class="nv">substitute_case_callout</span><span class="p">)(</span> | |
| <span class="kt">PCRE2_SPTR</span> <span class="nv">input</span><span class="p">,</span> <span class="kt">PCRE2_SIZE</span> <span class="nv">input_length</span><span class="p">,</span> | |
| <span class="kt">PCRE2_UCHAR</span> <span class="p">*</span><span class="nv">output</span><span class="p">,</span> <span class="kt">PCRE2_SIZE</span> <span class="nv">output_capacity</span><span class="p">,</span> | |
| <span class="kt">int</span> <span class="nv">case_operation</span><span class="p">,</span> | |
| <span class="kt">void</span> <span class="p">*</span><span class="nv">substitute_case_callout_data</span><span class="p">),</span> | |
| <span class="kt">void</span> <span class="p">*</span><span class="nv">substitute_case_callout_data</span><span class="p">);</span></code></pre></div> | |
| <p>The <code class="function pcre2-api rouge"><span class="nf">pcre2_set_substitute_case_callout()</span></code> function can be used to specify | |
| a callout function for <code class="function pcre2-api rouge"><span class="nf">pcre2_substitute()</span></code> to use when performing case | |
| transformations. This does not affect any case insensitivity behaviour when | |
| performing a match, but only the user-visible transformations performed when | |
| processing a substitution such as:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="c"><span class="nf">pcre2_substitute</span><span class="p">(...,</span> <span class="s">"</span><span class="se">\\</span><span class="s">U$1"</span><span class="p">,</span> <span class="p">...)</span></code></pre></div> | |
| <p>The default case transformations applied by PCRE2 are reasonably complete, and, | |
| in UTF or UCP mode, perform the simple locale-invariant case transformations as | |
| specified by Unicode. This is suitable for the internal (invisible) | |
| case-equivalence procedures used during pattern matching, but an application | |
| may wish to use more sophisticated locale-aware processing for the user-visible | |
| substitution transformations.</p> | |
| <p>One example implementation of the <code class="parameter pcre2-api rouge"><span class="nv">substitute_case_callout</span></code> function using the ICU | |
| library would be:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="c"><span class="kt">PCRE2_SIZE</span> | |
| <span class="nf">icu_case_callout</span><span class="p">(</span><span class="kt">PCRE2_SPTR</span> <span class="nv">input</span><span class="p">,</span> <span class="kt">PCRE2_SIZE</span> <span class="nv">input_len</span><span class="p">,</span> | |
| <span class="kt">PCRE2_UCHAR</span> <span class="p">*</span><span class="nv">output</span><span class="p">,</span> <span class="kt">PCRE2_SIZE</span> <span class="nv">output_cap</span><span class="p">,</span> | |
| <span class="kt">int</span> <span class="nv">to_case</span><span class="p">,</span> <span class="kt">void</span> <span class="p">*</span><span class="nv">data_ptr</span><span class="p">)</span> | |
| <span class="p">{</span> | |
| <span class="nv">UErrorCode</span> <span class="nv">err</span> <span class="o">=</span> <span class="no">U_ZERO_ERROR</span><span class="p">;</span> | |
| <span class="kt">int32_t</span> <span class="nv">r</span> <span class="o">=</span> | |
| <span class="nv">to_case</span> <span class="o">==</span> <span class="no">PCRE2_SUBSTITUTE_CASE_LOWER</span> | |
| <span class="o">?</span> <span class="nf">u_strToLower</span><span class="p">(</span><span class="nv">output</span><span class="p">,</span> <span class="nv">output_cap</span><span class="p">,</span> <span class="nv">input</span><span class="p">,</span> <span class="nv">input_len</span><span class="p">,</span> | |
| <span class="kc">NULL</span><span class="p">,</span> <span class="p">&</span><span class="nv">err</span><span class="p">)</span> | |
| <span class="o">:</span> <span class="nv">to_case</span> <span class="o">==</span> <span class="no">PCRE2_SUBSTITUTE_CASE_UPPER</span> | |
| <span class="o">?</span> <span class="nf">u_strToUpper</span><span class="p">(</span><span class="nv">output</span><span class="p">,</span> <span class="nv">output_cap</span><span class="p">,</span> <span class="nv">input</span><span class="p">,</span> <span class="nv">input_len</span><span class="p">,</span> | |
| <span class="kc">NULL</span><span class="p">,</span> <span class="p">&</span><span class="nv">err</span><span class="p">)</span> | |
| <span class="o">:</span> <span class="nf">u_strToTitle</span><span class="p">(</span><span class="nv">output</span><span class="p">,</span> <span class="nv">output_cap</span><span class="p">,</span> <span class="nv">input</span><span class="p">,</span> <span class="nv">input_len</span><span class="p">,</span> | |
| <span class="p">&</span><span class="nv">first_char_only</span><span class="p">,</span> <span class="kc">NULL</span><span class="p">,</span> <span class="p">&</span><span class="nv">err</span><span class="p">);</span> | |
| <span class="k">if</span> <span class="p">(</span><span class="nf">U_FAILURE</span><span class="p">(</span><span class="nv">err</span><span class="p">))</span> | |
| <span class="k">return</span> <span class="p">(</span><span class="o">~</span><span class="p">(</span><span class="kt">PCRE2_SIZE</span><span class="p">)</span><span class="mi">0</span><span class="p">);</span> | |
| <span class="k">return</span> <span class="nv">r</span><span class="p">;</span> | |
| <span class="p">}</span></code></pre></div> | |
| <p>The first and second arguments of the case callout function are the Unicode | |
| string to transform.</p> | |
| <p>The third and fourth arguments are the output buffer and its capacity.</p> | |
| <p>The fifth is one of the constants <code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_CASE_LOWER</span></code>, | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_CASE_UPPER</span></code>, or <code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_CASE_TITLE_FIRST</span></code>. | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_CASE_LOWER</span></code> and <code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_CASE_UPPER</span></code> are passed to the | |
| callout to indicate that the case of the entire callout input should be | |
| case-transformed. <code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_CASE_TITLE_FIRST</span></code> is passed to indicate that | |
| only the first character or glyph should be transformed to Unicode titlecase | |
| and the rest to Unicode lowercase (note that titlecasing sometimes uses Unicode | |
| properties to titlecase each word in a string; but PCRE2 is requesting that only | |
| the single leading character is to be titlecased).</p> | |
| <p>The sixth argument is the <code class="parameter pcre2-api rouge"><span class="nv">callout_data</span></code> supplied to | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_set_substitute_case_callout()</span></code>.</p> | |
| <p>The resulting string in the destination buffer may be larger or smaller than the | |
| input, if the casing rules merge or split characters. The return value is the | |
| length required for the output string. If a buffer of sufficient size was | |
| provided to the callout, then the result must be written to the buffer and the | |
| number of code units returned. If the result does not fit in the provided | |
| buffer, then the required capacity must be returned and PCRE2 will not make use | |
| of the output buffer. PCRE2 provides input and output buffers which overlap, so | |
| the callout must support this by suitable internal buffering.</p> | |
| <p>Alternatively, if the callout wishes to indicate an error, then it may return | |
| <code class="c rouge" data-lang="c"><span class="p">(</span><span class="o">~</span><span class="p">(</span><span class="kt">PCRE2_SIZE</span><span class="p">)</span><span class="mi">0</span><span class="p">)</span></code>. In this case <code class="function pcre2-api rouge"><span class="nf">pcre2_substitute()</span></code> will immediately fail with | |
| error <code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_REPLACECASE</span></code>.</p> | |
| <p>When a case callout is combined with the <code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_OVERFLOW_LENGTH</span></code> | |
| option, there are situations when <code class="function pcre2-api rouge"><span class="nf">pcre2_substitute()</span></code> will return an | |
| underestimate of the required buffer size. If you call <code class="function pcre2-api rouge"><span class="nf">pcre2_substitute()</span></code> once | |
| with <code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_OVERFLOW_LENGTH</span></code>, and the input buffer is too small for | |
| the replacement string to be constructed, then instead of calling the case | |
| callout, <code class="function pcre2-api rouge"><span class="nf">pcre2_substitute()</span></code> will make an estimate of the required buffer size. | |
| The second call should also pass <code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_OVERFLOW_LENGTH</span></code>, because that | |
| second call is not guaranteed to succeed either, if the case callout requires | |
| more buffer space than expected. The caller must make repeated attempts in a | |
| loop.</p></section></section> | |
| <section class="doc-section level-1"><h2 id="_duplicate_capture_group_names">Duplicate capture group names</h2><div class="listing-block prototype"><pre class="rouge highlight"><code data-lang="c"><span class="kt">int</span> <span class="nf">pcre2_substring_nametable_scan</span><span class="p">(</span><span class="kt">const</span> <span class="kt">pcre2_code</span> <span class="p">*</span><span class="nv">code</span><span class="p">,</span> | |
| <span class="kt">PCRE2_SPTR</span> <span class="nv">stringname</span><span class="p">,</span> | |
| <span class="kt">PCRE2_SPTR</span> <span class="p">*</span><span class="nv">firstptr</span><span class="p">,</span> | |
| <span class="kt">PCRE2_SPTR</span> <span class="p">*</span><span class="nv">lastptr</span><span class="p">);</span></code></pre></div> | |
| <p>When a pattern is compiled with the <code class="constant pcre2-api rouge"><span class="no">PCRE2_DUPNAMES</span></code> option, names for capture | |
| groups are not required to be unique. Duplicate names are always allowed for | |
| groups with the same number, created by using the <code class="regex rouge"><span class="pcre2-semantic">(?|</span></code> feature. Indeed, if such | |
| groups are named, they are required to use the same names.</p> | |
| <p>Normally, patterns that use duplicate names are such that in any one match, | |
| only one of each set of identically-named groups participates. An example is | |
| shown in the | |
| <a href="./pcre2pattern.html"><code>pcre2pattern</code></a> | |
| documentation.</p> | |
| <p>When duplicates are present, <code class="function pcre2-api rouge"><span class="nf">pcre2_substring_copy_byname()</span></code> and | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_substring_get_byname()</span></code> return the first substring corresponding to | |
| the given name that is set. Only if none are set is <code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_UNSET</span></code> is | |
| returned. The <code class="function pcre2-api rouge"><span class="nf">pcre2_substring_number_from_name()</span></code> function returns the | |
| error <code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_NOUNIQUESUBSTRING</span></code> when there are duplicate names.</p> | |
| <p>If you want to get full details of all captured substrings for a given name, | |
| you must use the <code class="function pcre2-api rouge"><span class="nf">pcre2_substring_nametable_scan()</span></code> function. The first | |
| argument is the compiled pattern, and the second is the name. If the third and | |
| fourth arguments are <code class="constant pcre2-api rouge"><span class="kc">NULL</span></code>, the function returns a group number for a unique | |
| name, or <code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_NOUNIQUESUBSTRING</span></code> otherwise.</p> | |
| <p>When the third and fourth arguments are not <code class="constant pcre2-api rouge"><span class="kc">NULL</span></code>, they must be pointers to | |
| variables that are updated by the function. After it has run, they point to the | |
| first and last entries in the name-to-number table for the given name, and the | |
| function returns the length of each entry in code units. In both cases, | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_NOSUBSTRING</span></code> is returned if there are no entries for the given name.</p> | |
| <p>The format of the name table is described | |
| above | |
| in the section <a href="#information-about-compiled-pattern">Information about a compiled pattern</a>. Given all the | |
| relevant entries for the name, you can extract each of their numbers, and hence | |
| the captured data.</p></section> | |
| <section class="doc-section level-1"><h2 id="_finding_all_possible_matches_at_one_position">Finding all possible matches at one position</h2><p>The traditional matching function uses a similar algorithm to Perl, which stops | |
| when it finds the first match at a given point in the subject. If you want to | |
| find all possible matches, or the longest possible match at a given position, | |
| consider using the alternative matching function (see below) instead. If you | |
| cannot use the alternative function, you can kludge it up by making use of the | |
| callout facility, which is described in the | |
| <a href="./pcre2callout.html"><code>pcre2callout</code></a> | |
| documentation.</p> | |
| <p>What you have to do is to insert a callout right at the end of the pattern. | |
| When your callout function is called, extract and save the current matched | |
| substring. Then return 1, which forces <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> to backtrack and try | |
| other alternatives. Ultimately, when it runs out of matches, | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> will yield <code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_NOMATCH</span></code>.</p></section> | |
| <section class="doc-section level-1"><h2 id="_matching_a_pattern_the_alternative_function">Matching a pattern: the alternative function</h2><div class="listing-block prototype"><pre class="rouge highlight"><code data-lang="c"><span class="kt">int</span> <span class="nf">pcre2_dfa_match</span><span class="p">(</span><span class="kt">const</span> <span class="kt">pcre2_code</span> <span class="p">*</span><span class="nv">code</span><span class="p">,</span> <span class="kt">PCRE2_SPTR</span> <span class="nv">subject</span><span class="p">,</span> | |
| <span class="kt">PCRE2_SIZE</span> <span class="nv">length</span><span class="p">,</span> <span class="kt">PCRE2_SIZE</span> <span class="nv">start_offset</span><span class="p">,</span> | |
| <span class="kt">uint32_t</span> <span class="nv">options</span><span class="p">,</span> <span class="kt">pcre2_match_data</span> <span class="p">*</span><span class="nv">match_data</span><span class="p">,</span> | |
| <span class="kt">pcre2_match_context</span> <span class="p">*</span><span class="nv">mcontext</span><span class="p">,</span> <span class="kt">int</span> <span class="p">*</span><span class="nv">workspace</span><span class="p">,</span> | |
| <span class="kt">PCRE2_SIZE</span> <span class="nv">wscount</span><span class="p">);</span></code></pre></div> | |
| <p>The function <code class="function pcre2-api rouge"><span class="nf">pcre2_dfa_match()</span></code> is called to match a subject string | |
| against a compiled pattern, using a matching algorithm that scans the subject | |
| string just once (not counting lookaround assertions), and does not backtrack | |
| (except when processing lookaround assertions). This has different | |
| characteristics to the normal algorithm, and is not compatible with Perl. Some | |
| of the features of PCRE2 patterns are not supported. Nevertheless, there are | |
| times when this kind of matching can be useful. For a discussion of the two | |
| matching algorithms, and a list of features that <code class="function pcre2-api rouge"><span class="nf">pcre2_dfa_match()</span></code> does | |
| not support, see the | |
| <a href="./pcre2matching.html"><code>pcre2matching</code></a> | |
| documentation.</p> | |
| <p>The arguments for the <code class="function pcre2-api rouge"><span class="nf">pcre2_dfa_match()</span></code> function are the same as for | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code>, plus two extras. The <code class="parameter pcre2-api rouge"><span class="nv">ovector</span></code> within the match data block | |
| is used in a different way, and this is described below. The other common | |
| arguments are used in the same way as for <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code>, so their | |
| description is not repeated here.</p> | |
| <p>The two additional arguments provide workspace for the function. The workspace | |
| vector should contain at least 20 elements. It is used for keeping track of | |
| multiple paths through the pattern tree. More workspace is needed for patterns | |
| and subjects where there are a lot of potential matches.</p> | |
| <p>Here is an example of a simple call to <code class="function pcre2-api rouge"><span class="nf">pcre2_dfa_match()</span></code>:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="c"><span class="kt">int</span> <span class="nv">wspace</span><span class="p">[</span><span class="mi">20</span><span class="p">];</span> | |
| <span class="kt">pcre2_match_data</span> <span class="p">*</span><span class="nv">md</span> <span class="o">=</span> <span class="nf">pcre2_match_data_create</span><span class="p">(</span><span class="mi">4</span><span class="p">,</span> <span class="kc">NULL</span><span class="p">);</span> | |
| <span class="kt">int</span> <span class="nv">rc</span> <span class="o">=</span> <span class="nf">pcre2_dfa_match</span><span class="p">(</span> | |
| <span class="nv">re</span><span class="p">,</span> <span class="cm">/* result of pcre2_compile() */</span> | |
| <span class="s">"some string"</span><span class="p">,</span> <span class="cm">/* the subject string */</span> | |
| <span class="mi">11</span><span class="p">,</span> <span class="cm">/* the length of the subject string */</span> | |
| <span class="mi">0</span><span class="p">,</span> <span class="cm">/* start at offset 0 in the subject */</span> | |
| <span class="mi">0</span><span class="p">,</span> <span class="cm">/* default options */</span> | |
| <span class="nv">md</span><span class="p">,</span> <span class="cm">/* the match data block */</span> | |
| <span class="kc">NULL</span><span class="p">,</span> <span class="cm">/* a match context; NULL means use defaults */</span> | |
| <span class="nv">wspace</span><span class="p">,</span> <span class="cm">/* working space vector */</span> | |
| <span class="mi">20</span><span class="p">);</span> <span class="cm">/* number of elements (NOT size in bytes) */</span></code></pre></div> | |
| <section class="doc-section level-2"><h3 id="_option_bits_for_pcre2_dfa_match">Option bits for <code class="function pcre2-api rouge"><span class="nf">pcre2_dfa_match()</span></code></h3><p>The unused bits of the <code class="parameter pcre2-api rouge"><span class="nv">options</span></code> argument for <code class="function pcre2-api rouge"><span class="nf">pcre2_dfa_match()</span></code> must | |
| be zero. The only bits that may be set are <code class="constant pcre2-api rouge"><span class="no">PCRE2_ANCHORED</span></code>, | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_COPY_MATCHED_SUBJECT</span></code>, <code class="constant pcre2-api rouge"><span class="no">PCRE2_ENDANCHORED</span></code>, <code class="constant pcre2-api rouge"><span class="no">PCRE2_NOTBOL</span></code>, <code class="constant pcre2-api rouge"><span class="no">PCRE2_NOTEOL</span></code>, | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_NOTEMPTY</span></code>, <code class="constant pcre2-api rouge"><span class="no">PCRE2_NOTEMPTY_ATSTART</span></code>, <code class="constant pcre2-api rouge"><span class="no">PCRE2_NO_UTF_CHECK</span></code>, <code class="constant pcre2-api rouge"><span class="no">PCRE2_PARTIAL_HARD</span></code>, | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_PARTIAL_SOFT</span></code>, <code class="constant pcre2-api rouge"><span class="no">PCRE2_DFA_SHORTEST</span></code>, and <code class="constant pcre2-api rouge"><span class="no">PCRE2_DFA_RESTART</span></code>. All but the last | |
| four of these are exactly the same as for <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code>, so their | |
| description is not repeated here.</p> | |
| <dl class="options spaced" style="--tab-width: 10"><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_PARTIAL_HARD</span></code><br><code class="constant pcre2-api rouge"><span class="no">PCRE2_PARTIAL_SOFT</span></code></span></dt><dd>These have the same general effect as they do for <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code>, but the | |
| details are slightly different. When <code class="constant pcre2-api rouge"><span class="no">PCRE2_PARTIAL_HARD</span></code> is set for | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_dfa_match()</span></code>, it returns <code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_PARTIAL</span></code> if the end of the | |
| subject is reached and there is still at least one matching possibility that | |
| requires additional characters. This happens even if some complete matches have | |
| already been found. When <code class="constant pcre2-api rouge"><span class="no">PCRE2_PARTIAL_SOFT</span></code> is set, the return code | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_NOMATCH</span></code> is converted into <code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_PARTIAL</span></code> if the end of the | |
| subject is reached, there have been no complete matches, but there is still at | |
| least one matching possibility. The portion of the string that was inspected | |
| when the longest partial match was found is set as the first matching string in | |
| both cases. There is a more detailed discussion of partial and multi-segment | |
| matching, with examples, in the | |
| <a href="./pcre2partial.html"><code>pcre2partial</code></a> | |
| documentation.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_DFA_SHORTEST</span></code></span></dt><dd>Setting the <code class="constant pcre2-api rouge"><span class="no">PCRE2_DFA_SHORTEST</span></code> option causes the matching algorithm to stop as | |
| soon as it has found one match. Because of the way the alternative algorithm | |
| works, this is necessarily the shortest possible match at the first possible | |
| matching point in the subject string.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_DFA_RESTART</span></code></span></dt><dd>When <code class="function pcre2-api rouge"><span class="nf">pcre2_dfa_match()</span></code> returns a partial match, it is possible to call it | |
| again, with additional subject characters, and have it continue with the same | |
| match. The <code class="constant pcre2-api rouge"><span class="no">PCRE2_DFA_RESTART</span></code> option requests this action; when it is set, the | |
| <code class="parameter pcre2-api rouge"><span class="nv">workspace</span></code> and <code class="parameter pcre2-api rouge"><span class="nv">wscount</span></code> options must reference the same vector as | |
| before because data about the match so far is left in them after a partial | |
| match. There is more discussion of this facility in the | |
| <a href="./pcre2partial.html"><code>pcre2partial</code></a> | |
| documentation.</dd></div></dl></section> | |
| <section class="doc-section level-2"><h3 id="_successful_returns_from_pcre2_dfa_match">Successful returns from <code class="function pcre2-api rouge"><span class="nf">pcre2_dfa_match()</span></code></h3><p>When <code class="function pcre2-api rouge"><span class="nf">pcre2_dfa_match()</span></code> succeeds, it may have matched more than one | |
| substring in the subject. Note, however, that all the matches from one run of | |
| the function start at the same point in the subject. The shorter matches are | |
| all initial substrings of the longer matches. For example, if the pattern</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic"><.*></span></code></pre></div> | |
| <p>is matched against the string</p> | |
| <div class="literal-block"><pre>This is <something> <something else> <something further> no more</pre></div> | |
| <p>the three matched strings are</p> | |
| <div class="literal-block"><pre><something> <something else> <something further> | |
| <something> <something else> | |
| <something></pre></div> | |
| <p>On success, the yield of the function is a number greater than zero, which is | |
| the number of matched substrings. The offsets of the substrings are returned in | |
| the ovector, and can be extracted by number in the same way as for | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code>, but the numbers bear no relation to any capture groups | |
| that may exist in the pattern, because DFA matching does not support capturing.</p> | |
| <p>Calls to the convenience functions that extract substrings by name | |
| return the error <code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_DFA_UFUNC</span></code> (unsupported function) if used after a | |
| DFA match. The convenience functions that extract substrings by number never | |
| return <code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_NOSUBSTRING</span></code>.</p> | |
| <p>The matched strings are stored in the ovector in reverse order of length; that | |
| is, the longest matching string is first. If there were too many matches to fit | |
| into the ovector, the yield of the function is zero, and the vector is filled | |
| with the longest matches.</p> | |
| <aside class="admonition-block note" role="note"><h6 class="block-title label-only"><span class="title-label">Note: </span></h6><p>PCRE2’s "auto-possessification" optimization usually applies to character | |
| repeats at the end of a pattern (as well as internally). For example, the | |
| pattern <code class="regex rouge"><span class="pcre2-semantic">a\d+</span></code> is compiled as if it were <code class="regex rouge"><span class="pcre2-semantic">a\d++</span></code>. For DFA matching, this | |
| means that only one possible match is found. If you really do want multiple | |
| matches in such cases, either use an ungreedy repeat such as <code class="regex rouge"><span class="pcre2-semantic">a\d+?</span></code> or set | |
| the <code class="constant pcre2-api rouge"><span class="no">PCRE2_NO_AUTO_POSSESS</span></code> option when compiling.</p></aside></section> | |
| <section class="doc-section level-2"><h3 id="_error_returns_from_pcre2_dfa_match">Error returns from <code class="function pcre2-api rouge"><span class="nf">pcre2_dfa_match()</span></code></h3><p>The <code class="function pcre2-api rouge"><span class="nf">pcre2_dfa_match()</span></code> function returns a negative number when it fails. | |
| Many of the errors are the same as for <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code>, as described | |
| above. | |
| There are in addition the following errors that are specific to | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_dfa_match()</span></code>:</p> | |
| <dl class="compact" style="--tab-width: 14"><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_DFA_UITEM</span></code></span></dt><dd>This return is given if <code class="function pcre2-api rouge"><span class="nf">pcre2_dfa_match()</span></code> encounters an item in the | |
| pattern that it does not support, for instance, the use of <code class="regex rouge"><span class="pcre2-semantic">\C</span></code> in a UTF mode or | |
| a backreference.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_DFA_UCOND</span></code></span></dt><dd>This return is given if <code class="function pcre2-api rouge"><span class="nf">pcre2_dfa_match()</span></code> encounters a condition item | |
| that uses a backreference for the condition, or a test for recursion in a | |
| specific capture group. These are not supported.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_DFA_UINVALID_UTF</span></code></span></dt><dd>This return is given if <code class="function pcre2-api rouge"><span class="nf">pcre2_dfa_match()</span></code> is called for a pattern that | |
| was compiled with <code class="constant pcre2-api rouge"><span class="no">PCRE2_MATCH_INVALID_UTF</span></code>. This is not supported for DFA | |
| matching.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_DFA_WSSIZE</span></code></span></dt><dd>This return is given if <code class="function pcre2-api rouge"><span class="nf">pcre2_dfa_match()</span></code> runs out of space in the | |
| <code class="parameter pcre2-api rouge"><span class="nv">workspace</span></code> vector.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_DFA_RECURSE</span></code></span></dt><dd>When a recursion or subroutine call is processed, the matching function calls | |
| itself recursively, using private memory for the <code class="parameter pcre2-api rouge"><span class="nv">ovector</span></code> and <code class="parameter pcre2-api rouge"><span class="nv">workspace</span></code>. | |
| This error is given if the internal <code class="parameter pcre2-api rouge"><span class="nv">ovector</span></code> is not large enough. This should be | |
| extremely rare, as a vector of size 1,000 is used.</dd></div><div class="dlist-item"><dt><span><code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_DFA_BADRESTART</span></code></span></dt><dd>When <code class="function pcre2-api rouge"><span class="nf">pcre2_dfa_match()</span></code> is called with the <code class="constant pcre2-api rouge"><span class="no">PCRE2_DFA_RESTART</span></code> option, | |
| some plausibility checks are made on the contents of the workspace, which | |
| should contain data about the previous partial match. If any of these checks | |
| fail, this error is given.</dd></div></dl></section></section> | |
| <section class="doc-section level-1"><h2 id="_see_also">See also</h2><p><a href="./pcre2build.html"><code>pcre2build</code></a>, <a href="./pcre2callout.html"><code>pcre2callout</code></a>, <a href="./pcre2demo.html"><code>pcre2demo</code></a>, | |
| <a href="./pcre2matching.html"><code>pcre2matching</code></a>, <a href="./pcre2partial.html"><code>pcre2partial</code></a>, <a href="./pcre2posix.html"><code>pcre2posix</code></a>, | |
| <a href="./pcre2sample.html"><code>pcre2sample</code></a>, <a href="./pcre2unicode.html"><code>pcre2unicode</code></a>.</p> | |
| <h2 id="_author" class="discrete">Author</h2> | |
| <p>Philip Hazel<br> | |
| Retired from University Computing Service<br> | |
| Cambridge, England.</p> | |
| <h2 id="_revision" class="discrete">Revision</h2> | |
| <p>Last updated: 08 December 2025<br> | |
| Copyright © 1997-2024 University of Cambridge.</p></section></article></div></main><footer class="offline-footer"></footer></body></html> |