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.

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.