string functions

::copystring
::wxgettranslation
::wxisempty
::wxstrcmp
::wxstricmp
::wxstringeq
::wxstringmatch
::wxstringtokenize
::wxstrlen
::wxsnprintf
wxt
wxtranslate
::wxvsnprintf
_
wxplural
_t

::copystring

char * copystring(const char *s)

makes a copy of the string s using the c++ new operator, so it can be deleted with the delete operator.

this function is deprecated, use wxstring class instead.

::wxgettranslation

const wxchar * wxgettranslation(const wxchar* str, const wxchar* domain = null)

const wxchar * wxgettranslation(const wxchar* str, const wxchar* strplural, size_t n, const wxchar* domain = null)

this function returns the translation of string str in the current locale. if the string is not found in any of the loaded message catalogs (see internationalization overview), the original string is returned. in debug build, an error message is logged -- this should help to find the strings which were not yet translated. if domain is specified then only that domain/catalog is searched for a matching string. as this function is used very often, an alternative (and also common in unix world) syntax is provided: the _() macro is defined to do the same thing as wxgettranslation.

the second form is used when retrieving translation of string that has different singular and plural form in english or different plural forms in some other language. it takes two extra arguments: as above, str parameter must contain the singular form of the string to be converted and is used as the key for the search in the catalog. the strplural parameter is the plural form (in english). the parameter n is used to determine the plural form. if no message catalog is found str is returned if 'n == 1', otherwise strplural.

see gnu gettext manual for additional information on plural forms handling. for a shorter alternative see the wxplural() macro.

both versions call wxlocale::getstring.

note that this function is not suitable for literal strings in unicode builds, since the literal strings must be enclosed into _t() or wxt macro which makes them unrecognised by xgettext, and so they are not extracted to the message catalog. instead, use the _() and wxplural macro for all literal strings.

::wxisempty

bool wxisempty(const char * p)

returns true if the pointer is either null or points to an empty string, false otherwise.

::wxstrcmp

int wxstrcmp(const char *p1, const char *p2)

returns a negative value, 0, or positive value if p1 is less than, equal to or greater than p2. the comparison is case-sensitive.

this function complements the standard c function stricmp() which performs case-insensitive comparison.

::wxstricmp

int wxstricmp(const char *p1, const char *p2)

returns a negative value, 0, or positive value if p1 is less than, equal to or greater than p2. the comparison is case-insensitive.

this function complements the standard c function strcmp() which performs case-sensitive comparison.

::wxstringeq

bool wxstringeq(const wxstring& s1, const wxstring& s2)

nb: this function is obsolete, use wxstring instead.

a macro defined as:

#define wxstringeq(s1, s2) (s1 && s2 && (strcmp(s1, s2) == 0))

::wxstringmatch

bool wxstringmatch(const wxstring& s1, const wxstring& s2,
bool substring = true, bool exact = false)

nb: this function is obsolete, use wxstring::find instead.

returns true if the substring s1 is found within s2, ignoring case if exact is false. if substring is false, no substring matching is done.

::wxstringtokenize

wxarraystring wxstringtokenize(const wxstring& str,
const wxstring& delims = wxdefault_delimiters,
wxstringtokenizermode mode = wxtoken_default)

this is a convenience function wrapping wxstringtokenizer which simply returns all tokens found in the given str in an array.

please see wxstringtokenizer::wxstringtokenizer for the description of the other parameters.

::wxstrlen

size_t wxstrlen(const char * p)

this is a safe version of standard function strlen(): it does exactly the same thing (i.e. returns the length of the string) except that it returns 0 if p is the null pointer.

::wxsnprintf

int wxsnprintf(wxchar *buf, size_t len, const wxchar *format, ...)

this function replaces the dangerous standard function sprintf() and is like 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.

see also

wxvsnprintf, wxstring::printf

wxt

wxchar wxt(char ch)

const wxchar * wxt(const char *s)

wxt() is a macro which can be used with character and string literals (in other words, 'x' or "foo") to automatically convert them to unicode in unicode build configuration. please see the unicode overview for more information.

this macro is simply returns the value passed to it without changes in ascii build. in fact, its definition is:

#ifdef unicode
#define wxt(x) l ## x
#else // !unicode
#define wxt(x) x
#endif

wxtranslate

const wxchar * wxtranslate(const char *s)

this macro doesn't do anything in the program code -- it simply expands to the value of its argument (except in unicode build where it is equivalent to wxt which makes it unnecessary to use both wxtranslate and wxt with the same string which would be really unreadable).

however it does have a purpose and it is to mark the literal strings for the extraction into the message catalog created by xgettext program. usually this is achieved using _() but that macro not only marks the string for extraction but also expands into a wxgettranslation function call which means that it cannot be used in some situations, notably for static array initialization.

here is an example which should make it more clear: suppose that you have a static array of strings containing the weekday names and which have to be translated (note that it is a bad example, really, as wxdatetime already can be used to get the localized week day names already). if you write

static const wxchar * const weekdays[] = { _("mon"), ..., _("sun") };
...
// use weekdays[n] as usual

static const wxchar * const weekdays[] = { wxtranslate("mon"), ..., wxtranslate("sun") };
...
// use wxgettranslation(weekdays[n])

note that although the code would compile if you simply omit wxtranslate() in the above, it wouldn't work as expected because there would be no translations for the weekday names in the program message catalog and wxgettranslation wouldn't find them.

::wxvsnprintf

int wxvsnprintf(wxchar *buf, size_t len, const wxchar *format, va_list argptr)

the same as wxsnprintf but takes a va_list argument instead of arbitrary number of parameters.

note that if 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 wxuse_printf_pos_params is 1.

see also

wxsnprintf, wxstring::printfv

_

const wxchar * _(const char *s)

this macro expands into a call to wxgettranslation function, so it marks the message for the extraction by xgettext just as wxtranslate does, but also returns the translation of the string for the current locale during execution.

don't confuse this macro with _t()!

wxplural

const wxchar * wxplural(const char *sing, const char *plur, size_tn)

this macro is identical to _() but for the plural variant of wxgettranslation.

_t

wxchar _t(char ch)

const wxchar * _t(const wxchar ch)

this macro is exactly the same as wxt and is defined in wxwidgets simply because it may be more intuitive for windows programmers as the standard win32 headers also define it (as well as yet another name for the same macro which is _text()).

don't confuse this macro with _()!