X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/23324ae1c7938ba904770fc456d3c07764b9c5e9..de536319f16406adf967003637b2655c61f6cb09:/interface/wxcrt.h diff --git a/interface/wxcrt.h b/interface/wxcrt.h index ba023ef432..f30ed8982c 100644 --- a/interface/wxcrt.h +++ b/interface/wxcrt.h @@ -1,105 +1,123 @@ ///////////////////////////////////////////////////////////////////////////// - // Name: wxcrt.h - // Purpose: documentation for global functions - // Author: wxWidgets team - // RCS-ID: $Id$ - // Licence: wxWindows license - ///////////////////////////////////////////////////////////////////////////// - - /** - Returns a negative value, 0, or positive value if @e p1 is less than, equal - to or greater than @e p2. The comparison is case-sensitive. - - This function complements the standard C function @e stricmp() which performs - case-insensitive comparison. +// Name: wxcrt.h +// Purpose: interface of global functions +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** @ingroup group_funcmacro_string */ +//@{ + +/** + @return @true if the pointer is either @NULL or points to an empty string, + @false otherwise. + + @header{wx/wxcrt.h} +*/ +bool wxIsEmpty(const char* p); + +/** + This is a safe version of standard function @e strlen(): it does exactly + the same thing (i.e. returns the length of the string) except that it + returns 0 if @a p is the @NULL pointer. + + @header{wx/wxcrt.h} +*/ +size_t wxStrlen(const char* p); + +/** + 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. + + @header{wx/wxcrt.h} */ -int wxStrcmp(const char * p1, const char * p2); +int wxStrcmp(const char* p1, const char* p2); + +/** + This function complements the standard C function @e strcmp() which performs + 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. + + @header{wx/wxcrt.h} +*/ +int wxStricmp(const char* p1, const char* p2); + +/** + @deprecated Use wxString instead. + This macro is defined as: - /** - @b NB: This function is obsolete, use wxString instead. - - A macro defined as: @code #define wxStringEq(s1, s2) (s1 && s2 && (strcmp(s1, s2) == 0)) @endcode + + @header{wx/wxcrt.h} */ bool wxStringEq(const wxString& s1, const wxString& s2); /** - @b NB: This function is obsolete, use wxString::Find instead. - - Returns @true if the substring @e s1 is found within @e s2, - ignoring case if @e exact is @false. If @e subString is @false, - no substring matching is done. + @deprecated Use wxString::Find() instead. + + Returns @true if the substring @a s1 is found within @a s2, ignoring case + if @a exact is @false. If @a subString is @false, no substring matching is + done. + + @header{wx/wxcrt.h} */ bool wxStringMatch(const wxString& s1, const wxString& s2, - bool subString = @true, - bool exact = @false); + bool subString = true, bool exact = false); /** - This function replaces the dangerous standard function @c sprintf() and is - like @c snprintf() available on some platforms. The only difference with - sprintf() is that an additional argument - buffer size - is taken and the - buffer is never overflowed. - - Returns the number of characters copied to the buffer or -1 if there is not - enough space. - - @sa wxVsnprintf, wxString::Printf -*/ -int wxSnprintf(wxChar * buf, size_t len, const wxChar * format, - ...); + This is a convenience function wrapping wxStringTokenizer which simply + returns all tokens found in the given @a string in an array. -/** - This is a convenience function wrapping - wxStringTokenizer which simply returns all tokens - found in the given @e str in an array. - - Please see - wxStringTokenizer::wxStringTokenizer - for the description of the other parameters. + Please see wxStringTokenizer::wxStringTokenizer() for a description of the + other parameters. + + @header{wx/wxcrt.h} */ -wxArrayString wxStringTokenize(const wxString& str, +wxArrayString wxStringTokenize(const wxString& string, const wxString& delims = wxDEFAULT_DELIMITERS, wxStringTokenizerMode mode = wxTOKEN_DEFAULT); /** - This is a safe version of standard function @e strlen(): it does exactly the - same thing (i.e. returns the length of the string) except that it returns 0 if - @e p is the @NULL pointer. -*/ -size_t wxStrlen(const char * p); + This function replaces the dangerous standard function @e sprintf() and is + like @e snprintf() available on some platforms. The only difference with + @e sprintf() is that an additional argument - buffer size - is taken and + the buffer is never overflowed. -/** - The same as wxSnprintf but takes a @c va_list - argument instead of arbitrary number of parameters. - - Note that if @c wxUSE_PRINTF_POS_PARAMS is set to 1, then this function supports - positional arguments (see wxString::Printf for more information). - However other functions of the same family (wxPrintf, wxSprintf, wxFprintf, - wxVfprintf, - wxVfprintf, wxVprintf, wxVsprintf) currently do not to support positional - parameters - even when @c wxUSE_PRINTF_POS_PARAMS is 1. - - @sa wxSnprintf, wxString::PrintfV -*/ -int wxVsnprintf(wxChar * buf, size_t len, const wxChar * format, - va_list argPtr); + Returns the number of characters copied to the buffer or -1 if there is not + enough space. -/** - Returns @true if the pointer is either @NULL or points to an empty - string, @false otherwise. + @see wxVsnprintf(), wxString::Printf() + + @header{wx/wxcrt.h} */ -bool wxIsEmpty(const char * p); +int wxSnprintf(wxChar* buf, size_t len, const wxChar* format, ...); /** - Returns a negative value, 0, or positive value if @e p1 is less than, equal - to or greater than @e p2. The comparison is case-insensitive. - - This function complements the standard C function @e strcmp() which performs - case-sensitive comparison. + The same as wxSnprintf() but takes a @c va_list argument instead of an + arbitrary number of parameters. + + @note If @c wxUSE_PRINTF_POS_PARAMS is set to 1, then this function + supports positional arguments (see wxString::Printf() for more + information). However other functions of the same family (wxPrintf(), + wxSprintf(), wxFprintf(), wxVfprintf(), wxVfprintf(), wxVprintf(), + wxVsprintf()) currently do not to support positional parameters even + when @c wxUSE_PRINTF_POS_PARAMS is 1. + + @see wxSnprintf(), wxString::PrintfV() + + @header{wx/wxcrt.h} */ -int wxStricmp(const char * p1, const char * p2); +int wxVsnprintf(wxChar* buf, size_t len, + const wxChar* format, va_list argPtr); + +//@}