HString 类

项目
10/18/2023

用于使用 RAII 模式管理 HSTRING 的生存期的帮主程序类。

语法

class HString;

备注

Windows 运行时通过 HSTRING 句柄提供对字符串的访问权限。 HString 类提供简单的函数和运算符，以简化 HSTRING 句柄的用法。此类可以通过 RAII 模式处理其拥有的 HSTRING 的生存期。

成员

公共构造函数

名称	描述
HString::HString	初始化 `HString` 类的新实例。
HString::~HString	销毁 `HString` 类的当前实例。

公共方法

名称	描述
HString::Attach	将指定的 `HString` 对象与当前 `HString` 对象相关联。
HString::CopyTo	将当前 `HString` 对象复制到 HSTRING 对象。
HString::Detach	将指定的 `HString` 对象与其基础值解除关联。
HString::Get	检索基础 HSTRING 句柄的值。
HString::GetAddressOf	检索指向基础 HSTRING 句柄的指针。
HString::GetRawBuffer	检索指向基础字符串数据的指针。
HString::IsValid	指示当前 `HString` 对象是否有效。
HString::MakeReference	从指定的字符串参数创建 `HStringReference` 对象。
HString::Release	删除基础字符串值，并将当前 `HString` 对象初始化为空值。
HString::Set	将当前 `HString` 对象的值设置为指定的宽字符字符串或 `HString` 参数。

公共运算符

“属性”	描述
HString::operator=	将另一个 `HString` 对象的值移动到当前 `HString` 对象。
HString::operator==	指示两个参数是否相等。
HString::operator!=	指示两个参数是否不相等。
`HString::operator<`	指示第一个参数是否小于第二个参数。

继承层次结构

HString

要求

标头：corewrappers.h

命名空间：Microsoft::WRL::Wrappers

HString::~HString

销毁 HString 类的当前实例。

~HString() throw()

HString::Attach

将指定的 HString 对象与当前 HString 对象相关联。

void Attach(
       HSTRING hstr
       ) throw()

参数

hstr
一个现有的 HString 对象。

HString::CopyTo

将当前 HString 对象复制到 HSTRING 对象。

HRESULT CopyTo(
   _Out_ HSTRING *str
   ) const throw();

参数

str
接收副本的 HSTRING。

备注

此方法调用 WindowsDuplicateString 函数。

HString::Detach

将指定的 HString 对象与其基础值解除关联。

HSTRING Detach() throw()

返回值

分离操作启动之前的基础 HString 值。

HString::Get

检索基础 HSTRING 句柄的值。

HSTRING Get() const throw()

返回值

基础 HSTRING 句柄的值

HString::GetAddressOf

检索指向基础 HSTRING 句柄的指针。

HSTRING* GetAddressOf() throw()

返回值

指向基础 HSTRING 句柄的指针。

注解

此操作后，将销毁基础 HSTRING 句柄的字符串值。

HString::GetRawBuffer

检索指向基础字符串数据的指针。

const wchar_t* GetRawBuffer(unsigned int* length) const;

参数

length 指向接收数据长度的 int 变量的指针。

返回值

指向基础字符串数据的 const 指针。

HString::HString

初始化 HString 类的新实例。

HString() throw();
HString(HString&& other) throw();

参数

hstr
HSTRING 句柄。

其他
一个现有的 HString 对象。

备注

第一个构造函数初始化空的新 HString 对象。

第二个构造函数将新的 HString 对象初始化为现有 other 参数的值，然后销毁 other 参数。

HString::IsValid

指示当前 HString 对象是否为空。

bool IsValid() const throw()

参数

如果当前 HString 对象不为空，则为 true；否则为 false。

HString::MakeReference

从指定的字符串参数创建 HStringReference 对象。

template<unsigned int sizeDest>
    static HStringReference MakeReference(
              wchar_t const (&str)[ sizeDest]);

    template<unsigned int sizeDest>
    static HStringReference MakeReference(
              wchar_t const (&str)[sizeDest],
              unsigned int len);

参数

sizeDest
指定目标 HStringReference 缓冲区大小的模板参数。

str
对宽字符串的引用。

len
要在此操作中使用的 str 参数缓冲区的最大长度。如果 len 参数未指定，则将使用整个 str 参数。

返回值

一个 HStringReference 对象，其值与指定的 str 参数相同。

HString::operator= 运算符

将另一个 HString 对象的值移动到当前 HString 对象。

HString& operator=(HString&& other) throw()

参数

其他
一个现有的 HString 对象。

备注

现有 other 对象的值将复制到当前 HString 对象，然后将销毁 other 对象。

HString::operator== 运算符

指示两个参数是否相等。

inline bool operator==(
               const HString& lhs,
               const HString& rhs) throw()

inline bool operator==(
                const HString& lhs,
                const HStringReference& rhs) throw()

inline bool operator==(
                const HStringReference& lhs,
                const HString& rhs) throw()

inline bool operator==(
                 const HSTRING& lhs,
                 const HString& rhs) throw()

inline bool operator==(
                 const HString& lhs,
                 const HSTRING& rhs) throw()

参数

lhs
要比较的第一个参数。 lhs 可以是 HString 或 HStringReference 对象或 HSTRING 句柄。

rhs
要比较的第二个参数。rhs 可以是 HString 或 HStringReference 对象或 HSTRING 句柄。

返回值

如果 lhs 和 rhs 参数相等，则为 true；否则为 false。

HString::operator!= 运算符

指示两个参数是否不相等。

inline bool operator!=( const HString& lhs,
                        const HString& rhs) throw()

inline bool operator!=( const HStringReference& lhs,
                        const HString& rhs) throw()

inline bool operator!=( const HString& lhs,
                        const HStringReference& rhs) throw()

inline bool operator!=( const HSTRING& lhs,
                        const HString& rhs) throw()

inline bool operator!=( const HString& lhs,
                        const HSTRING& rhs) throw()

参数

lhs
要比较的第一个参数。 lhs 可以是 HString 或 HStringReference 对象或 HSTRING 句柄。

rhs
要比较的第二个参数。rhs 可以是 HString 或 HStringReference 对象或 HSTRING 句柄。

返回值

如果 lhs 和 rhs 参数不相等，则为 true；否则为 false。

`HString::operator<` 运算符

指示第一个参数是否小于第二个参数。

inline bool operator<(
    const HString& lhs,
    const HString& rhs) throw()

参数

lhs
要比较的第一个参数。 lhs 可以是对 HString 的引用。

rhs
要比较的第二个参数。 rhs 可以是对 HString 的引用。

返回值

如果 lhs 参数小于 rhs 参数，则为 true；否则为 false。

HString::Release

删除基础字符串值，并将当前 HString 对象初始化为空值。

void Release() throw()

HString::Set

将当前 HString 对象的值设置为指定的宽字符字符串或 HString 参数。

HRESULT Set(
          const wchar_t* str) throw();
HRESULT Set(
          const wchar_t* str,
          unsigned int len
           ) throw();
HRESULT Set(
          const HSTRING& hstr
           ) throw();

参数

str
宽字符字符串。

len
分配给当前 HString 对象的 str 参数的最大长度。