Fix missing documentation for several GDI functions.

[wxWidgets.git] / include / wx / regex.h

diff --git a/include/wx/regex.h b/include/wx/regex.h
index 70443b2964cd853b0b074c9e58c8503b08dabf03..77ed092997277fb793df6661c58e4186d4a852bf 100644 (file)
--- a/include/wx/regex.h
+++ b/include/wx/regex.h
@@ -1,41 +1,38 @@
 ///////////////////////////////////////////////////////////////////////////////
 // Name:        wx/regex.h
 // Purpose:     regular expression matching
 ///////////////////////////////////////////////////////////////////////////////
 // Name:        wx/regex.h
 // Purpose:     regular expression matching

-// Author:      Karsten Ballüder
+// Author:      Karsten Ballueder

 // Modified by: VZ at 13.07.01 (integrated to wxWin)
 // Created:     05.02.2000
 // RCS-ID:      $Id$
 // Modified by: VZ at 13.07.01 (integrated to wxWin)
 // Created:     05.02.2000
 // RCS-ID:      $Id$

-// Copyright:   (c) 2000 Karsten Ballüder <ballueder@gmx.net>
+// Copyright:   (c) 2000 Karsten Ballueder <ballueder@gmx.net>

 // Licence:     wxWindows licence
 ///////////////////////////////////////////////////////////////////////////////
 
 #ifndef _WX_REGEX_H_
 #define _WX_REGEX_H_
 
 // Licence:     wxWindows licence
 ///////////////////////////////////////////////////////////////////////////////
 
 #ifndef _WX_REGEX_H_
 #define _WX_REGEX_H_
 

-#ifdef __GNUG__
-    #pragma interface "regex.h"
-#endif
-

 #include "wx/defs.h"
 
 #if wxUSE_REGEX
 
 #include "wx/defs.h"
 
 #if wxUSE_REGEX
 

+#include "wx/string.h"
+

 // ----------------------------------------------------------------------------
 // constants
 // ----------------------------------------------------------------------------
 
 // ----------------------------------------------------------------------------
 // constants
 // ----------------------------------------------------------------------------
 

-// max number of subexpression matches, the default should be big enough for
-// all uses but may be a bit wasteful
-#ifndef WX_REGEX_MAXMATCHES
-    #define WX_REGEX_MAXMATCHES 1024
-#endif
-

 // flags for regex compilation: these can be used with Compile()
 enum
 {
 // flags for regex compilation: these can be used with Compile()
 enum
 {

-    // use extended regex syntax (default)
+    // use extended regex syntax

     wxRE_EXTENDED = 0,
 
     wxRE_EXTENDED = 0,
 

+    // use advanced RE syntax (built-in regex only)
+#ifdef wxHAS_REGEX_ADVANCED
+    wxRE_ADVANCED = 1,
+#endif
+

     // use basic RE syntax
     wxRE_BASIC    = 2,
 
     // use basic RE syntax
     wxRE_BASIC    = 2,
 


@@ -71,9 +68,9 @@ enum
 // wxRegEx: a regular expression
 // ----------------------------------------------------------------------------
 
 // wxRegEx: a regular expression
 // ----------------------------------------------------------------------------
 

-class WXDLLEXPORT wxRegExImpl;
+class WXDLLIMPEXP_FWD_BASE wxRegExImpl;

 
 

-class WXDLLEXPORT wxRegEx
+class WXDLLIMPEXP_BASE wxRegEx

 {
 public:
     // default ctor: use Compile() later
 {
 public:
     // default ctor: use Compile() later


@@ -86,27 +83,30 @@ public:
         (void)Compile(expr, flags);
     }
 
         (void)Compile(expr, flags);
     }
 

-    // return TRUE if this is a valid compiled regular expression
+    // return true if this is a valid compiled regular expression

     bool IsValid() const { return m_impl != NULL; }
 
     bool IsValid() const { return m_impl != NULL; }
 

-    // compile the string into regular expression, return TRUE if ok or FALSE
+    // compile the string into regular expression, return true if ok or false

     // if string has a syntax error
     bool Compile(const wxString& pattern, int flags = wxRE_DEFAULT);
 
     // matches the precompiled regular expression against a string, return
     // if string has a syntax error
     bool Compile(const wxString& pattern, int flags = wxRE_DEFAULT);
 
     // matches the precompiled regular expression against a string, return

-    // TRUE if matches and FALSE otherwise
+    // true if matches and false otherwise

     //
     // flags may be combination of wxRE_NOTBOL and wxRE_NOTEOL
     //
     // flags may be combination of wxRE_NOTBOL and wxRE_NOTEOL

+    // len may be the length of text (ignored by most system regex libs)

     //
     // may only be called after successful call to Compile()
     //
     // may only be called after successful call to Compile()

-    bool Matches(const wxString& str, int flags = 0) const;
+    bool Matches(const wxString& text, int flags = 0) const;
+    bool Matches(const wxChar *text, int flags, size_t len) const
+        { return Matches(wxString(text, len), flags); }

 
     // get the start index and the length of the match of the expression
     // (index 0) or a bracketed subexpression (index != 0)
     //
     // may only be called after successful call to Matches()
     //
 
     // get the start index and the length of the match of the expression
     // (index 0) or a bracketed subexpression (index != 0)
     //
     // may only be called after successful call to Matches()
     //

-    // return FALSE if no match or on error
+    // return false if no match or on error

     bool GetMatch(size_t *start, size_t *len, size_t index = 0) const;
 
     // return the part of string corresponding to the match, empty string is
     bool GetMatch(size_t *start, size_t *len, size_t index = 0) const;
 
     // return the part of string corresponding to the match, empty string is


@@ -115,10 +115,33 @@ public:
     // may only be called after successful call to Matches()
     wxString GetMatch(const wxString& text, size_t index = 0) const;
 
     // may only be called after successful call to Matches()
     wxString GetMatch(const wxString& text, size_t index = 0) const;
 

+    // return the size of the array of matches, i.e. the number of bracketed
+    // subexpressions plus one for the expression itself, or 0 on error.
+    //
+    // may only be called after successful call to Compile()
+    size_t GetMatchCount() const;
+

     // replaces the current regular expression in the string pointed to by
     // pattern, with the text in replacement and return number of matches
     // replaced (maybe 0 if none found) or -1 on error
     // replaces the current regular expression in the string pointed to by
     // pattern, with the text in replacement and return number of matches
     // replaced (maybe 0 if none found) or -1 on error

-    int Replace(wxString *str, const wxString& replacement) const;
+    //
+    // the replacement text may contain backreferences (\number) which will be
+    // replaced with the value of the corresponding subexpression in the
+    // pattern match
+    //
+    // maxMatches may be used to limit the number of replacements made, setting
+    // it to 1, for example, will only replace first occurrence (if any) of the
+    // pattern in the text while default value of 0 means replace all
+    int Replace(wxString *text, const wxString& replacement,
+                size_t maxMatches = 0) const;
+
+    // replace the first occurrence
+    int ReplaceFirst(wxString *text, const wxString& replacement) const
+        { return Replace(text, replacement, 1); }
+
+    // replace all occurrences: this is actually a synonym for Replace()
+    int ReplaceAll(wxString *text, const wxString& replacement) const
+        { return Replace(text, replacement, 0); }

 
     // dtor not virtual, don't derive from this class
     ~wxRegEx();
 
     // dtor not virtual, don't derive from this class
     ~wxRegEx();


@@ -129,6 +152,11 @@ private:
 
     // the real guts of this class
     wxRegExImpl *m_impl;
 
     // the real guts of this class
     wxRegExImpl *m_impl;

+
+    // as long as the class wxRegExImpl is not ref-counted,
+    // instances of the handle wxRegEx must not be copied.
+    wxRegEx(const wxRegEx&);
+    wxRegEx &operator=(const wxRegEx&);

 };
 
 #endif // wxUSE_REGEX
 };
 
 #endif // wxUSE_REGEX