add SetCharIncludes and SetCharExcludes utilities to wxTextValidator; use iterators...

[wxWidgets.git] / interface / wx / wxcrt.h

diff --git a/interface/wx/wxcrt.h b/interface/wx/wxcrt.h
index f30ed8982c7291c89f8aa3fa0c70d1509e2fb9cb..e085f0dad5886b6de247d6a7b5d7b90173dd8e2f 100644 (file)
--- a/interface/wx/wxcrt.h
+++ b/interface/wx/wxcrt.h
@@ -1,17 +1,17 @@
 /////////////////////////////////////////////////////////////////////////////
 // Name:        wxcrt.h
-// Purpose:     interface of global functions
+// Purpose:     interface of global CRT wrapper functions
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
-/** @ingroup group_funcmacro_string */
+/** @addtogroup group_funcmacro_string */
 //@{
 
 /**
-    @return @true if the pointer is either @NULL or points to an empty string,
-             @false otherwise.
+    Returns @true if the pointer @a p is either @NULL or points to an empty string,
+    @false otherwise.
 
     @header{wx/wxcrt.h}
 */
@@ -26,12 +26,27 @@ bool wxIsEmpty(const char* p);
 */
 size_t wxStrlen(const char* p);
 
+/**
+    This is a safe version of standard function @e strlen(): it returns the length
+    of the string s in bytes if this length is smaller than @a maxlen bytes.
+    Otherwise it returns @a maxlen.
+
+    The @a maxlen parameter makes it easier to avoid array indexing errors
+    since you are sure that wxStrnlen() won't read any memory exceeding the
+    @c "*(p+maxlen)" location.
+
+    @since 2.9.0
+
+    @header{wx/wxcrt.h}
+*/
+size_t wxStrnlen(const char* p, size_t maxlen);
+
 /**
     This function complements the standard C function @e stricmp() which
     performs case-insensitive comparison.
 
     @return A negative value, 0, or positive value if @a p1 is less than,
-             equal to or greater than @a p2. The comparison is case-sensitive.
+            equal to or greater than @a p2. The comparison is case-sensitive.
 
     @header{wx/wxcrt.h}
 */
@@ -42,14 +57,14 @@ int wxStrcmp(const char* p1, const char* p2);
     case-sensitive comparison.
 
     @return A negative value, 0, or positive value if @a p1 is less than,
-             equal to or greater than @e p2. The comparison is case-insensitive.
+            equal to or greater than @e p2. The comparison is case-insensitive.
 
     @header{wx/wxcrt.h}
 */
 int wxStricmp(const char* p1, const char* p2);
 
 /**
-    @deprecated Use wxString instead.
+    @deprecated Use wxString::operator== instead.
 
     This macro is defined as:
 
@@ -86,6 +101,53 @@ wxArrayString wxStringTokenize(const wxString& string,
                                const wxString& delims = wxDEFAULT_DELIMITERS,
                                wxStringTokenizerMode mode = wxTOKEN_DEFAULT);
 
+/**
+    Safe and more convenient replacement for strncpy().
+
+    This function copies the source string @a src to the destination buffer @a
+    dst of size @a n without overflowing the buffer and ensuring that it is
+    always @NUL-terminated.
+
+    Example of use:
+    @code
+        char buf[256];
+        if ( wxStrlcpy(buf, GetSomeString(), WXSIZEOF(buf)) > WXSIZEOF(buf) )
+            ... handle truncation ...
+    @endcode
+    Notice that using wxStrncpy() in similar way is wrong, the above is broadly
+    equivalent to
+    @code
+        char buf[256];
+        buf[WXSIZEOF(buf) - 1] = '\0';
+        wxStrncpy(buf, GetSomeString(), WXSIZEOF(buf) - 1);
+        if ( buf[WXSIZEOF(buf) - 1] != '\0' )
+        {
+            ... truncation occurred ...
+            // need to NUL-terminate string manually
+            buf[WXSIZEOF(buf) - 1] = '\0';
+        }
+    @endcode
+    which should explain the advantage of using wxStrlcpy().
+
+    Notice that this function is similar to the OpenBSD strlcpy() function.
+
+    @param dst
+        Destination buffer of size (greater or) equal to @a n.
+    @param src
+        @NUL-terminated source string.
+    @param n
+        The size of the destination buffer.
+    @return
+        The length of @a src, if the returned value is greater or equal to @a n
+        then there was not enough space in the destination buffer and the
+        string was truncated.
+
+    @since 2.9.0
+
+    @header{wx/wxcrt.h}
+ */
+size_t wxStrlcpy(char *dst, const char *src, size_t n);
+
 /**
     This function replaces the dangerous standard function @e sprintf() and is
     like @e snprintf() available on some platforms. The only difference with
@@ -99,7 +161,7 @@ wxArrayString wxStringTokenize(const wxString& string,
 
     @header{wx/wxcrt.h}
 */
-int wxSnprintf(wxChar* buf, size_t len, const wxChar* format, ...);
+int wxSnprintf(char* buf, size_t len, const char* format, ...);
 
 /**
     The same as wxSnprintf() but takes a @c va_list argument instead of an
@@ -116,8 +178,7 @@ int wxSnprintf(wxChar* buf, size_t len, const wxChar* format, ...);
 
     @header{wx/wxcrt.h}
 */
-int wxVsnprintf(wxChar* buf, size_t len,
-                const wxChar* format, va_list argPtr);
+int wxVsnprintf(char* buf, size_t len, const char* format, va_list argPtr);
 
 //@}