interface/wx/wxcrt.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        wxcrt.h
   3 // Purpose:     interface of global CRT wrapper functions
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /** @addtogroup group_funcmacro_string */
  10 //@{
  11
  12 /**
  13     Returns @true if the pointer @a p is either @NULL or points to an empty string,
  14     @false otherwise.
  15
  16     @header{wx/wxcrt.h}
  17 */
  18 bool wxIsEmpty(const char* p);
  19
  20 /**
  21     This is a safe version of standard function @e strlen(): it does exactly
  22     the same thing (i.e. returns the length of the string) except that it
  23     returns 0 if @a p is the @NULL pointer.
  24
  25     @header{wx/wxcrt.h}
  26 */
  27 size_t wxStrlen(const char* p);
  28
  29 /**
  30     This is a safe version of standard function @e strlen(): it returns the length
  31     of the string s in bytes if this length is smaller than @a maxlen bytes.
  32     Otherwise it returns @a maxlen.
  33
  34     The @a maxlen parameter makes it easier to avoid array indexing errors
  35     since you are sure that wxStrnlen() won't read any memory exceeding the
  36     @c "*(p+maxlen)" location.
  37
  38     @since 2.9.0
  39
  40     @header{wx/wxcrt.h}
  41 */
  42 size_t wxStrnlen(const char* p, size_t maxlen);
  43
  44 /**
  45     This function complements the standard C function @e stricmp() which
  46     performs case-insensitive comparison.
  47
  48     @return A negative value, 0, or positive value if @a p1 is less than,
  49             equal to or greater than @a p2. The comparison is case-sensitive.
  50
  51     @header{wx/wxcrt.h}
  52 */
  53 int wxStrcmp(const char* p1, const char* p2);
  54
  55 /**
  56     This function complements the standard C function @e strcmp() which performs
  57     case-sensitive comparison.
  58
  59     @return A negative value, 0, or positive value if @a p1 is less than,
  60             equal to or greater than @e p2. The comparison is case-insensitive.
  61
  62     @header{wx/wxcrt.h}
  63 */
  64 int wxStricmp(const char* p1, const char* p2);
  65
  66 /**
  67     @deprecated Use wxString::operator== instead.
  68
  69     This macro is defined as:
  70
  71     @code
  72     #define wxStringEq(s1, s2) (s1 && s2 && (strcmp(s1, s2) == 0))
  73     @endcode
  74
  75     @header{wx/wxcrt.h}
  76 */
  77 bool wxStringEq(const wxString& s1, const wxString& s2);
  78
  79 /**
  80     @deprecated Use wxString::Find() instead.
  81
  82     Returns @true if the substring @a s1 is found within @a s2, ignoring case
  83     if @a exact is @false. If @a subString is @false, no substring matching is
  84     done.
  85
  86     @header{wx/wxcrt.h}
  87 */
  88 bool wxStringMatch(const wxString& s1, const wxString& s2,
  89                    bool subString = true, bool exact = false);
  90
  91 /**
  92     This is a convenience function wrapping wxStringTokenizer which simply
  93     returns all tokens found in the given @a string in an array.
  94
  95     Please see wxStringTokenizer::wxStringTokenizer() for a description of the
  96     other parameters.
  97
  98     @header{wx/wxcrt.h}
  99 */
 100 wxArrayString wxStringTokenize(const wxString& string,
 101                                const wxString& delims = wxDEFAULT_DELIMITERS,
 102                                wxStringTokenizerMode mode = wxTOKEN_DEFAULT);
 103
 104 /**
 105     Safe and more convenient replacement for strncpy().
 106
 107     This function copies the source string @a src to the destination buffer @a
 108     dst of size @a n without overflowing the buffer and ensuring that it is
 109     always @NUL-terminated.
 110
 111     Example of use:
 112     @code
 113         char buf[256];
 114         if ( wxStrlcpy(buf, GetSomeString(), WXSIZEOF(buf)) > WXSIZEOF(buf) )
 115             ... handle truncation ...
 116     @endcode
 117     Notice that using wxStrncpy() in similar way is wrong, the above is broadly
 118     equivalent to
 119     @code
 120         char buf[256];
 121         buf[WXSIZEOF(buf) - 1] = '\0';
 122         wxStrncpy(buf, GetSomeString(), WXSIZEOF(buf) - 1);
 123         if ( buf[WXSIZEOF(buf) - 1] != '\0' )
 124         {
 125             ... truncation occurred ...
 126             // need to NUL-terminate string manually
 127             buf[WXSIZEOF(buf) - 1] = '\0';
 128         }
 129     @endcode
 130     which should explain the advantage of using wxStrlcpy().
 131
 132     Notice that this function is similar to the OpenBSD strlcpy() function.
 133
 134     @param dst
 135         Destination buffer of size (greater or) equal to @a n.
 136     @param src
 137         @NUL-terminated source string.
 138     @param n
 139         The size of the destination buffer.
 140     @return
 141         The length of @a src, if the returned value is greater or equal to @a n
 142         then there was not enough space in the destination buffer and the
 143         string was truncated.
 144
 145     @since 2.9.0
 146
 147     @header{wx/wxcrt.h}
 148  */
 149 size_t wxStrlcpy(char *dst, const char *src, size_t n);
 150
 151 /**
 152     This function replaces the dangerous standard function @e sprintf() and is
 153     like @e snprintf() available on some platforms. The only difference with
 154     @e sprintf() is that an additional argument - buffer size - is taken and
 155     the buffer is never overflowed.
 156
 157     Returns the number of characters copied to the buffer or -1 if there is not
 158     enough space.
 159
 160     @see wxVsnprintf(), wxString::Printf()
 161
 162     @header{wx/wxcrt.h}
 163 */
 164 int wxSnprintf(char* buf, size_t len, const char* format, ...);
 165
 166 /**
 167     The same as wxSnprintf() but takes a @c va_list argument instead of an
 168     arbitrary number of parameters.
 169
 170     @note If @c wxUSE_PRINTF_POS_PARAMS is set to 1, then this function
 171           supports positional arguments (see wxString::Printf() for more
 172           information). However other functions of the same family (wxPrintf(),
 173           wxSprintf(), wxFprintf(), wxVfprintf(), wxVfprintf(), wxVprintf(),
 174           wxVsprintf()) currently do not to support positional parameters even
 175           when @c wxUSE_PRINTF_POS_PARAMS is 1.
 176
 177     @see wxSnprintf(), wxString::PrintfV()
 178
 179     @header{wx/wxcrt.h}
 180 */
 181 int wxVsnprintf(char* buf, size_t len, const char* format, va_list argPtr);
 182
 183 //@}
 184