JRegex Class Reference

#include <JRegex.h>

Classes
class	Error

Public Types
enum	IncludeSubmatches {   kIgnoreSubmatches = 0 ,   kIncludeSubmatches = 1 }

Public Member Functions
	JRegex ()
	JRegex (const JString &pattern)
	JRegex (const JUtf8Byte *pattern)
virtual	~JRegex ()
	JRegex (const JRegex &source)
JRegex &	operator= (const JRegex &source)
const JString &	GetPattern () const
JError	SetPattern (const JString &pattern)
JError	SetPattern (const JUtf8Byte *pattern)
void	SetPatternOrDie (const JString &pattern)
void	SetPatternOrDie (const JUtf8Byte *pattern)
JSize	GetSubexpressionCount () const
bool	GetSubexpressionIndex (const JUtf8Byte *name, JIndex *index) const
bool	GetSubexpressionIndex (const JString &name, JIndex *index) const
bool	Match (const JString &str) const
JStringMatch	Match (const JString &str, const IncludeSubmatches includeSubmatches) const
bool	IsCaseSensitive () const
void	SetCaseSensitive (const bool yesNo=true)
bool	IsSingleLine () const
void	SetSingleLine (const bool yesNo=true)
bool	IsLineBegin () const
void	SetLineBegin (const bool yesNo=true)
bool	IsLineEnd () const
void	SetLineEnd (const bool yesNo=true)
bool	IsUtf8 () const
void	SetUtf8 (const bool yesNo=true)
JError	RestoreDefaults ()

Static Public Member Functions
static bool	NeedsBackslashToBeLiteral (const JUtf8Byte c)
static bool	NeedsBackslashToBeLiteral (const JUtf8Character &c)
static JString	BackslashForLiteral (const JString &text)

Static Public Attributes
static const JUtf8Byte *	kError = "Error::JRegex"

Protected Member Functions
JStringMatch	MatchForward (const JString &str, const JIndex byteIndex) const
JStringMatch	MatchBackward (const JString &str, const JIndex byteIndex) const

Friends
class	JStringIterator
class	JSubstitute

Detailed Description

JRegex provides regular expression-based search with a convenient, safe
interface which is idiomatic in both C++ and JCore.

USAGE:

A pattern is set with the constructor or the SetPattern method.
Matches are then performed with Match*().

Search & replace must be done using a JStringIterator.

DESIGN:

JRegex uses a dollar sign '$' for match interpolations.  Backslashes
are used in some tools, but for several reasons it is better for both
user and implementor to use a different symbol for character escapes
and for match interpolation.  One is that dollar signs avoid the
'backslashitis' which results in source code because C already expands
them (of course, you still have to deal with this problem for character
escapes).  They also correspond to the preferred usage in Perl,
arguably the premier regex tool.

The Match functions assert that a pattern has successfully been set.
It might be more forgiving to simply return an error condition instead.
This would, however considerably complicate the Match interface, and I
don't think it's worth it.  It is infeasible to simply have a default
pattern because there is no clear choice and this would only make
things more confusing.  Just check to see that it is set before calling
a Match... function.

IMPLEMENTATION:

JRegex is a thin layer over the PCRE package.  It provides an improved,
native C++ interface, but the real work is underneath, in PCRE.

The private Match function asserts that it did not run out of memory
or get passed an invalid argument.  I think JRegex can guarantee that
regex is never fed an invalid argument, so this is probably fine.

Member Enumeration Documentation

IncludeSubmatches

enum JRegex::IncludeSubmatches

Enumerator
kIgnoreSubmatches
kIncludeSubmatches

Constructor & Destructor Documentation

JRegex() [1/4]

JRegex::JRegex

(

)

The form which takes a pattern argument automatically does a SetPattern, which is convenient. However, it also asserts that this pattern was successfully compiled, which can be rather inconvenient if you make a mistake. So don't make mistakes (or don't use that constructor). :-)

JRegex() [2/4]

JRegex::JRegex

(

const JString &

pattern

)

JRegex() [3/4]

JRegex::JRegex

(

const JUtf8Byte *

pattern

)

~JRegex()

JRegex::~JRegex ( )

virtual

JRegex() [4/4]

JRegex::JRegex

(

const JRegex &

source

)

Member Function Documentation

BackslashForLiteral()

JString JRegex::BackslashForLiteral ( const JString &  text )

static

Insert backslashes so the string will be interpreted literally by the regex parser.

GetPattern()

const JString & JRegex::GetPattern ( ) const

inline

GetSubexpressionCount()

JSize JRegex::GetSubexpressionCount

(

)

const

Returns the number of parenthesized subexpressions in the compiled expression. Returns zero if there is no compiled expression or if the expression has no subexpressions.

GetSubexpressionIndex() [1/2]

bool JRegex::GetSubexpressionIndex ( const JString &  name, JIndex *  index  ) const

inline

GetSubexpressionIndex() [2/2]

bool JRegex::GetSubexpressionIndex	(	const JUtf8Byte *	name,
		JIndex *	index
	)		const

IsCaseSensitive()

bool JRegex::IsCaseSensitive ( ) const

inline

IsLineBegin()

bool JRegex::IsLineBegin ( ) const

inline

IsLineEnd()

bool JRegex::IsLineEnd ( ) const

inline

IsSingleLine()

bool JRegex::IsSingleLine ( ) const

inline

IsUtf8()

bool JRegex::IsUtf8 ( ) const

inline

Match() [1/2]

bool JRegex::Match ( const JString &  str ) const

inline

Returns true if our pattern matches the given string.

Match() [2/2]

JStringMatch JRegex::Match ( const JString &  str, const IncludeSubmatches  includeSubmatches  ) const

inline

MatchBackward()

JStringMatch JRegex::MatchBackward ( const JString &  str, const JIndex  byteIndex  ) const

protected

The MatchBackward function attempts to provide an efficient algorithm for backwards searching on large buffers by a trial-and-error scheme.

The byteIndex is included in the search range; in other words, the search is over the range [1, byteIndex]. Index may be any number from 1 to the length of the buffer.

MatchForward()

JStringMatch JRegex::MatchForward ( const JString &  str, const JIndex  byteIndex  ) const

inlineprotected

If a match is not found, the returned JStringMatch will be empty.

NeedsBackslashToBeLiteral() [1/2]

bool JRegex::NeedsBackslashToBeLiteral ( const JUtf8Byte  c )

inlinestatic

JAFL 5/11/98

Returns true if the given character needs to be backslashed in order to be treated as a literal by the regex compiler.

NeedsBackslashToBeLiteral() [2/2]

bool JRegex::NeedsBackslashToBeLiteral ( const JUtf8Character &  c )

inlinestatic

operator=()

JRegex & JRegex::operator=

(

const JRegex &

source

)

RestoreDefaults()

JError JRegex::RestoreDefaults

(

)

Restores the default values of both the compile-time and run-time options.

SetCaseSensitive()

void JRegex::SetCaseSensitive ( const bool  yesNo = true )

inline

Controls whether matches will be case sensitive (the default) or case insensitive.

Performance note: changing this option can cause a recompile before the next match.

SetLineBegin()

void JRegex::SetLineBegin ( const bool  yesNo = true )

inline

Controls whether the beginning of the string to be matched is considered to begin a line for purposes of matching '^'. Default is for '^' to match at the beginning of the string. This option is independent of SetSingleLine().

SetLineEnd()

void JRegex::SetLineEnd ( const bool  yesNo = true )

inline

Controls whether the end of the string to be matched is considered to end a line for purposes of matching '$'. Default is for '$' to match at the end of the string. This option is independent of SetSingleLine().

SetPattern() [1/2]

JError JRegex::SetPattern

(

const JString &

pattern

)

Sets 'pattern' as the regular expression for subsequent matches. Returns false if the pattern could not be compiled, true otherwise. If the compile fails the pattern remains set until the next call to SetPattern(); it can be examined with GetPattern().

SetPattern() [2/2]

JError JRegex::SetPattern

(

const JUtf8Byte *

pattern

)

SetPatternOrDie() [1/2]

void JRegex::SetPatternOrDie

(

const JString &

pattern

)

All forms are like the corresponding SetPattern forms, but they assert that the set succeeds. A minor convenience, since a set followed by an assert seems to happen pretty frequently.

SetPatternOrDie() [2/2]

void JRegex::SetPatternOrDie

(

const JUtf8Byte *

pattern

)

SetSingleLine()

void JRegex::SetSingleLine ( const bool  yesNo = true )

inline

Controls whether the entire string is considered a single line or whether newlines are considered to indicate line boundaries (the default). This option is independent of SetLineBegin() and SetLineEnd().

Performance note: changing this option can cause a recompile before the next match.

SetUtf8()

void JRegex::SetUtf8 ( const bool  yesNo = true )

inline

Controls whether the string is treated as utf-8 or raw bytes.

Friends And Related Symbol Documentation

JStringIterator

friend class JStringIterator

friend

JSubstitute

friend class JSubstitute

friend

Member Data Documentation

kError

const JUtf8Byte * JRegex::kError = "Error::JRegex"

static

---

The documentation for this class was generated from the following files:

• libjcore/code/JRegex.h
• libjcore/code/JRegex.cpp