BeStringUtilities.h

Go to the documentation of this file.

/*--------------------------------------------------------------------------------------+
|
|   Supplied under applicable software license agreement.
|
|   Copyright (c) 2018 Bentley Systems, Incorporated. All rights reserved.
|
+---------------------------------------------------------------------------------------*/
#pragma once
#ifndef BENTLEY_WIN32
#define BENTLEY_WIN32
#endif


#include "Bentley.h"
#include "bvector.h"
#include "NonCopyableClass.h"
#include "CodePages.h"
#include <stdarg.h>
#include <stdio.h>

BEGIN_BENTLEY_NAMESPACE


typedef bvector<Utf16Char>  Utf16Buffer;
typedef Utf16Buffer const*  Utf16BufferCP;
typedef Utf16Buffer const&  Utf16BufferCR;
typedef Utf16Buffer*        Utf16BufferP;
typedef Utf16Buffer&        Utf16BufferR;

// Options for formatting unsigned integer values in hexadecimal
enum class HexFormatOptions
    {
    None              = 0,
    LeftJustify       = 1 << 0,       // Append spaces to meet minimum width. Analogous to '-' printf option.
    IncludePrefix     = 1 << 1,       // Prefix with "0x" or "0X" depending on the HexFormatOptions::Uppercase flag. Analagous to '#' printf option.
    Uppercase         = 1 << 2,       // Use uppercase hexadecimal digits; also affects case of prefix. Analogous to "%X" printf specifier.
    LeadingZeros      = 1 << 3,       // Pad with leading zeros to meet minimum precision and/or width. Analogous to '0' printf option.
    UsePrecision      = 1 << 4,       // Without this option, default precision of 1 is used and leading zeros are applied to fulfill minimum width based on HexFormatOptions::LeadingZeros option.
                                      // With this option, leading zeros are not used to satisfy minimum width regardless of HexFormatOptions::LeadingZeros, but are used to satisfy minimum precision, in keeping with Snwprintf()
    };

//=======================================================================================
// @bsiclass                                                     Bentley Systems
//=======================================================================================
struct BeStringUtilities : public NonCopyableClass
    {
private:
    // Static class; don't allow new instances.
    BeStringUtilities () { }


public:
    static const size_t NPOS = (size_t)-1;                  
    static const size_t AsManyAsPossible = ((size_t)-1);    

    BENTLEYDLL_EXPORT static BentleyStatus Utf16ToWChar (WStringR, Utf16CP, size_t count = AsManyAsPossible);

    BENTLEYDLL_EXPORT static BentleyStatus Utf16ToWChar (WCharP wbuf, size_t wbufSizeInChars, Utf16CP inStr, size_t count = AsManyAsPossible);

    template <size_t wbufSizeInChars>
    static BentleyStatus Utf16ToWChar (WChar (&wbuf)[wbufSizeInChars], Utf16CP inStr, size_t count = AsManyAsPossible) {return Utf16ToWChar (wbuf, wbufSizeInChars, inStr, count);}

    BENTLEYDLL_EXPORT static BentleyStatus WCharToUtf16 (Utf16BufferR, WCharCP, size_t count = AsManyAsPossible);

    BENTLEYDLL_EXPORT static BentleyStatus WCharToUtf16 (Utf16P ubuf, size_t ubufSizeInChars, WCharCP inStr, size_t count = AsManyAsPossible);

    template <size_t ubufSizeInChars>
    static BentleyStatus WCharToUtf16 (Utf16Char (&ubuf)[ubufSizeInChars], WCharCP inStr, size_t count) {return WCharToUtf16 (ubuf, ubufSizeInChars, inStr, count);}

    BENTLEYDLL_EXPORT static int CompareUtf16 (Utf16CP s1, Utf16CP s2);

    BENTLEYDLL_EXPORT static int CompareUtf16WChar (Utf16CP s1, WCharCP s2);

    BENTLEYDLL_EXPORT static size_t Utf16Len (Utf16CP);

    BENTLEYDLL_EXPORT static void CopyUtf16 (Utf16P outStr, size_t outStrCapacity, Utf16CP inStr);

    template <size_t outStrCapacity>
    static void CopyUtf16 (Utf16Char (&outStr)[outStrCapacity], Utf16CP inStr) {return CopyUtf16 (outStr, outStrCapacity, inStr);}

    BENTLEYDLL_EXPORT static BentleyStatus WCharToUtf8 (Utf8StringR, WCharCP, size_t count = AsManyAsPossible);

    BENTLEYDLL_EXPORT static BentleyStatus Utf8ToWChar (WStringR, Utf8CP, size_t count = AsManyAsPossible);

    BENTLEYDLL_EXPORT static WCharP Utf8ToWChar (WCharP outWChar, Utf8CP inChar, size_t outMaxChars);

    BENTLEYDLL_EXPORT static BentleyStatus Utf8ToUtf16 (Utf16BufferR, Utf8CP, size_t count = AsManyAsPossible);

    BENTLEYDLL_EXPORT static BentleyStatus Utf16ToUtf8 (Utf8StringR, Utf16CP, size_t count = AsManyAsPossible);

    BENTLEYDLL_EXPORT static BentleyStatus WCharToLocaleChar (AStringR, UInt32 codePage, WCharCP, size_t count = AsManyAsPossible);

    BENTLEYDLL_EXPORT static CharP WCharToCurrentLocaleChar (CharP outChar, WCharCP inWChar, size_t outMaxBytes);

    BENTLEYDLL_EXPORT static BentleyStatus WCharToCurrentLocaleChar (AStringR localeStr, WCharCP inWChar);

    BENTLEYDLL_EXPORT static void* WCharToPointer (WCharCP inWChar);

    BENTLEYDLL_EXPORT static BentleyStatus LocaleCharToWChar (WStringR, CharCP, UInt32 codePage, size_t count = AsManyAsPossible);

    BENTLEYDLL_EXPORT static WCharP LocaleCharToWChar (WCharP outWChar, CharCP inChar, UInt32 codePage, size_t outMaxChars);

    BENTLEYDLL_EXPORT static WCharP CurrentLocaleCharToWChar (WCharP outWChar, CharCP inChar, size_t outMaxChars);

    BENTLEYDLL_EXPORT static BentleyStatus CurrentLocaleCharToWChar (WStringR outStr, CharCP inChar);

    BENTLEYDLL_EXPORT static BentleyStatus GetCurrentCodePage (LangCodePage& codePage);

    BENTLEYDLL_EXPORT static bool IsValidCodePage (LangCodePage codePage);

    BENTLEYDLL_EXPORT static BentleyStatus GetDecimalSeparator (WStringR sep);

    BENTLEYDLL_EXPORT static Utf8String UriEncode (Utf8CP charsToEncode);

    BENTLEYDLL_EXPORT static int Snprintf (CharP buffer, size_t numCharsInBuffer, CharCP format, ...);

    template <size_t destArraySize>
    static int Snprintf (char (&destArray)[destArraySize], CharCP format, ...)
        {
        va_list args;
        va_start (args, format);
        return Vsnprintf (destArray, destArraySize, format, args);
        }

    BENTLEYDLL_EXPORT static int Vsnprintf (CharP buffer, size_t numCharsInBuffer, CharCP format, va_list args);

    BENTLEYDLL_EXPORT static int Snwprintf (WCharP buffer, size_t numCharsInBuffer, WCharCP format, ...);

    template <size_t destArraySize>
    static int Snwprintf (wchar_t (&destArray)[destArraySize], WCharCP format, ...)
        {
        va_list args;
        va_start (args, format);
        return Vsnwprintf (destArray, destArraySize, format, args);
        }

    BENTLEYDLL_EXPORT static int Vsnwprintf (WCharP buffer, size_t numCharsInBuffer, WCharCP format, va_list args);

    BENTLEYDLL_EXPORT static char* Strlwr (char* s);

    BENTLEYDLL_EXPORT static wchar_t* Wcslwr (wchar_t* s);

    BENTLEYDLL_EXPORT static char* Strupr (char* s);

    BENTLEYDLL_EXPORT static wchar_t* Wcsupr (wchar_t* s);

    BENTLEYDLL_EXPORT static int Stricmp (const char* s1, const char* s2);

    BENTLEYDLL_EXPORT static int Wcsicmp (WCharCP lhs, WCharCP rhs);

    BENTLEYDLL_EXPORT static int Strnicmp (const char* s1, const char* s2, size_t n);

    BENTLEYDLL_EXPORT static int Wcsnicmp (const wchar_t* s1, const wchar_t* s2, size_t n);

    BENTLEYDLL_EXPORT static char* Strdup (char const* s);

    BENTLEYDLL_EXPORT static wchar_t* Wcsdup (wchar_t const* s);

    BENTLEYDLL_EXPORT static char *Strtok (char *strToken, const char *strDelimit, char **context);

    BENTLEYDLL_EXPORT static wchar_t *Wcstok (wchar_t *wcsToken, const wchar_t *wcsDelimit, wchar_t **context);

    BENTLEYDLL_EXPORT static wchar_t *Wcsrev (wchar_t *wstr);

    BENTLEYDLL_EXPORT static wchar_t* Wcsncpy (wchar_t *strDest, size_t destLen, const wchar_t *strSource, size_t count = AsManyAsPossible);

    template <size_t destArraySize>
    static wchar_t* Wcsncpy (wchar_t (&destArray)[destArraySize], const wchar_t *strSource, size_t count = AsManyAsPossible) {return Wcsncpy (destArray, destArraySize, strSource, count);}

    BENTLEYDLL_EXPORT static char* Strncpy (char *strDest, size_t destLen, const char *strSource, size_t count = AsManyAsPossible);

    template <size_t destArraySize>
    static char* Strncpy (char (&destArray)[destArraySize], const char *strSource, size_t count = AsManyAsPossible) {return Strncpy (destArray, destArraySize, strSource, count);}

    BENTLEYDLL_EXPORT static BentleyStatus ParseHexUInt64 (UInt64& value, WCharCP string);

    BENTLEYDLL_EXPORT static void          FormatHexUInt64 (WCharP buf, UInt64 value);

    BENTLEYDLL_EXPORT static int Wtoi (wchar_t const* s);

    BENTLEYDLL_EXPORT static unsigned long Wcstoul (wchar_t const* nptr, wchar_t** endptr, int base);

    BENTLEYDLL_EXPORT static long          Wcstol (wchar_t const* nptr, wchar_t** endptr, int base);

    BENTLEYDLL_EXPORT static double        Wcstod (wchar_t const* s, wchar_t** end);

    BENTLEYDLL_EXPORT static double Wtof (wchar_t const* s);

    BENTLEYDLL_EXPORT static BentleyStatus Itow (wchar_t* buffer, int value, size_t sizeInCharacters, int radix);

    BENTLEYDLL_EXPORT static BentleyStatus Wmemmove (wchar_t *dest, size_t numberOfElements, const wchar_t *src, size_t count);

    BENTLEYDLL_EXPORT static BentleyStatus Memcpy (void *dest, size_t numberOfElements, const void *src, size_t count);

    BENTLEYDLL_EXPORT static BentleyStatus Wmemcpy (wchar_t *dest, size_t numberOfElements, const wchar_t *src, size_t count);

    BENTLEYDLL_EXPORT static void Split(WCharCP str, WCharCP delimiters, bvector<WString>& tokens) { return Split(str, delimiters, NULL, tokens); }
    
    BENTLEYDLL_EXPORT static void Split(WCharCP str, WCharCP delimiters, WCharCP escapeChars, bvector<WString>& tokens);

    BENTLEYDLL_EXPORT static WString    Join (bvector<WString> const& strings, WCharCP delimiter = NULL);

    BENTLEYDLL_EXPORT static void Split(Utf8CP str, Utf8CP delimiters, bvector<Utf8String>& tokens) { return Split(str, delimiters, NULL, tokens); }

    BENTLEYDLL_EXPORT static void Split(Utf8CP str, Utf8CP delimiters, Utf8CP escapeChars, bvector<Utf8String>& tokens);

    BENTLEYDLL_EXPORT static void ParseArguments (bvector<WString>& subStrings, WCharCP inString, WCharCP auxDelimiters = NULL);

    BENTLEYDLL_EXPORT static UInt32  ParseArguments (WCharCP inString, UInt32 numSubStrings, ...);

    BENTLEYDLL_EXPORT static int FormatUInt64 (wchar_t *dest, size_t numCharsInBuffer, UInt64 val, HexFormatOptions opts, UInt8 width = 0, UInt8 precision = 1);

    BENTLEYDLL_EXPORT static BentleyStatus ParseUInt64(uint64_t& value, WCharCP string);

    BENTLEYDLL_EXPORT static BentleyStatus ParseUInt64(uint64_t& value, Utf8CP string);

    BENTLEYDLL_EXPORT static int LexicographicCompare (WCharCP value0, WCharCP value1);

    }; // BeStringUtilities

BENTLEYDLL_EXPORT BentleyStatus BeGetUserName (WStringR s);

BENTLEYDLL_EXPORT BentleyStatus BeGetUserNameA (AStringR s);

BENTLEYDLL_EXPORT BentleyStatus BeGetComputerName (WStringR s);

BENTLEYDLL_EXPORT BentleyStatus BeGetComputerNameA (AStringR s);


END_BENTLEY_NAMESPACE