0027838: Foundation Classes - support wchar_t* input within TCollection_AsciiString and TCollection_ExtendedString

TCollection_ExtendedString/TCollection_AsciiString description
has been updated to reflect usage of this classes for Unicode strings.

TCollection_ExtendedString now defines constructor taking wchar_t* (all platforms)
and method ::ToWideString() returning wchar_t* (Windows only).
TCollection_AsciiString now defines constructor taking wchar_t*.

TCollection_ExtendedString/TCollection_AsciiString now defines
auxiliary methods ::StartsWith() and ::EndsWith().

TCollection_ExtendedString internals has been updated to eliminate
duplicated code for converting between UTF-16 and UTF-8.

Code has been cleaned up from redundant explicit conversions to wchar_t*.
Global method OSD_OpenStream()/OSD_OpenFileBuf() have been replaced
by C++ template to eliminate copy-paste for different STL collections.

OSD_SharedLibrary now uses wide-char system API call LoadLibraryExW()
on Windows for consistency.

New macro Standard_UNUSED has been added for marking possibly unused functions and variables
(to suppress gcc/clang compiler warnings).

src/NCollection/NCollection_UtfIterator.hxx

@@ -88,6 +88,12 @@ public:
     return myPosition == theRight.myPosition;
   }
 
+  //! Return true if Unicode symbol is within valid range.
+  bool IsValid() const
+  {
+    return myCharUtf32 <= UTF32_MAX_LEGAL;
+  }
+
   //! Dereference operator.
   //! @return the UTF-32 codepoint of the character currently pointed by iterator.
   Standard_Utf32Char operator*() const
@@ -121,6 +127,12 @@ public:
   //! 4 bytes for surrogate pair.
   Standard_Integer AdvanceBytesUtf16() const;
 
+  //! @return the advance in bytes to store current symbol in UTF-16.
+  //! 0 means an invalid symbol;
+  //! 1 16-bit code unit is a general case;
+  //! 2 16-bit code units for surrogate pair.
+  Standard_Integer AdvanceCodeUnitsUtf16() const;
+
   //! @return the advance in bytes to store current symbol in UTF-32.
   //! Always 4 bytes (method for consistency).
   Standard_Integer AdvanceBytesUtf32() const

src/NCollection/NCollection_UtfIterator.lxx

@@ -229,6 +229,16 @@ Standard_Utf8UChar* NCollection_UtfIterator<Type>::GetUtf8 (Standard_Utf8UChar*
 // =======================================================================
 template<typename Type> inline
 Standard_Integer NCollection_UtfIterator<Type>::AdvanceBytesUtf16() const
+{
+  return AdvanceCodeUnitsUtf16() * sizeof(Standard_Utf16Char);
+}
+
+// =======================================================================
+// function : AdvanceCodeUnitsUtf16
+// purpose  :
+// =======================================================================
+template<typename Type> inline
+Standard_Integer NCollection_UtfIterator<Type>::AdvanceCodeUnitsUtf16() const
 {
   if (myCharUtf32 <= UTF32_MAX_BMP) // target is a character <= 0xFFFF
   {
@@ -240,7 +250,7 @@ Standard_Integer NCollection_UtfIterator<Type>::AdvanceBytesUtf16() const
     }
     else
     {
-      return Standard_Integer(sizeof(Standard_Utf16Char));
+      return 1;
     }
   }
   else if (myCharUtf32 > UTF32_MAX_LEGAL)
@@ -252,7 +262,7 @@ Standard_Integer NCollection_UtfIterator<Type>::AdvanceBytesUtf16() const
   {
     // target is a character in range 0xFFFF - 0x10FFFF
     // surrogate pair
-    return Standard_Integer(sizeof(Standard_Utf16Char) * 2);
+    return 2;
   }
 }
 

src/NCollection/NCollection_UtfString.hxx

@@ -96,11 +96,15 @@ public:
   NCollection_UtfString (const Standard_Utf32Char* theCopyUtf32,
                          const Standard_Integer    theLength = -1);
 
+#if !defined(_WIN32) || defined(_NATIVE_WCHAR_T_DEFINED) || (defined(_MSC_VER) && _MSC_VER >= 1900)
   //! Copy constructor from NULL-terminated wide UTF string.
   //! @param theCopyUtfWide NULL-terminated wide UTF string to copy
   //! @param theLength      the length limit in Unicode symbols (NOT bytes!)
+  //!
+  //! This constructor is undefined if Standard_WideChar is the same type as Standard_Utf16Char.
   NCollection_UtfString (const Standard_WideChar* theCopyUtfWide,
                          const Standard_Integer   theLength = -1);
+#endif
 
   //! Copy from NULL-terminated Unicode string.
   //! @param theStringUtf NULL-terminated Unicode string

src/NCollection/NCollection_UtfString.lxx

@@ -179,6 +179,7 @@ NCollection_UtfString<Type>::NCollection_UtfString (const Standard_Utf32Char* th
   FromUnicode (theCopyUtf32, theLength);
 }
 
+#if !defined(_WIN32) || defined(_NATIVE_WCHAR_T_DEFINED) || (defined(_MSC_VER) && _MSC_VER >= 1900)
 // =======================================================================
 // function : NCollection_UtfString
 // purpose  :
@@ -192,6 +193,7 @@ NCollection_UtfString<Type>::NCollection_UtfString (const Standard_WideChar* the
 {
   FromUnicode (theCopyUtfWide, theLength);
 }
+#endif
 
 // =======================================================================
 // function : ~NCollection_UtfString