HString Class

A helper class for managing the lifetime of an HSTRING using the RAII pattern.

Syntax

class HString;

Remarks

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.

Members

Public Constructors

Name	Description
HString::HString	Initializes a new instance of the HString class.
HString::~HString	Destroys the current instance of the HString class.

Public Methods

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.

Public Operators

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.

Inheritance Hierarchy

HString

Requirements

Header: corewrappers.h

Namespace: Microsoft::WRL::Wrappers

HString::~HString

Destroys the current instance of the HString class.

~HString() throw()

HString::Attach

Associates the specified HString object with the current HString object.

void Attach(
       HSTRING hstr
       ) throw()

Parameters

hstr
An existing HString object.

HString::CopyTo

Copies the current HString object to an HSTRING object.

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

Parameters

str
The HSTRING that receives the copy.

Remarks

This method calls the WindowsDuplicateString function.

HString::Detach

Disassociates the specified HString object from its underlying value.

HSTRING Detach() throw()

Return Value

The underlying HString value before the detach operation started.

HString::Get

Retrieves the value of the underlying HSTRING handle.

HSTRING Get() const throw()

Return Value

The value of the underlying HSTRING handle

HString::GetAddressOf

Retrieves a pointer to the underlying HSTRING handle.

HSTRING* GetAddressOf() throw()

Return Value

A pointer to the underlying HSTRING handle.

Remarks

After this operation, the string value of the underlying HSTRING handle is destroyed.

HString::GetRawBuffer

Retrieves a pointer to the underlying string data.

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

Parameters

length Pointer to an int variable that receives the length of the data.

Return Value

A const pointer to the underlying string data.

HString::HString

Initializes a new instance of the HString class.

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

Parameters

hstr
An HSTRING handle.

other
An existing HString object.

Remarks

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.

HString::IsValid

Indicates whether the current HString object is empty or not.

bool IsValid() const throw()

Parameters

true if the current HString object is not empty; otherwise, false.

HString::MakeReference

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);

Parameters

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.

Return Value

An HStringReference object whose value is the same as the specified str parameter.

HString::operator= Operator

Moves the value of another HString object to the current HString object.

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

Parameters

other
An existing HString object.

Remarks

The value of the existing other object is copied to the current HString object, and then the other object is destroyed.

HString::operator== Operator

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()

Parameters

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.

Return Value

true if the lhs and rhs parameters are equal; otherwise, false.

HString::operator!= Operator

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()

Parameters

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.

Return Value

true if the lhs and rhs parameters are not equal; otherwise, false.

HString::operator< Operator

Indicates whether the first parameter is less than the second parameter.

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

Parameters

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.

Return Value

true if the lhs parameter is less than the rhs parameter; otherwise, false.

HString::Release

Deletes the underlying string value and intializes the current HString object to an empty value.

void Release() throw()

HString::Set

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();

Parameters

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.