HString Class
A helper class for managing the lifetime of an HSTRING using the RAII pattern.
class HString;
The Windows Runtime provides access to strings through HSTRING handles. The HString
class provides convenience functions and operators to simplify using HSTRING handles. This class can handle the lifetime of the HSTRING it owns through an RAII pattern.
Name | Description |
---|---|
HString::HString | Initializes a new instance of the HString class. |
HString::~HString | Destroys the current instance of the HString class. |
Name | Description |
---|---|
HString::Attach | Associates the specified HString object with the current HString object. |
HString::CopyTo | Copies the current HString object to an HSTRING object. |
HString::Detach | Disassociates the specified HString object from its underlying value. |
HString::Get | Retrieves the value of the underlying HSTRING handle. |
HString::GetAddressOf | Retrieves a pointer to the underlying HSTRING handle. |
HString::GetRawBuffer | Retrieves a pointer to the underlying string data. |
HString::IsValid | Indicates whether the current HString object is valid. |
HString::MakeReference | Creates an HStringReference object from a specified string parameter. |
HString::Release | Deletes the underlying string value and initializes the current HString object to an empty value. |
HString::Set | Sets the value of the current HString object to the specified wide-character string or HString parameter. |
Name | Description |
---|---|
HString::operator= | Moves the value of another HString object to the current HString object. |
HString::operator== | Indicates whether the two parameters are equal. |
HString::operator!= | Indicates whether the two parameters are not equal. |
HString::operator< |
Indicates whether the first parameter is less than the second parameter. |
HString
Header: corewrappers.h
Namespace: Microsoft::WRL::Wrappers
Destroys the current instance of the HString
class.
~HString() throw()
Associates the specified HString
object with the current HString
object.
void Attach(
HSTRING hstr
) throw()
hstr
An existing HString
object.
Copies the current HString
object to an HSTRING object.
HRESULT CopyTo(
_Out_ HSTRING *str
) const throw();
str
The HSTRING that receives the copy.
This method calls the WindowsDuplicateString function.
Disassociates the specified HString
object from its underlying value.
HSTRING Detach() throw()
The underlying HString
value before the detach operation started.
Retrieves the value of the underlying HSTRING handle.
HSTRING Get() const throw()
The value of the underlying HSTRING handle
Retrieves a pointer to the underlying HSTRING handle.
HSTRING* GetAddressOf() throw()
A pointer to the underlying HSTRING handle.
After this operation, the string value of the underlying HSTRING handle is destroyed.
Retrieves a pointer to the underlying string data.
const wchar_t* GetRawBuffer(unsigned int* length) const;
length
Pointer to an int
variable that receives the length of the data.
A const
pointer to the underlying string data.
Initializes a new instance of the HString
class.
HString() throw();
HString(HString&& other) throw();
hstr
An HSTRING handle.
other
An existing HString
object.
The first constructor initializes a new HString
object that is empty.
The second constructor initializes a new HString
object to the value of the existing other parameter, and then destroys the other parameter.
Indicates whether the current HString
object is empty or not.
bool IsValid() const throw()
true
if the current HString
object is not empty; otherwise, false
.
Creates an HStringReference
object from a specified string parameter.
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
A template parameter that specifies the size of the destination HStringReference
buffer.
str
A reference to a wide-character string.
len
The maximum length of the str parameter buffer to use in this operation. If the len parameter isn't specified, the entire str parameter is used.
An HStringReference
object whose value is the same as the specified str parameter.
Moves the value of another HString
object to the current HString
object.
HString& operator=(HString&& other) throw()
other
An existing HString
object.
The value of the existing other object is copied to the current HString
object, and then the other object is destroyed.
Indicates whether the two parameters are equal.
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
The first parameter to compare. lhs can be an HString
or HStringReference
object, or an HSTRING handle.
rhs
The second parameter to compare.rhs can be an HString
or HStringReference
object, or an HSTRING handle.
true
if the lhs and rhs parameters are equal; otherwise, false
.
Indicates whether the two parameters are not equal.
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
The first parameter to compare. lhs can be an HString
or HStringReference
object, or an HSTRING handle.
rhs
The second parameter to compare.rhs can be an HString
or HStringReference
object, or an HSTRING handle.
true
if the lhs and rhs parameters are not equal; otherwise, false
.
Indicates whether the first parameter is less than the second parameter.
inline bool operator<(
const HString& lhs,
const HString& rhs) throw()
lhs
The first parameter to compare. lhs can be a reference to an HString
.
rhs
The second parameter to compare. rhs can be a reference to an HString
.
true
if the lhs parameter is less than the rhs parameter; otherwise, false
.
Deletes the underlying string value and intializes the current HString
object to an empty value.
void Release() throw()
Sets the value of the current HString
object to the specified wide-character string or HString
parameter.
HRESULT Set(
const wchar_t* str) throw();
HRESULT Set(
const wchar_t* str,
unsigned int len
) throw();
HRESULT Set(
const HSTRING& hstr
) throw();
str
A wide-character string.
len
The maximum length of the str parameter that is assigned to the current HString
object.
hstr
An existing HString
object.