HStringReference Class

Represents an HSTRING that is created from an existing string.

Syntax

class HStringReference;

Remarks

The lifetime of the backing buffer in the new HSTRING is not managed by the Windows Runtime. The caller allocates a source string on the stack frame to avoid a heap allocation and to eliminate the risk of a memory leak. Also, the caller must ensure that source string remains unchanged during the lifetime of the attached HSTRING. For more information, see WindowsCreateStringReference function.

Members

Public Constructors

Name	Description
HStringReference::HStringReference	Initializes a new instance of the HStringReference class.

Public Methods

Member	Description
HStringReference::CopyTo	Copies the current HStringReference object to an HSTRING object.
HStringReference::Get	Retrieves the value of the underlying HSTRING handle.
HStringReference::GetRawBuffer	Retrieves a pointer to the underlying string data.

Public Operators

Name	Description
HStringReference::operator=	Moves the value of another HStringReference object to the current HStringReference object.
HStringReference::operator==	Indicates whether the two parameters are equal.
HStringReference::operator!=	Indicates whether the two parameters are not equal.
HStringReference::operator<	Indicates whether the first parameter is less than the second parameter.

Inheritance Hierarchy

HStringReference

Requirements

Header: corewrappers.h

Namespace: Microsoft::WRL::Wrappers

HStringReference::CopyTo

Copies the current HStringReference 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.

HStringReference::Get

Retrieves the value of the underlying HSTRING handle.

HSTRING Get() const throw()

Return Value

The value of the underlying HSTRING handle.

HStringReference::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.

HStringReference::HStringReference

Initializes a new instance of the HStringReference class.

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

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

HStringReference(HStringReference&& other) throw();

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. If len is greater than sizeDest, len is set to sizeDest-1.

other
Another HStringReference object.

Remarks

The first constructor initializes a new HStringReference object that the same size as parameter str.

The second constructor initializes a new HStringReference object that the size specifeid by parameter len.

The third constructor initializes a new HStringReference object to the value of the other parameter, and then destroys the other parameter.

HStringReference::operator=

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

HStringReference& operator=(HStringReference&& other) throw()

Parameters

other
An existing HStringReference object.

Remarks

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

HStringReference::operator==

Indicates whether the two parameters are equal.

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

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

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

Parameters

lhs
The first parameter to compare. lhs can be an HStringReference object or an HSTRING handle.

rhs
The second parameter to compare. rhs can be an HStringReference object or an HSTRING handle.

Return Value

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

HStringReference::operator!=

Indicates whether the two parameters are not equal.

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

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

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

Parameters

lhs
The first parameter to compare. lhs can be an HStringReference object or an HSTRING handle.

rhs
The second parameter to compare. rhs can be an HStringReference object or an HSTRING handle.

Return Value

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

HStringReference::operator<

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

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

Parameters

lhs
The first parameter to compare. lhs can be a reference to an HStringReference.

rhs
The second parameter to compare. rhs can be a reference to an HStringReference.

Return Value

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