FreeRDP
string.h File Reference
#include <wchar.h>
#include <string.h>
#include <winpr/winpr.h>
#include <winpr/wtypes.h>

Macros

#define CSTR_LESS_THAN   1
 
#define CSTR_EQUAL   2
 
#define CSTR_GREATER_THAN   3
 
#define CP_ACP   0
 
#define CP_OEMCP   1
 
#define CP_MACCP   2
 
#define CP_THREAD_ACP   3
 
#define CP_SYMBOL   42
 
#define CP_UTF7   65000
 
#define CP_UTF8   65001
 
#define MB_PRECOMPOSED   0x00000001
 
#define MB_COMPOSITE   0x00000002
 
#define MB_USEGLYPHCHARS   0x00000004
 
#define MB_ERR_INVALID_CHARS   0x00000008
 
#define CharUpper   CharUpperA
 
#define CharUpperBuff   CharUpperBuffA
 
#define CharLower   CharLowerA
 
#define CharLowerBuff   CharLowerBuffA
 
#define IsCharAlpha   IsCharAlphaA
 
#define IsCharAlphaNumeric   IsCharAlphaNumericA
 
#define IsCharUpper   IsCharUpperA
 
#define IsCharLower   IsCharLowerA
 
#define lstrlen   lstrlenA
 
#define lstrcmp   lstrcmpA
 
#define sprintf_s   snprintf
 
#define _snprintf   snprintf
 
#define _scprintf(...)   snprintf(NULL, 0, __VA_ARGS__)
 
#define _scprintf(...)   snprintf(NULL, 0, __VA_ARGS__)
 

Functions

WINPR_API char * _strdup (const char *strSource)
 
WINPR_API WCHAR * _wcsdup (const WCHAR *strSource)
 
WINPR_API int _stricmp (const char *string1, const char *string2)
 
WINPR_API int _strnicmp (const char *string1, const char *string2, size_t count)
 
WINPR_API int _wcscmp (const WCHAR *string1, const WCHAR *string2)
 
WINPR_API size_t _wcslen (const WCHAR *str)
 
WINPR_API size_t _wcsnlen (const WCHAR *str, size_t maxNumberOfElements)
 
WINPR_API WCHAR * _wcschr (const WCHAR *str, WCHAR c)
 
WINPR_API WCHAR * _wcsrchr (const WCHAR *str, WCHAR c)
 
WINPR_API char * strtok_s (char *strToken, const char *strDelimit, char **context)
 
WINPR_API WCHAR * wcstok_s (WCHAR *strToken, const WCHAR *strDelimit, WCHAR **context)
 
WINPR_API LPSTR CharUpperA (LPSTR lpsz)
 
WINPR_API LPWSTR CharUpperW (LPWSTR lpsz)
 
WINPR_API DWORD CharUpperBuffA (LPSTR lpsz, DWORD cchLength)
 
WINPR_API DWORD CharUpperBuffW (LPWSTR lpsz, DWORD cchLength)
 
WINPR_API LPSTR CharLowerA (LPSTR lpsz)
 
WINPR_API LPWSTR CharLowerW (LPWSTR lpsz)
 
WINPR_API DWORD CharLowerBuffA (LPSTR lpsz, DWORD cchLength)
 
WINPR_API DWORD CharLowerBuffW (LPWSTR lpsz, DWORD cchLength)
 
WINPR_API BOOL IsCharAlphaA (CHAR ch)
 
WINPR_API BOOL IsCharAlphaW (WCHAR ch)
 
WINPR_API BOOL IsCharAlphaNumericA (CHAR ch)
 
WINPR_API BOOL IsCharAlphaNumericW (WCHAR ch)
 
WINPR_API BOOL IsCharUpperA (CHAR ch)
 
WINPR_API BOOL IsCharUpperW (WCHAR ch)
 
WINPR_API BOOL IsCharLowerA (CHAR ch)
 
WINPR_API BOOL IsCharLowerW (WCHAR ch)
 
WINPR_API int lstrlenA (LPCSTR lpString)
 
WINPR_API int lstrlenW (LPCWSTR lpString)
 
WINPR_API int lstrcmpA (LPCSTR lpString1, LPCSTR lpString2)
 
WINPR_API int lstrcmpW (LPCWSTR lpString1, LPCWSTR lpString2)
 
WINPR_API int MultiByteToWideChar (UINT CodePage, DWORD dwFlags, LPCSTR lpMultiByteStr, int cbMultiByte, LPWSTR lpWideCharStr, int cchWideChar)
 
WINPR_API int WideCharToMultiByte (UINT CodePage, DWORD dwFlags, LPCWSTR lpWideCharStr, int cchWideChar, LPSTR lpMultiByteStr, int cbMultiByte, LPCSTR lpDefaultChar, LPBOOL lpUsedDefaultChar)
 
WINPR_API int ConvertToUnicode (UINT CodePage, DWORD dwFlags, LPCSTR lpMultiByteStr, int cbMultiByte, LPWSTR *lpWideCharStr, int cchWideChar)
 
WINPR_API int ConvertFromUnicode (UINT CodePage, DWORD dwFlags, LPCWSTR lpWideCharStr, int cchWideChar, LPSTR *lpMultiByteStr, int cbMultiByte, LPCSTR lpDefaultChar, LPBOOL lpUsedDefaultChar)
 
WINPR_API void ByteSwapUnicode (WCHAR *wstr, int length)
 
WINPR_API int ConvertLineEndingToLF (char *str, int size)
 
WINPR_API char * ConvertLineEndingToCRLF (const char *str, int *size)
 
WINPR_API char * StrSep (char **stringp, const char *delim)
 
WINPR_API INT64 GetLine (char **lineptr, size_t *size, FILE *stream)
 

Macro Definition Documentation

#define _scprintf (   ...)    snprintf(NULL, 0, __VA_ARGS__)
#define _scprintf (   ...)    snprintf(NULL, 0, __VA_ARGS__)
#define _snprintf   snprintf
#define CharLower   CharLowerA
#define CharLowerBuff   CharLowerBuffA
#define CharUpper   CharUpperA
#define CharUpperBuff   CharUpperBuffA
#define CP_ACP   0
#define CP_MACCP   2
#define CP_OEMCP   1
#define CP_SYMBOL   42
#define CP_THREAD_ACP   3
#define CP_UTF7   65000
#define CP_UTF8   65001
#define CSTR_EQUAL   2
#define CSTR_GREATER_THAN   3
#define CSTR_LESS_THAN   1

WinPR: Windows Portable Runtime String Manipulation (CRT)

Copyright 2012 Marc-Andre Moreau marca.nosp@m.ndre.nosp@m..more.nosp@m.au@g.nosp@m.mail..nosp@m.com Copyright 2016 David PHAM-VAN d.pha.nosp@m.mvan.nosp@m.@inuv.nosp@m.ika..nosp@m.com

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

#define IsCharAlpha   IsCharAlphaA
#define IsCharAlphaNumeric   IsCharAlphaNumericA
#define IsCharLower   IsCharLowerA
#define IsCharUpper   IsCharUpperA
#define lstrcmp   lstrcmpA
#define lstrlen   lstrlenA
#define MB_COMPOSITE   0x00000002
#define MB_ERR_INVALID_CHARS   0x00000008
#define MB_PRECOMPOSED   0x00000001
#define MB_USEGLYPHCHARS   0x00000004
#define sprintf_s   snprintf

Function Documentation

WINPR_API char* _strdup ( const char *  strSource)
WINPR_API int _stricmp ( const char *  string1,
const char *  string2 
)

Here is the caller graph for this function:

WINPR_API int _strnicmp ( const char *  string1,
const char *  string2,
size_t  count 
)

Here is the caller graph for this function:

WINPR_API WCHAR* _wcschr ( const WCHAR *  str,
WCHAR  c 
)

Here is the caller graph for this function:

WINPR_API int _wcscmp ( const WCHAR *  string1,
const WCHAR *  string2 
)

Here is the caller graph for this function:

WINPR_API WCHAR* _wcsdup ( const WCHAR *  strSource)

Here is the caller graph for this function:

WINPR_API size_t _wcslen ( const WCHAR *  str)

Here is the caller graph for this function:

WINPR_API size_t _wcsnlen ( const WCHAR *  str,
size_t  maxNumberOfElements 
)

Here is the caller graph for this function:

WINPR_API WCHAR* _wcsrchr ( const WCHAR *  str,
WCHAR  c 
)

Here is the caller graph for this function:

WINPR_API void ByteSwapUnicode ( WCHAR *  wstr,
int  length 
)

Swap Unicode byte order (UTF16LE <-> UTF16BE)

Here is the call graph for this function:

Here is the caller graph for this function:

WINPR_API LPSTR CharLowerA ( LPSTR  lpsz)
WINPR_API DWORD CharLowerBuffA ( LPSTR  lpsz,
DWORD  cchLength 
)
WINPR_API DWORD CharLowerBuffW ( LPWSTR  lpsz,
DWORD  cchLength 
)
WINPR_API LPWSTR CharLowerW ( LPWSTR  lpsz)
WINPR_API LPSTR CharUpperA ( LPSTR  lpsz)

Here is the caller graph for this function:

WINPR_API DWORD CharUpperBuffA ( LPSTR  lpsz,
DWORD  cchLength 
)

Here is the caller graph for this function:

WINPR_API DWORD CharUpperBuffW ( LPWSTR  lpsz,
DWORD  cchLength 
)

Here is the caller graph for this function:

WINPR_API LPWSTR CharUpperW ( LPWSTR  lpsz)
WINPR_API int ConvertFromUnicode ( UINT  CodePage,
DWORD  dwFlags,
LPCWSTR  lpWideCharStr,
int  cchWideChar,
LPSTR *  lpMultiByteStr,
int  cbMultiByte,
LPCSTR  lpDefaultChar,
LPBOOL  lpUsedDefaultChar 
)

ConvertFromUnicode is a convenience wrapper for WideCharToMultiByte:

If the lpMultiByteStr parameter for the converted string points to NULL or if the cbMultiByte parameter is set to 0 this function will automatically allocate the required memory which is guaranteed to be null-terminated after the conversion, even if the source unicode string isn't.

If the cchWideChar parameter is set to -1 the passed lpWideCharStr must be null-terminated and the required length for the converted string will be calculated accordingly.

Here is the call graph for this function:

WINPR_API char* ConvertLineEndingToCRLF ( const char *  str,
int *  size 
)

Here is the caller graph for this function:

WINPR_API int ConvertLineEndingToLF ( char *  str,
int  size 
)

Here is the caller graph for this function:

WINPR_API int ConvertToUnicode ( UINT  CodePage,
DWORD  dwFlags,
LPCSTR  lpMultiByteStr,
int  cbMultiByte,
LPWSTR *  lpWideCharStr,
int  cchWideChar 
)

ConvertToUnicode is a convenience wrapper for MultiByteToWideChar:

If the lpWideCharStr parameter for the converted string points to NULL or if the cchWideChar parameter is set to 0 this function will automatically allocate the required memory which is guaranteed to be null-terminated after the conversion, even if the source c string isn't.

If the cbMultiByte parameter is set to -1 the passed lpMultiByteStr must be null-terminated and the required length for the converted string will be calculated accordingly.

Here is the call graph for this function:

WINPR_API INT64 GetLine ( char **  lineptr,
size_t *  size,
FILE *  stream 
)

Here is the caller graph for this function:

WINPR_API BOOL IsCharAlphaA ( CHAR  ch)
WINPR_API BOOL IsCharAlphaNumericA ( CHAR  ch)
WINPR_API BOOL IsCharAlphaNumericW ( WCHAR  ch)
WINPR_API BOOL IsCharAlphaW ( WCHAR  ch)
WINPR_API BOOL IsCharLowerA ( CHAR  ch)
WINPR_API BOOL IsCharLowerW ( WCHAR  ch)
WINPR_API BOOL IsCharUpperA ( CHAR  ch)
WINPR_API BOOL IsCharUpperW ( WCHAR  ch)
WINPR_API int lstrcmpA ( LPCSTR  lpString1,
LPCSTR  lpString2 
)
WINPR_API int lstrcmpW ( LPCWSTR  lpString1,
LPCWSTR  lpString2 
)

Here is the caller graph for this function:

WINPR_API int lstrlenA ( LPCSTR  lpString)

Here is the caller graph for this function:

WINPR_API int lstrlenW ( LPCWSTR  lpString)

Here is the caller graph for this function:

WINPR_API int MultiByteToWideChar ( UINT  CodePage,
DWORD  dwFlags,
LPCSTR  lpMultiByteStr,
int  cbMultiByte,
LPWSTR  lpWideCharStr,
int  cchWideChar 
)

Notes on cross-platform Unicode portability:

Unicode has many possible Unicode Transformation Format (UTF) encodings, where some of the most commonly used are UTF-8, UTF-16 and sometimes UTF-32.

The number in the UTF encoding name (8, 16, 32) refers to the number of bits per code unit. A code unit is the minimal bit combination that can represent a unit of encoded text in the given encoding. For instance, UTF-8 encodes the English alphabet using 8 bits (or one byte) each, just like in ASCII.

However, the total number of code points (values in the Unicode codespace) only fits completely within 32 bits. This means that for UTF-8 and UTF-16, more than one code unit may be required to fully encode a specific value. UTF-8 and UTF-16 are variable-width encodings, while UTF-32 is fixed-width.

UTF-8 has the advantage of being backwards compatible with ASCII, and is one of the most commonly used Unicode encoding.

UTF-16 is used everywhere in the Windows API. The strategy employed by Microsoft to provide backwards compatibility in their API was to create an ANSI and a Unicode version of the same function, ending with A (ANSI) and W (Wide character, or UTF-16 Unicode). In headers, the original function name is replaced by a macro that defines to either the ANSI or Unicode version based on the definition of the _UNICODE macro.

UTF-32 has the advantage of being fixed width, but wastes a lot of space for English text (4x more than UTF-8, 2x more than UTF-16).

In C, wide character strings are often defined with the wchar_t type. Many functions are provided to deal with those wide character strings, such as wcslen (strlen equivalent) or wprintf (printf equivalent).

This may lead to some confusion, since many of these functions exist on both Windows and Linux, but they are not the same!

This sample hello world is a good example:

include <wchar.h>

wchar_t hello[] = L"Hello, World!\n";

int main(int argc, char** argv) { wprintf(hello); wprintf(L"sizeof(wchar_t): %d\n", sizeof(wchar_t)); return 0; }

There is a reason why the sample prints the size of the wchar_t type: On Windows, wchar_t is two bytes (UTF-16), while on most other systems it is 4 bytes (UTF-32). This means that if you write code on Windows, use L"" to define a string which is meant to be UTF-16 and not UTF-32, you will have a little surprise when trying to port your code to Linux.

Since the Windows API uses UTF-16, not UTF-32, WinPR defines the WCHAR type to always be 2-bytes long and uses it instead of wchar_t. Do not ever use wchar_t with WinPR unless you know what you are doing.

As for L"", it is unfortunately unusable in a portable way, unless a special option is passed to GCC to define wchar_t as being two bytes. For string constants that must be UTF-16, it is a pain, but they can be defined in a portable way like this:

WCHAR hello[] = { 'H','e','l','l','o','\0' };

Such strings cannot be passed to native functions like wcslen(), which may expect a different wchar_t size. For this reason, WinPR provides _wcslen, which expects UTF-16 WCHAR strings on all platforms.

Here is the call graph for this function:

Here is the caller graph for this function:

WINPR_API char* StrSep ( char **  stringp,
const char *  delim 
)

Here is the caller graph for this function:

WINPR_API char* strtok_s ( char *  strToken,
const char *  strDelimit,
char **  context 
)

Here is the caller graph for this function:

WINPR_API WCHAR* wcstok_s ( WCHAR *  strToken,
const WCHAR *  strDelimit,
WCHAR **  context 
)

Here is the call graph for this function:

Here is the caller graph for this function:

WINPR_API int WideCharToMultiByte ( UINT  CodePage,
DWORD  dwFlags,
LPCWSTR  lpWideCharStr,
int  cchWideChar,
LPSTR  lpMultiByteStr,
int  cbMultiByte,
LPCSTR  lpDefaultChar,
LPBOOL  lpUsedDefaultChar 
)

Here is the call graph for this function:

Here is the caller graph for this function: