wxString::Format() added

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

docs/latex/wx/wxstring.tex

@@ -152,8 +152,22 @@ converted to a number.
 \membersection{Writing values into the string}
 
 Both formatted versions (\helpref{Printf}{wxstringprintf}) and stream-like
-insertion operators exist (for basic types only).
+insertion operators exist (for basic types only). Additionally, the 
+\helpref{Format}{wxstringformat} function allows to use simply append
+formatted value to a string:
 
+\begin{verbatim}
+    // the following 2 snippets are equivalent
+
+    wxString s = "...";
+    s += wxString::Format("%d", n);
+
+    wxString s;
+    s.Printf("...%d", n);
+\end{verbatim}
+
+\helpref{Format}{wxstringformat}\\
+\helpref{FormatV}{wxstringformatv}\\
 \helpref{Printf}{wxstringprintf}\\
 \helpref{PrintfV}{wxstringprintfv}\\
 \helpref{operator \cinsert}{wxstringoperatorout}
@@ -559,6 +573,28 @@ Searches for the given string. Returns the starting index, or -1 if not found.
 
 Returns the first occurrence of the item.
 
+\membersection{wxString::Format}\label{wxstringformat}
+
+\func{static wxString}{Format}{\param{const wxChar }{*format}, \param{}{...}}
+
+This static function returns the string containing the result of calling 
+\helpref{Printf}{wxstringprintf} with the passed parameters on it.
+
+\wxheading{See also}
+
+\helpref{FormatV}{wxstringformatv}, \helpref{Printf}{wxstringprintf}
+
+\membersection{wxString::FormatV}\label{wxstringformatv}
+
+\func{static wxString}{Format}{\param{const wxChar }{*format}, \param{va\_list }{argptr}}
+
+This static function returns the string containing the result of calling 
+\helpref{PrintfV}{wxstringprintfv} with the passed parameters on it.
+
+\wxheading{See also}
+
+\helpref{Format}{wxstringformat}, \helpref{PrintfV}{wxstringprintfv}
+
 \membersection{wxString::Freq}\label{wxstringfreq}
 
 \constfunc{int}{Frec}{\param{char }{ch}}

include/wx/string.h

@@ -630,6 +630,11 @@ public:
     // as vprintf(), returns the number of characters written or < 0 on error
   int PrintfV(const wxChar* pszFormat, va_list argptr);
 
+    // returns the string containing the result of Printf() to it
+  static wxString Format(const wxChar *pszFormat, ...);
+    // the same as above, but takes a va_list
+  static wxString FormatV(const wxChar *pszFormat, va_list argptr);
+
   // raw access to string memory
     // ensure that string has space for at least nLen characters
     // only works if the data of this string is not shared

src/common/string.cpp

@@ -1102,6 +1102,27 @@ wxString& wxString::operator<<(double d)
 // formatted output
 // ---------------------------------------------------------------------------
 
+/* static */
+wxString wxString::Format(const wxChar *pszFormat, ...)
+{
+  va_list argptr;
+  va_start(argptr, pszFormat);
+
+  wxString s = FormatV(pszFormat, argptr);
+
+  va_end(argptr);
+
+  return s;
+}
+
+/* static */
+wxString wxString::FormatV(const wxChar *pszFormat, va_list argptr)
+{
+    wxString s;
+    s.Printf(pszFormat, argptr);
+    return s;
+}
+
 int wxString::Printf(const wxChar *pszFormat, ...)
 {
   va_list argptr;