Pcre(3)

📦 version 0.9.5, in ubuntu jammy

🌸 NAME 🌸

Pcre — the C++ wrapper class for the PCRE library, from the pcre++ package 💖 (yes bestie, this page is Pcre(3), from the Library Functions Manual, and the description line in the original is literally just empty, no cap, we move).

✨ SYNOPSIS ✨

#include <pcre++.h>

💅 Public Member Functions 💅

  • Pcre ()
  • Pcre (const std::string &expression)
  • Pcre (const std::string &expression, const std::string &flags)
  • Pcre (const Pcre &P)
  • const Pcre & operator= (const std::string &expression)
  • const Pcre & operator= (const Pcre &P)
  • ~Pcre ()
  • bool search (const std::string &stuff)
  • bool search (const std::string &stuff, int OffSet)
  • Array * get_sub_strings ()
  • std::string get_match (int pos)
  • int get_match_start (int pos)
  • int get_match_end (int pos)
  • int get_match_start ()
  • int get_match_end ()
  • size_t get_match_length (int pos)
  • bool matched ()
  • int matches ()
  • Array split (const std::string &piece)
  • Array split (const std::string &piece, int limit)
  • Array split (const std::string &piece, int limit, int start_offset)
  • Array split (const std::string &piece, int limit, int start_offset, int end_offset)
  • Array split (const std::string &piece, std::vector< int > positions)
  • std::string replace (const std::string &piece, const std::string &with)

🫶 Public Attributes 🫶

  • bool did_match
  • int num_matches

🌈 Detailed Description 🌈

The Pcre class is a wrapper around the PCRE library. That's the whole bit. 🎀

The library pcre++ defines a class named Pcre which you can use to search in strings using regular expressions, and also to get the matched sub strings back out. Ngl, it does not currently support every single feature the underlying PCRE library gives you — but bestie, the most important stuff? All implemented. Slay. 👑

Please study this example code to learn how to use this class — it's giving tutorial, it's giving main character:

/*
 *
 *  This file  is part of the PCRE++ Class Library.
 *
 *  By  accessing  this software,  PCRE++, you  are  duly informed
 *  of and agree to be  bound  by the  conditions  described below
 *  in this notice:
 *
 *  This software product,  PCRE++,  is developed by Thomas Linden
 *  and  copyrighted (C) 2002  by  Thomas Linden,  with all rights
 *  reserved.
 *
 *  There  is no charge for PCRE++ software.  You can redistribute
 *  it and/or modify it under the terms of the GNU  Lesser General
 *  Public License, which is incorporated by reference herein.
 *
 *  PCRE++ is distributed WITHOUT ANY WARRANTY, IMPLIED OR EXPRESS,
 *  OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE or that
 *  the use of it will not infringe on any third party's intellec-
 *  tual property rights.
 *
 *  You should have received a copy of the GNU Lesser General Public
 *  License along with PCRE++.  Copies can also be obtained from:
 *
 *    http://www.gnu.org/licenses/lgpl.txt
 *
 *  or by writing to:
 *
 *  Free Software Foundation, Inc.
 *  59 Temple Place, Suite 330
 *  Boston, MA 02111-1307
 *  USA
 *
 *  Or contact:
 *
 *   'Thomas Linden' <tom@daemon.de>
 *
 *
 */

/* you need to include the pcre++ header file */
#include <pcre++.h>
#include <iostream>

using namespace std;

void regex() {
    /*
     * define a string with a regular expression
     */
    string expression = '([a-z]*) ([0-9]+)';

    /*
     * this is the string in which we want to search
     */
    string stuff = 'hallo 11 robert';

    cout << '  searching in ´' << stuff << '´ for regex ´'
         << expression << '´:' << endl;

    /*
     * Create a new Pcre object, search case-insensitive ('i')
     */
    Pcre reg(expression, 'i');

    /*
     * see if the expression matched
     */
    if(reg.search(stuff) == true) {

      /*
       * see if the expression generated any substrings
       */
      if(reg.num_matches >= 1) {

        /*
         * print out the number of substrings
         */
        cout << '  generated ' << reg.matches() << ' substrings:' << endl;

        /*
         * iterate over the matched sub strings
         */
        for(int pos=0; pos < reg.matches(); pos++) {
          /* print out each substring */
          cout << '  substring ' << pos << ': ' << reg.get_match(pos);
          /* print out the start/end offset of the current substring
           * within the searched string(stuff)
           */
          cout << ' (start: ' << reg.get_match_start(pos) << ', end: '
               << reg.get_match_end(pos) << ')' << endl;
        }
      }
      else {
        /*
         * we had a match, but it generated no substrings, for whatever reason
         */
        cout << '   it matched, but there where no substrings.' << endl;
      }
    }
    else {
      /*
       * no match at all
       */
      cout << '   didn't match.' << endl;
    }
}

void replace() {
    /*
     * Sample of replace() usage
     */
    string orig = 'Hans ist 22 Jahre alt. Er ist 8 Jahre älter als Fred.';
    cout << '   orig: ' << orig << endl;

    /*
     * define a regex for digits (character class)
     */
    Pcre p(' ([0-9]+) ');

    /*
     * replace the 1st occurence of [0-9]+ with 'zweiundzwanzig'
     */
    string n = p.replace(orig, ' zweiundzwanzig($1) ');

    /*
     * prints out: 'Hans ist zweiundzwanzig Jahre alt. Er ist 8 Jahre älter
     * als Fred.'
     */
    cout << '   new: ' << n << endl;
}

void replace_multi() {
  /*
   * Sample of replace() usage with multiple substrings
   */
  string orig = ' 08:23 ';
  cout << '   orig: ' << orig << endl;

  /*
   * create regex which, if it matches, creates 3 substrings
   */
  Pcre reg(' ([0-9]+)(:)([0-9]+) ', 'sig');

  /*
   * remove $2 (':')
   * re-use $1 ('08') and $3 ('23') in the replace string
   */
  string n  = reg.replace(orig, '$1 Stunden und $3 Minuten');

  /*
   * prints the result: '08 Stunden und 23 Minuten'
   */
  cout << '   new:  ' << n  << endl;
}

void normalize() {
  /*
   * another sample to check if normalizing using replace() works
   */
  string orig = 'Heute   ist ein  schoener  Tag        gell?';
  cout << '   orig: ' << orig << endl;

  /*
   * create regex for normalizing whitespace
   */
  Pcre reg('[\s]+', 'gs');

  /*
   * do the normalizing process
   */
  string n = reg.replace(orig, ' ');

  /*
   * prints the result, should be: 'Heute ist ein schoener Tag , gell?'
   */
  cout << '   new:  ' << n  << endl;
}

void split() {
  /*
   * Sample of split() usage
   */
      string sp_orig = 'was21willst2387461du3alter!';
      cout << '   orig: ' << sp_orig << endl;

      /*
       * define a regex for digits (character class)
       */
      string delimiter = '[0-9]+';

      /*
       * new Pcre object, match globally ('g' flag)
       */
      Pcre S(delimiter, 'g');

      /*
       * split 'was21willst2387461du3alter!' by digits
       */
      Array splitted = S.split(sp_orig);

      /*
       * iterate over the resulting list
       */
      cout << '   splitted: ';
      for(ArrayIterator A = splitted.begin(); A != splitted.end(); ++A)
        cout << *A << ' ';
      cout << endl;
}

void ex() {
  /*
   * Pcre::exception Test
   */

  /*
   * this will generate only one substring, 'This'
   */
  Pcre ex('([a-z]+)', 'i');
  if(ex.search('This is a test.')) {
    cout << '  trying to access a non-existing substring:' << endl;
    cout << '  substring 2: ' << ex.get_match(1) << endl;
  }
}

void mycopy() {
  /*
   * Sample use of copy contsructor and operator=
   */
    cout << '  initializing reg1(([a-z]+?)' << endl;
    Pcre reg1('^([a-z]+?)');

    /*
     * create an empty Pcre objects
     */
    Pcre reg2;

    /*
     * copy reg1 to reg2 (operator=)
     */
    cout << '  copying reg1 to new Pcre object reg2' << endl;
    reg2 = reg1;

    /*
     * using the copy constructor to initialize the 3rd object
     */
    cout << '  creating a new Pcre object reg3 from reg2' << endl;
    Pcre reg3(reg2);

    /*
     * doing regular stuff on reg3
     */
    if(reg3.search('anton'))
      cout << '  string 'anton' matched using reg3 object' << endl;
}

void multisearch() {
  Pcre reg('([^\n]+\n)');
  string str = '0ine10ine20ine30;
  size_t pos = 0;

  while (pos <= str.length()) {
    if( reg.search(str, pos)) {
      pos = reg.get_match_end(0);
      cout << '   pos: ' << pos << ' match: ' << reg.get_match(0);
    }
    else
      break;
  }
}

int main() {
  /*
   * the Pcre class throws errors via exceptions
   */
  try {
    cout << endl << 'SEARCH() sample:' << endl;
    regex();

    cout << endl << 'REPLACE() sample:' << endl;
    replace();

    cout << endl << 'Multiple REPLACE() sample:' << endl;
    replace_multi();

    cout << endl << 'Normalizing REPLACE() sample:' << endl;
    normalize();

    cout << endl << 'SPLIT() sample:' << endl;
    split();

    cout << endl << 'COPY+Operator sample:' << endl;
    mycopy();

    cout << endl << 'Multi line search test:' << endl;
    multisearch();

    cout << endl << 'Pcre::exception test:' << endl;
    ex();

    exit(0);
  }
  catch (Pcre::exception &E) {
    /*
     * the Pcre class has thrown an exception
     */
    cerr << 'Pcre++ error: ' << E.what() << endl;
    exit(-1);
  }
  exit(0);
}

Ok so to compile your own programs that use the pcre++ class, the original hands you this command line — copy it exactly, bestie, don't freestyle it:

g++ -c yourcode.o `pcre-config --cflags` `pcre++-config --cflags`
g++ yourcode.o `pcre-config --libs` `pcre++-config --libs` -o yourprogram
🦋 Note the backticks — those are command substitutions doing the heavy lifting, not decoration. Do not lose them.

Wanna learn more about the regular expressions you can actually use with pcre++? Go read this: perlre - Perl regular expressions 📖

The pcre library itself also ships with some useful documentation that might be interesting to you: PCRE manual page ✨

📍 Definition at line 95 of file pcre++.h.

and that's where part one of this page lands, bestie — there's more of it still loading… 💖

💖 Constructor & Destructor Documentation 💖

🎀 Pcre::Pcre () 🎀

Empty Constructor, bestie. This makes you a brand new, squeaky-clean empty Pcre object. It's literally the simplest constructor in the whole roster, so ngl you might wanna peek at the other constructors as a better solution 👀. Here's the thing though — if you go the empty-constructor route, you have to initialize this Pcre object yourself. The move is to use one of the two available operator= operators to hand it an expression or a Pcre copy.

  • Returns: a new empty Pcre object ✨
  • Definition at line 86 of file pcre++.cc.

🌸 Pcre::Pcre (const std::string & expression) 🌸

Constructor, and she's a hard worker. This compiles the pattern you give her. A Pcre object born this way can be used over and over to do searches — no re-compiling, no drama 💅.

  • Parameters:
    • expression — a string, which must be a valid perl regular expression.
  • Returns: a new Pcre object, which holds the compiled pattern.
  • See also: Pcre(const std::string& expression, const std::string& flags)
  • Definition at line 49 of file pcre++.cc.

✨ Pcre::Pcre (const std::string & expression, const std::string & flags) ✨

Constructor number two, now with flags 🚩. Same deal: it compiles the given pattern, and the resulting Pcre object can be used multiple times to do searches.

  • Parameters:
    • expression — a string, which must be a valid perl regular expression.
    • flags — can be one or more of the following letters:
      • i — Search case insensitive.
      • m — Match on multiple lines, thus ^ and $ are interpreted as the start and end of the entire string, not of a single line.
      • s — A dot in an expression matches newlines too (which is normally not the case).
      • x — Whitespace characters will be ignored (except within character classes or if escaped).
      • g — Match multiple times. This flag affects only the behavior of the replace(const std::string& piece, const std::string& with) method.
  • Returns: a new Pcre object, which holds the compiled pattern.
  • See also: Pcre(const std::string& expression)
  • Definition at line 57 of file pcre++.cc.

🦋 Pcre::Pcre (const Pcre & P) 🦋

Copy Constructor, aka the twin-maker 👯. Creates a new Pcre object out of an existing one.

  • Parameters:
    • P — an existing Pcre object.
  • Returns: a new Pcre object, which holds the compiled pattern.
  • See also:
    • Pcre(const std::string& expression)
    • Pcre(const std::string& expression, const std::string& flags)
  • Definition at line 77 of file pcre++.cc.
  • References _expression, _flags, case_t, and global_t.

💀 Pcre::~Pcre () 💀

Destructor, the closer 🫶. She gets automatically invoked once the object isn't used anymore, and she frees all the memory allocated by pcre++. Clean exit, no leaks, we love to see it.

  • Definition at line 99 of file pcre++.cc.
  • References num_matches.

👑 Member Function Documentation 👑

🍓 string Pcre::get_match (int pos) 🍓

Get a substring at a known position. Heads up though: this method throws an out-of-range exception if the given position is invalid 😭. So know your positions, bestie.

  • Parameters:
    • pos — the position of the substring to return. Identical to perl's $1..$n.
  • Returns: the substring at the given position.

Example:

std::string mysub = regex.get_match(1);

That grabs the first substring that matched the expression in the regex object 💅.

  • Definition at line 59 of file get.cc.
  • References ArrayIterator, and num_matches.

🌈 int Pcre::get_match_end () 🌈

Get the end position of the entire match within the searched string. She hands you the character position of the last character of the entire match inside the searched string.

  • Returns: the integer character position of the last character of the entire match.

Example:

Pcre regex('([0-9]+)a-z]+)');     // search for the date(makes 2 substrings
regex.search('The 11th september.');  // do the search on this string
int pos = regex.get_match_end();      // returns 17, because '11th september', which is
                                          // the entire match, ends at the
                                      // 17th character inside the search string.
  • See also:
    • int get_match_start()
    • int get_match_start(int pos)
    • int get_match_end(int pos)
  • Definition at line 76 of file get.cc.
  • Referenced by replace().

🧚 int Pcre::get_match_end (int pos) 🧚

Same energy, but for a substring — she gives you the end position of a substring within the searched string, i.e. the character position of the last character of a substring inside the searched string.

  • Parameters:
    • pos — the position of the substring. Identical to perl's $1..$n.
  • Returns: the integer character position of the last character of a substring. Positions are starting at 0.

Example:

Pcre regex('([0-9]+)');               // search for numerical characters
regex.search('The 11th september.');  // do the search on this string
std::string day = regex.get_match(1);      // returns '11'
int pos = regex.get_match_end(1);     // returns 5, because '11' ends at the
                                      // 5th character inside the search string.
  • See also:
    • int get_match_start(int pos)
    • int get_match_start()
    • int get_match_end()
  • Definition at line 95 of file get.cc.
  • References num_matches.

🎀 size_t Pcre::get_match_length (int pos) 🎀

Get the length of a substring at a known position. And yes, same warning as before: this one throws an out-of-range exception if the given position is invalid 🙈.

  • Parameters:
    • pos — the position of the substring-length to return. Identical to perl's $1..$n.
  • Returns: the length substring at the given position.
  • Definition at line 109 of file get.cc.
  • References ArrayIterator, and num_matches.

🌟 int Pcre::get_match_start () 🌟

Get the start position of the entire match within the searched string. She returns the character position of the first character of the entire match inside the searched string.

  • Returns: the integer character position of the first character of the entire match.

Example:

Pcre regex('([0-9]+)a-z]+)');     // search for the date(makes 2 substrings
regex.search('The 11th september.');  // do the search on this string
int pos = regex.get_match_start();    // returns 4, because '11th september' begins at the
                                      // 4th character inside the search string.
  • See also:
    • int get_match_start(int pos)
    • int get_match_end(int pos)
    • int get_match_end()
  • Definition at line 69 of file get.cc.
  • Referenced by replace().

💜 int Pcre::get_match_start (int pos) 💜

Get the start position of a substring within the searched string — the character position of the first character of a substring inside the searched string.

  • Parameters:
    • pos — the position of the substring. Identical to perl's $1..$n.
  • Returns: the integer character position of the first character of a substring. Positions are starting at 0.

Example:

Pcre regex('([0-9]+)');               // search for numerical characters
regex.search('The 11th september.');  // do the search on this string
std::string day = regex.get_match(1);      // returns '11'
int pos = regex.get_match_start(1);   // returns 4, because '11' begins at the
                                      // 4th character inside the search string.
  • See also:
    • int get_match_end(int pos)
    • int get_match_end()
    • int get_match_start()
  • Definition at line 83 of file get.cc.
  • References num_matches.

🫶 Array * Pcre::get_sub_strings () 🫶

Return a vector of substrings, if any. Very "if she has anything for you she'll say it" energy.

  • Returns: a pointer to an Array, which may be NULL, if no substrings has been found. So please, check before you dereference, bestie 😭.
  • See also: Array
  • Definition at line 52 of file get.cc.
  • References Array.

💅 bool Pcre::matched () [inline] 💅

Test if a search was successful. And listen — this method must be invoked after calling search() ⚠️. Order matters, fr fr.

  • Returns: boolean true if the search was successful at all, or false if not.
  • Definition at line 409 of file pcre++.h.
  • Referenced by replace().

🔥 int Pcre::matches () [inline] 🔥

Get the number of substrings generated by pcre++. The receipts, basically.

  • Returns: the number of substrings generated by pcre++.
  • Definition at line 414 of file pcre++.h.
  • Referenced by replace().

⭐ const Pcre & Pcre::operator= (const Pcre & P) ⭐

Operator =. Copy assignment, iconic behavior.

  • Parameters:
    • &P — an Pcre object
  • Returns: a new Pcre object

Example:

Pcre reg1('^[a-z]+?');
Pcre reg2;
reg2 = reg1;
  • Definition at line 132 of file pcre++.cc.
  • References _expression, _flags, case_t, and global_t.

🌸 const Pcre & Pcre::operator= (const std::string & expression) 🌸

Operator =, but she takes a string instead. Give her an expression and she becomes it.

  • Parameters:
    • expression — a valid regular expression.
  • Returns: a new Pcre object.

Example:

Pcre regex = '(A+?)';
  • Definition at line 121 of file pcre++.cc.

🦋 string Pcre::replace (const std::string & piece, const std::string & with) 🦋

Replace parts of a string using regular expressions 🔁. This method is the counterpart of the perl s/// operator — she swaps out the substrings that matched the given regular expression (the one you gave to the constructor) with the string you supply.

  • Parameters:
    • piece — the string in which you want to search and replace.
    • with — the string which you want to place on the positions which match the expression (given to the constructor).
  • Definition at line 50 of file replace.cc.
  • References __pcredebug, did_match, get_match_end(), get_match_start(), matched(), matches(), num_matches, and search().

🌈 bool Pcre::search (const std::string & stuff, int OffSet) 🌈

Do a search on the given string beginning at the given offset. She does the actual searching on the string you hand over.

  • Parameters:
    • stuff — the string in which you want to search for something.
    • OffSet — the offset where to start the search.
  • Returns: boolean true if the regular expression matched. false if not.
  • See also: bool search(const std::string& stuff)
  • Definition at line 83 of file search.cc.

🎀 bool Pcre::search (const std::string & stuff) 🎀

Do a search on the given string, no offset, no extras. She does the actual search on the given string 💖.

  • Parameters:
    • stuff — the string in which you want to search for something.
  • Returns: boolean true if the regular expression matched. false if not.
  • See also: bool search(const std::string& stuff, int OffSet)
  • Definition at line 87 of file search.cc.
  • Referenced by replace().

✂️ Array Pcre::split (const std::string & piece, std::vector< int > positions) ✂️

Split a string into pieces. This method will split the given string into a vector of strings using the compiled expression (given to the constructor). Very "cut it up into little pieces and hand them back" 🍰.

  • Parameters:
    • piece — The string you want to split into its parts.
    • positions — a std::vector<int> of positions, which the returned Array should contain.
  • Returns: an Array of strings
  • See also: Array split(const std::string& piece)

💅 the rest of the split() overloads, bestie

okay so the page literally cut off mid-Array right here 😭 not me getting cliffhanger'd by a manpage. anyway, here's the rest of that list:

  • Array split(const std::string& piece, int limit)
  • Array split(const std::string& piece, int limit, int start_offset)
  • Array split(const std::string& piece, int limit, int start_offset)
  • Array
Definition at line 150 of file split.cc.

References Array.

🌸 Array Pcre::split (const std::string & piece, int limit, int start_offset, int end_offset)

split a string into pieces — this method will split the given string into a vector of strings using the compiled expression (the one you handed to the constructor). the full-control version, all four dials turned up 🔥

Parameters:

  • piece — The string you want to split into it's parts.
  • limit — the maximum number of elements you want to get back from split().
  • start_offset — at which substring the returned Array should start.
  • end_offset — at which substring the returned Array should end.

Returns:

  • an Array of strings

See also:

  • Array split(const std::string& piece)
  • Array split(const std::string& piece, int limit)
  • Array split(const std::string& piece, int limit, int start_offset)
  • Array split(const std::string& piece, std::vector<int> positions)
  • Array
Definition at line 146 of file split.cc.

References Array.

🦋 Array Pcre::split (const std::string & piece, int limit, int start_offset)

split a string into pieces — this method will split the given string into a vector of strings using the compiled expression (given to the constructor). same energy as above, just without the end_offset lil handle 🎀

Parameters:

  • piece — The string you want to split into it's parts.
  • limit — the maximum number of elements you want to get back from split().
  • start_offset — at which substring the returned Array should start.

Returns:

  • an Array of strings

See also:

  • Array
  • Array split(const std::string& piece)
  • Array split(const std::string& piece, int limit)
  • Array split(const std::string& piece, int limit, int start_offset, int end_offset)
  • Array split(const std::string& piece, std::vector<int> positions)
Definition at line 142 of file split.cc.

References Array.

🎀 Array Pcre::split (const std::string & piece, int limit)

split a string into pieces — this method will split the given string into a vector of strings using the compiled expression (given to the constructor). now we're capping how much you get back, very mindful, very demure ✨

Parameters:

  • piece — The string you want to split into it's parts.
  • limit — the maximum number of elements you want to get back from split().

Returns:

  • an Array of strings

See also:

  • Array
  • Array split(const std::string& piece)
  • Array split(const std::string& piece, int limit, int start_offset)
  • Array split(const std::string& piece, int limit, int start_offset, int end_offset)
  • Array split(const std::string& piece, std::vector<int> positions)
Definition at line 138 of file split.cc.

References Array.

💖 Array Pcre::split (const std::string & piece)

split a string into pieces — this method will split the given string into a vector of strings using the compiled expression (given to the constructor). the bare-minimum, just-give-me-everything version, and honestly? she ate 💅

Parameters:

  • piece — The string you want to split into it's parts.

Returns:

  • an Array of strings

See also:

  • Array
  • Array split(const std::string& piece, int limit)
  • Array split(const std::string& piece, int limit, int start_offset)
  • Array split(const std::string& piece, int limit, int start_offset, int end_offset)
  • Array split(const std::string& piece, std::vector<int> positions)
Definition at line 134 of file split.cc.

References Array.

✨ Member Data Documentation ✨

the lore. the receipts. the variables just vibing in there 👑

💜 bool Pcre::did_match

Definition at line 169 of file pcre++.h.

Referenced by replace().

🌈 int Pcre::num_matches

true if the expression produced a match

Definition at line 170 of file pcre++.h.

Referenced by get_match(), get_match_end(), get_match_length(), get_match_start(), replace(), and ~Pcre().

👑 Author

Generated automatically by Doxygen for PCRE++ from the source code.

and that's a wrap bestie 🫶 this whole thing is the PCRE++ page, version 26 Jun 2003, filed under Pcre(3) — go forth and split responsibly, mwah 💖

📦 where this page comes from