added and documented wxString::StartsWith()

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/branches/WX_2_2_BRANCH@7197 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

docs/latex/wx/wxstring.tex

@@ -93,16 +93,22 @@ insensitive comparisons you should use \helpref{CmpNoCase}{wxstringcmpnocase} or
 give a second parameter to IsSameAs. This last function is may be more
 convenient if only equality of the strings matters because it returns a boolean
 true value if the strings are the same and not 0 (which is usually FALSE in C)
-as Cmp does.
+as {\tt Cmp()} does.
 
 \helpref{Matches}{wxstringmatches} is a poor man's regular expression matcher:
 it only understands '*' and '?' metacharacters in the sense of DOS command line
 interpreter.
 
+\helpref{StartsWith}{wxstringstartswith} is helpful when parsing a line of
+text which should start with some predefined prefix and is more efficient than
+doing direct string comparaison as you would also have to precalculate the
+length of the prefix then.
+
 \helpref{Cmp}{wxstringcmp}\\
 \helpref{CmpNoCase}{wxstringcmpnocase}\\
 \helpref{IsSameAs}{wxstringissameas}\\
-\helpref{Matches}{wxstringmatches}
+\helpref{Matches}{wxstringmatches}\\
+\helpref{StartsWith}{wxstringstartswith}
 
 \membersection{Substring extraction}
 
@@ -117,7 +123,8 @@ substring.
 \helpref{BeforeFirst}{wxstringbeforefirst}\\
 \helpref{BeforeLast}{wxstringbeforelast}\\
 \helpref{AfterFirst}{wxstringafterfirst}\\
-\helpref{AfterLast}{wxstringafterlast}
+\helpref{AfterLast}{wxstringafterlast}\\
+\helpref{StartsWith}{wxstringstartswith}
 
 \membersection{Case conversion}
 
@@ -869,6 +876,16 @@ Minimizes the string's memory. This can be useful after a call to
 
 The same as Printf.
 
+\membersection{wxString::StartsWith}\label{wxstringstartswith}
+
+\constfunc{bool}{StartsWith}{\param{const wxChar }{*prefix}, \param{wxString }{*rest = NULL}}
+
+This function can be used to test if the string starts with the specified 
+{\it prefix}. If it does, the function will return {\tt TRUE} and put the rest
+of the string (i.e. after the prefix) into {\it rest} string if it is not 
+{\tt NULL}. Otherwise, the function returns {\tt FALSE} and doesn't modify the 
+{\it rest}.
+
 \membersection{wxString::Strip}\label{wxstringstrip}
 
 \begin{verbatim}

include/wx/string.h

@@ -602,6 +602,11 @@ public:
   wxString  operator()(size_t start, size_t len) const
     { return Mid(start, len); }
 
+      // check that the tring starts with prefix and return the rest of the
+      // string in the provided pointer if it is not NULL, otherwise return
+      // FALSE
+  bool StartsWith(const wxChar *prefix, wxString *rest = NULL) const;
+
       // get first nCount characters
   wxString Left(size_t nCount) const;
       // get last nCount characters

samples/console/console.cpp

@@ -2408,6 +2408,32 @@ static void TestStringSub()
     printf("substr(3, 5) = '%s'\n", s.substr(3, 5).c_str());
     printf("substr(3) = '%s'\n", s.substr(3).c_str());
 
+    static const wxChar *prefixes[] =
+    {
+        _T("Hello"),
+        _T("Hello, "),
+        _T("Hello, world!"),
+        _T("Hello, world!!!"),
+        _T(""),
+        _T("Goodbye"),
+        _T("Hi"),
+    };
+
+    for ( size_t n = 0; n < WXSIZEOF(prefixes); n++ )
+    {
+        wxString prefix = prefixes[n], rest;
+        bool rc = s.StartsWith(prefix, &rest);
+        printf("StartsWith('%s') = %s", prefix.c_str(), rc ? "TRUE" : "FALSE");
+        if ( rc )
+        {
+            printf(" (the rest is '%s')\n", rest.c_str());
+        }
+        else
+        {
+            putchar('\n');
+        }
+    }
+
     puts("");
 }
 
@@ -2688,15 +2714,15 @@ int main(int argc, char **argv)
         TestPChar();
         TestString();
     }
+        TestStringSub();
     if ( 0 )
     {
         TestStringConstruction();
-        TestStringSub();
         TestStringFormat();
         TestStringFind();
         TestStringTokenizer();
-    }
         TestStringReplace();
+    }
 #endif // TEST_STRINGS
 
 #ifdef TEST_ARRAYS

src/common/string.cpp

@@ -776,6 +776,35 @@ wxString wxString::Mid(size_t nFirst, size_t nCount) const
   return dest;
 }
 
+// check that the tring starts with prefix and return the rest of the string
+// in the provided pointer if it is not NULL, otherwise return FALSE
+bool wxString::StartsWith(const wxChar *prefix, wxString *rest) const
+{
+    wxASSERT_MSG( prefix, _T("invalid parameter in wxString::StartsWith") );
+
+    // first check if the beginning of the string matches the prefix: note
+    // that we don't have to check that we don't run out of this string as
+    // when we reach the terminating NUL, either prefix string ends too (and
+    // then it's ok) or we break out of the loop because there is no match
+    const wxChar *p = c_str();
+    while ( *prefix )
+    {
+        if ( *prefix++ != *p++ )
+        {
+            // no match
+            return FALSE;
+        }
+    }
+
+    if ( rest )
+    {
+        // put the rest of the string into provided pointer
+        *rest = p;
+    }
+
+    return TRUE;
+}
+
 // extract nCount last (rightmost) characters
 wxString wxString::Right(size_t nCount) const
 {