CStringElementTraits Class

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at CStringElementTraits Class.

This class provides static functions used by collection classes storing CString objects.

Syntax

template <typename T>  
class CStringElementTraits

Parameters

T
The type of data to be stored in the collection.

Members

Public Typedefs

Public Methods

Remarks

This class provides static functions for copying, moving, and comparing strings and for creating a hash value. These functions are useful when using a collection class to store string-based data. Use CStringElementTraitsI when case-insensitive comparisons are required. Use CStringRefElementTraits when the string objects are to be dealt with as references.

For more information, see ATL Collection Classes.

Requirements

Header: cstringt.h

CStringElementTraits::CompareElements

Call this static function to compare two string elements for equality.

static bool CompareElements(INARGTYPE str1, INARGTYPE str2);

Parameters

str1
The first string element.

str2
The second string element.

Return Value

Returns true if the elements are equal, false otherwise.

CStringElementTraits::CompareElementsOrdered

Call this static function to compare two string elements.

static int CompareElementsOrdered(INARGTYPE str1, INARGTYPE str2);

Parameters

str1
The first string element.

str2
The second string element.

Return Value

Zero if the strings are identical, < 0 if str1 is less than str2, or > 0 if str1 is greater than str2. The CStringT::Compare method is used to perform the comparisons.

CStringElementTraits::CopyElements

Call this static function to copy CString elements stored in a collection class object.

static void CopyElements(
    T* pDest,
    const T* pSrc,
    size_t nElements);

Parameters

pDest
Pointer to the first element that will receive the copied data.

pSrc
Pointer to the first element to copy.

nElements
The number of elements to copy.

Remarks

The source and destination elements should not overlap.

CStringElementTraits::Hash

Call this static function to calculate a hash value for the given string element.

static ULONG Hash(INARGTYPE str);

Parameters

str
The string element.

Return Value

Returns a hash value, calculated using the string's contents.

CStringElementTraits::INARGTYPE

The data type to use for adding elements to the collection class object.

typedef T::PCXSTR INARGTYPE;

CStringElementTraits::OUTARGTYPE

The data type to use for retrieving elements from the collection class object.

typedef T& OUTARGTYPE;

CStringElementTraits::RelocateElements

Call this static function to relocate CString elements stored in a collection class object.

static void RelocateElements(
    T* pDest,
    T* pSrc,
    size_t nElements);

Parameters

pDest
Pointer to the first element that will receive the relocated data.

pSrc
Pointer to the first element to relocate.

nElements
The number of elements to relocate.

Remarks

This static function calls memmove, which is sufficient for most data types. If the objects being moved contain pointers to their own members, this static function will need to be overridden.

See Also

CElementTraitsBase Class
CStringElementTraitsI Class
Class Overview