Поделиться через


Класс CSimpleStringT

Этот класс представляет CSimpleStringT объект.

Синтаксис

template <typename BaseType>
class CSimpleStringT

Параметры

BaseType
Тип символа класса строки. Может применяться один из перечисленных ниже типов.

  • char (для строк символов ANSI).

  • wchar_t (для строк символов Юникода).

  • TCHAR (для строк символов ANSI и Юникода).

Участники

Общедоступные определения типов

Имя Описание
CSimpleStringT::PCXSTR Указатель на константную строку.
CSimpleStringT::PXSTR Указатель на строку.

Открытые конструкторы

Имя Описание
CSimpleStringT::CSimpleStringT CSimpleStringT Создает объекты различными способами.
CSimpleStringT::~CSimpleStringT Деструктор.

Открытые методы

Имя Описание
CSimpleStringT::Append Добавляет объект к CSimpleStringT существующему CSimpleStringT объекту.
CSimpleStringT::AppendChar Добавляет символ к существующему CSimpleStringT объекту.
CSimpleStringT::CopyChars Копирует символ или символы в другую строку.
CSimpleStringT::CopyCharsOverlapped Копирует символ или символы в другую строку, в которой буферы перекрываются.
CSimpleStringT::Empty Принудительно заставляет строку иметь длину нуля.
CSimpleStringT::FreeExtra Освобождает любую дополнительную память, выделенную ранее строковым объектом.
CSimpleStringT::GetAllocLength Извлекает выделенную длину CSimpleStringT объекта.
CSimpleStringT::GetAt Возвращает символ в заданной позиции.
CSimpleStringT::GetBuffer Возвращает указатель на символы в объекте CSimpleStringT.
CSimpleStringT::GetBufferSetLength Возвращает указатель на символы, CSimpleStringTусеченные до указанной длины.
CSimpleStringT::GetLength Возвращает количество символов в объекте CSimpleStringT .
CSimpleStringT::GetManager Извлекает диспетчер CSimpleStringT памяти объекта.
CSimpleStringT::GetString Извлекает строку символа
CSimpleStringT::IsEmpty Проверяет, содержит ли CSimpleStringT объект символы.
CSimpleStringT::LockBuffer Отключает подсчет ссылок и защищает строку в буфере.
CSimpleStringT::Preallocate Выделяет определенный объем памяти для буфера символов.
CSimpleStringT::ReleaseBuffer Освобождает элемент управления буфером, возвращенным GetBuffer.
CSimpleStringT::ReleaseBufferSetLength Освобождает элемент управления буфером, возвращенным GetBuffer.
CSimpleStringT::SetAt Задает символ в заданной позиции.
CSimpleStringT::SetManager Задает диспетчер CSimpleStringT памяти объекта.
CSimpleStringT::SetString Задает строку CSimpleStringT объекта.
CSimpleStringT::StringLength Возвращает количество символов в указанной строке.
CSimpleStringT::Truncate Усечение строки до указанной длины.
CSimpleStringT::UnlockBuffer Включает подсчет ссылок и освобождает строку в буфере.

Открытые операторы

Имя Описание
CSimpleStringT::operator PCXSTR Непосредственно обращается к символам, хранящимся в объекте CSimpleStringT в виде строки стиля C.
CSimpleStringT::operator[] Возвращает символ в заданной позиции — подстановку GetAtоператора.
CSimpleStringT::operator += Объединяет новую строку с концами существующей строки.
CSimpleStringT::operator = Назначает новое значение объекту CSimpleStringT .

Замечания

CSimpleStringT — базовый класс для различных строковых классов, поддерживаемых Visual C++. Она обеспечивает минимальную поддержку управления памятью строкового объекта и базовой манипуляции с буфером. Дополнительные строковые объекты см. в разделе CStringT Class.

Требования

Заголовок: atlsimpstr.h

CSimpleStringT::Append

Добавляет объект к CSimpleStringT существующему CSimpleStringT объекту.

Синтаксис

void Append(const CSimpleStringT& strSrc);
void Append(PCXSTR pszSrc, int nLength);
void Append(PCXSTR pszSrc);

Параметры

strSrc
Добавляемый CSimpleStringT объект.

pszSrc
Указатель на строку, содержащую символы, добавляемые.

nLength
Количество добавляемых знаков.

Замечания

Вызовите этот метод, чтобы добавить существующий CSimpleStringT объект к другому CSimpleStringT объекту.

Пример

В следующем примере показано использование функции CSimpleStringT::Append.

CAtlString basestr;
IAtlStringMgr* pMgr = basestr.GetManager();
CSimpleString str1(pMgr), str2(pMgr);
str1.SetString(_T("Soccer is"));
str2.SetString(_T(" an elegant game"));
str1.Append(str2);
ASSERT(_tcscmp(str1, _T("Soccer is an elegant game")) == 0);

CSimpleStringT::AppendChar

Добавляет символ к существующему CSimpleStringT объекту.

Синтаксис

void AppendChar(XCHAR ch);

Параметры

ch
Добавляемый символ

Замечания

Вызовите эту функцию, чтобы добавить указанный символ в конец существующего CSimpleStringT объекта.

CSimpleStringT::CopyChars

Копирует символ или символы в CSimpleStringT объект.

Синтаксис

static void CopyChars(
    XCHAR* pchDest,
    const XCHAR* pchSrc,
    int nChars) throw();
static void CopyChars(
    XCHAR* pchDest,
    size_t nDestLen,
    const XCHAR* pchSrc,
    int nChars) throw();

Параметры

pchDest
Указатель на символьную строку.

nDestLen
Размер буфера pchDest

pchSrc
Указатель на строку, содержащую символы для копирования.

nChars
Число копируемых pchSrc символов.

Замечания

Вызовите этот метод для копирования символов из pchSrc pchDest строки.

Пример

В следующем примере показано использование функции CSimpleStringT::CopyChars.

CAtlString basestr;
IAtlStringMgr* pMgr = basestr.GetManager();
CSimpleString str(_T("xxxxxxxxxxxxxxxxxxx"), 20, pMgr);
const TCHAR* pszSrc = _T("Hello world!");
_tprintf_s(_T("%s\n"), str);
str.CopyChars(str.GetBuffer(), 20, pszSrc, 12);
_tprintf_s(_T("%s\n"), str);

Выходные данные из этого примера приведены следующим образом:

xxxxxxxxxxxxxxxxxxx
Hello world!xxxxxxx

CSimpleStringT::CopyCharsOverlapped

Копирует символ или символы в CSimpleStringT объект.

Синтаксис

static void CopyCharsOverlapped(
    XCHAR* pchDest,
    const XCHAR* pchSrc,
    int nChars) throw();

Параметры

pchDest
Указатель на символьную строку.

pchSrc
Указатель на строку, содержащую символы для копирования.

nChars
Число копируемых pchSrc символов.

Замечания

Вызовите этот метод для копирования символов из pchSrc pchDest строки. В отличие от CopyCharsэтого, CopyCharsOverlapped предоставляет безопасный метод копирования из буферов символов, которые могут перекрываться.

Пример

Пример см. в примере CSimpleStringT::CopyCharsили исходном коде CSimpleStringT::SetString для (расположено в atlsimpstr.h).

CSimpleStringT::CSimpleStringT

Формирует объект CSimpleStringT.

Синтаксис

CSimpleStringT(const XCHAR* pchSrc, int nLength, IAtlStringMgr* pStringMgr);
CSimpleStringT(PCXSTR pszSrc, IAtlStringMgr* pStringMgr);
CSimpleStringT(const CSimpleStringT& strSrc);
explicit CSimpleStringT(IAtlStringMgr* pStringMgr) throw();

Параметры

strSrc
Существующий CSimpleStringT объект, скопированный в этот CSimpleStringT объект.

pchSrc
Указатель на массив символов длины nLength, не завершаемого значением NULL.

pszSrc
Строка, завершающаяся значением NULL, копируется в этот CSimpleStringT объект.

nLength
Количество символов в pch.

pStringMgr
Указатель на диспетчер CSimpleStringT памяти объекта. Дополнительные сведения об IAtlStringMgr управлении памятью см. в разделе "Управление памятьюCSimpleStringT" и CStringT"Управление памятью".

Замечания

Создание нового CSimpleStringT объекта. Так как конструкторы копируют входные данные в новое выделенное хранилище, исключения памяти могут привести к возникновению.

Пример

В следующем примере показано использование CSimpleStringT::CSimpleStringT с помощью ATL typedef CSimpleString. CSimpleString — это часто используемая специализация шаблона CSimpleStringTкласса.

CAtlString basestr;
IAtlStringMgr* pMgr = basestr.GetManager();

CSimpleString s1(pMgr);
// Empty string
CSimpleString s2(_T("cat"), pMgr);
// From a C string literal

CSimpleString s3(s2);
// Copy constructor
CSimpleString s4(s2 + _T(" ") + s3);

// From a string expression
CSimpleString s5(_T("xxxxxx"), 6, pMgr);
// s5 = "xxxxxx"

CSimpleStringT::Empty

Делает этот CSimpleStringT объект пустой строкой и освобождает память соответствующим образом.

Синтаксис

void Empty() throw();

Замечания

Дополнительные сведения см. в разделе "Строки: CString очистка исключений".

Пример

В следующем примере показано использование функции CSimpleStringT::Empty.

CAtlString basestr;
IAtlStringMgr* pMgr = basestr.GetManager();

CSimpleString s(pMgr);
ASSERT(s.IsEmpty());

CSimpleStringT::FreeExtra

Освобождает дополнительную память, ранее выделенную строкой, но больше не требуется.

Синтаксис

void FreeExtra();

Замечания

Это должно снизить затраты на память, потребляемые строковым объектом. Метод перераспреждает буфер до точной длины, возвращаемой GetLength.

Пример

CAtlString basestr;
IAtlStringMgr* pMgr;

pMgr= basestr.GetManager();
ASSERT(pMgr != NULL);

// Create a CSimpleString with 28 characters
CSimpleString str(_T("Many sports are fun to play."), 28, pMgr);
_tprintf_s(_T("Alloc length is %d, String length is %d\n"),
   str.GetAllocLength(), str.GetLength());

// Assigning a smaller string won't cause CSimpleString to free its
// memory, because it assumes the string will grow again anyway.
str = _T("Soccer is best!");
_tprintf_s(_T("Alloc length is %d, String length is %d\n"),
   str.GetAllocLength(), str.GetLength());

// This call forces CSimpleString to release the extra
// memory it doesn't need.
str.FreeExtra();
_tprintf_s(_T("Alloc length is %d, String length is %d\n"),
   str.GetAllocLength(), str.GetLength());

Выходные данные из этого примера приведены следующим образом:

Alloc length is 1031, String length is 1024
Alloc length is 1031, String length is 15
Alloc length is 15, String length is 15

CSimpleStringT::GetAllocLength

Извлекает выделенную длину CSimpleStringT объекта.

Синтаксис

int GetAllocLength() const throw();

Возвращаемое значение

Количество символов, выделенных для этого объекта.

Замечания

Вызовите этот метод, чтобы определить количество символов, выделенных для этого CSimpleStringT объекта. См FreeExtra . пример вызова этой функции.

CSimpleStringT::GetAt

Возвращает один символ из CSimpleStringT объекта.

Синтаксис

XCHAR GetAt(int iChar) const;

Параметры

iChar
Отсчитываемый от нуля индекс символа в объекте CSimpleStringT . Параметр iChar должен быть больше или равен 0 и меньше значения, возвращаемого GetLength. GetAt В противном случае будет создано исключение.

Возвращаемое значение

Объект, XCHAR содержащий символ в указанной позиции в строке.

Замечания

Вызовите этот метод, чтобы вернуть один символ, указанный в iChar. Перегруженный оператор подстрочного ([]) — удобный псевдоним.GetAt Конечный элемент NULL можно адресировать без создания исключения с помощью GetAt. Однако он не учитывается GetLength, и возвращаемое значение равно 0.

Пример

В следующем примере показано, как использовать CSimpleStringT::GetAt.

CSimpleString s(_T("abcdef"), pMgr);
ASSERT(s.GetAt(2) == _T('c'));

CSimpleStringT::GetBuffer

Возвращает указатель на внутренний буфер символов CSimpleStringT для объекта.

Синтаксис

PXSTR GetBuffer(int nMinBufferLength);
PXSTR GetBuffer();

Параметры

nMinBufferLength
Минимальное количество символов, которое может содержать буфер символов. Это значение не содержит пробела для конца null.

Если nMinBufferLength длина текущего буфера превышает длину текущего буфера, GetBuffer уничтожает текущий буфер, заменяет его буфером запрошенного размера и сбрасывает число ссылок на объект до нуля. Если вы ранее вызвали LockBuffer этот буфер, вы потеряете блокировку буфера.

Возвращаемое значение

Указатель PXSTR на буфер символов объекта (с пустым завершением).

Замечания

Вызовите этот метод, чтобы вернуть содержимое буфера CSimpleStringT объекта. Возвращаемый PXSTR объект не является константой и поэтому позволяет напрямую изменять содержимое CSimpleStringT .

При использовании указателя, возвращаемого GetBuffer для изменения содержимого строки, необходимо вызвать ReleaseBuffer обновление внутреннего состояния CSimpleStringT , прежде чем использовать любые другие CSimpleStringT методы.

Адрес, возвращаемый GetBuffer недействителен после вызова ReleaseBuffer , так как дополнительные CSimpleStringT операции могут привести CSimpleStringT к перераспределению буфера. Буфер не перераспределен, если длина буфера CSimpleStringTне изменяется.

Буферная память автоматически освобождается при CSimpleStringT уничтожении объекта.

Если вы отслеживаете длину строки самостоятельно, не следует добавлять завершающий символ NULL. Однако при освобождении буфера ReleaseBufferнеобходимо указать окончательную длину строки. Если вы добавите завершающий символ NULL, необходимо передать значение -1 (значение по умолчанию) для длины. ReleaseBuffer затем определяет длину буфера.

Если для выполнения GetBuffer запроса недостаточно памяти, этот метод создает CMemoryException*исключение.

Пример

CSimpleString s(_T("abcd"), pMgr);
LPTSTR pBuffer = s.GetBuffer(10);
int sizeOfBuffer = s.GetAllocLength();

// Directly access CSimpleString buffer
_tcscpy_s(pBuffer, sizeOfBuffer, _T("Hello"));
ASSERT(_tcscmp(s, _T("Hello")) == 0);
s.ReleaseBuffer();

CSimpleStringT::GetBufferSetLength

Возвращает указатель на внутренний буфер символов для CSimpleStringT объекта, усечение или увеличение его длины при необходимости, чтобы точно соответствовать длине, указанной в nLength.

Синтаксис

PXSTR GetBufferSetLength(int nLength);

Параметры

nLength
Точный размер буфера CSimpleStringT символов в символах.

Возвращаемое значение

Указатель PXSTR на буфер символов объекта ,завершаемый значением NULL.

Замечания

Вызовите этот метод, чтобы получить указанную длину внутреннего буфера CSimpleStringT объекта. Возвращаемый PXSTR указатель не const является и таким образом позволяет напрямую изменять содержимое CSimpleStringT .

При использовании указателя, возвращаемого GetBufferSetLength для изменения содержимого CSimpleStringT строки, вызовите ReleaseBuffer обновление внутреннего состояния перед использованием других CSimpleStringT методов.

Адрес, возвращаемый GetBufferSetLength недействителен после вызова ReleaseBuffer , так как дополнительные CSimpleStringT операции могут привести CSimpleStringT к перераспределению буфера. Буфер не переназначается, если длина буфера CSimpleStringTне изменяется.

Буферная память автоматически освобождается при CSimpleStringT уничтожении объекта.

Если вы отслеживаете длину строки самостоятельно, не добавляйте завершающий символ NULL. При освобождении буфера ReleaseBufferнеобходимо указать окончательную длину строки. Если при вызове добавляется ReleaseBufferзавершающийся символ NULL, передайте значение -1 (значение по умолчанию) для длины ReleaseBufferи ReleaseBuffer будет выполняться strlen на буфере, чтобы определить его длину.

Дополнительные сведения о подсчете ссылок см. в следующих статьях:

Пример

В следующем примере показано использование функции CSimpleStringT::GetBufferSetLength.

CSimpleString str(pMgr);
LPTSTR pstr = str.GetBufferSetLength(3);
pstr[0] = _T('C');
pstr[1] = _T('u');
pstr[2] = _T('p');
str.ReleaseBuffer();

str += _T(" soccer is best!");
ASSERT(_tcscmp(str, _T("Cup soccer is best!")) == 0);

CSimpleStringT::GetLength

Возвращает количество символов в объекте CSimpleStringT .

Синтаксис

int GetLength() const throw();

Возвращаемое значение

Количество символов в строке.

Замечания

Вызовите этот метод, чтобы вернуть количество символов в объекте. Число не включает терминатор NULL.

Для многобайтовых наборов символов (MBCS) GetLength подсчитывает каждый 8-разрядный символ, т. е. байт свинца и байт в одном многобайтовом символе считаются двумя байтами. См FreeExtra . пример вызова этой функции.

CSimpleStringT::GetManager

Извлекает диспетчер CSimpleStringT памяти объекта.

Синтаксис

IAtlStringMgr* GetManager() const throw();

Возвращаемое значение

Указатель на диспетчер памяти для CSimpleStringT объекта.

Замечания

Вызовите этот метод, чтобы получить диспетчер памяти, используемый CSimpleStringT объектом. Дополнительные сведения о диспетчерах памяти и строковых объектах см. в разделе "Управление памятью" и CStringT..

CSimpleStringT::GetString

Извлекает строку символа.

Синтаксис

PCXSTR GetString() const throw();

Возвращаемое значение

Указатель на строку символов, завершаемую значением NULL.

Замечания

Вызовите этот метод, чтобы получить символьную строку, связанную с CSimpleStringT объектом.

Примечание.

Возвращаемый PCXSTR указатель не const допускает прямого изменения содержимого CSimpleStringT .

Пример

В следующем примере показано использование функции CSimpleStringT::GetString.

CAtlString basestr;
IAtlStringMgr* pMgr = basestr.GetManager();   
CSimpleString str(pMgr);
str += _T("Cup soccer is best!");
_tprintf_s(_T("%s"), str.GetString());

Выходные данные из этого примера приведены следующим образом:

Cup soccer is best!

CSimpleStringT::IsEmpty

CSimpleStringT Проверяет объект для пустого условия.

Синтаксис

bool IsEmpty() const throw();

Возвращаемое значение

Возвращает значение TRUE , если CSimpleStringT объект имеет длину 0; в противном случае FALSE.

Замечания

Вызовите этот метод, чтобы определить, содержит ли объект пустую строку.

Пример

В следующем примере показано использование функции CSimpleStringT::IsEmpty.

CSimpleString s(pMgr);
ASSERT(s.IsEmpty());

CSimpleStringT::LockBuffer

Отключает подсчет ссылок и защищает строку в буфере.

Синтаксис

PXSTR LockBuffer();

Возвращаемое значение

Указатель на CSimpleStringT объект или строку, завершаемую значением NULL.

Замечания

Вызовите этот метод, чтобы заблокировать буфер CSimpleStringT объекта. При вызове LockBufferсоздается копия строки с значением -1 для счетчика ссылок. Если значение счетчика ссылок равно -1, строка в буфере считается заблокированной. Хотя в заблокированном состоянии строка защищена двумя способами:

  • Другая строка не может получить ссылку на данные в заблокированной строке, даже если эта строка назначена заблокированной строке.

  • Заблокированная строка никогда не будет ссылаться на другую строку, даже если другая строка копируется в заблокированную строку.

Заблокируя строку в буфере, убедитесь, что монопольная удержание строки в буфере останется нетронутым.

После завершения LockBufferвызова для UnlockBuffer сброса счетчика ссылок до 1.

Примечание.

Если вы вызываете GetBuffer заблокированный буфер и задаете GetBuffer для параметра nMinBufferLength значение больше длины текущего буфера, вы потеряете блокировку буфера. Такой вызов GetBuffer для уничтожения текущего буфера, заменяет его буфером запрошенного размера и сбрасывает число ссылок на ноль.

Дополнительные сведения о подсчете ссылок см. в следующих статьях:

Пример

В следующем примере показано использование функции CSimpleStringT::LockBuffer.

CAtlString basestr;
IAtlStringMgr* pMgr = basestr.GetManager();

CSimpleString str(_T("Hello"), pMgr);
TCHAR ch;

str.LockBuffer();
ch = str.GetAt(2);
_tprintf_s(_T("%c"), ch);
str.UnlockBuffer();

Выходные данные из этого примера приведены следующим образом:

l

CSimpleStringT::operator[]

Вызовите эту функцию для доступа к одному символу массива символов.

Синтаксис

XCHAR operator[](int iChar) const;

Параметры

iChar
Отсчитываемый от нуля индекс символа в строке.

Замечания

Перегруженный оператор подстрочного ([]) возвращает один символ, заданный отсчитываемым от нуля индексом iChar. Этот оператор является удобной заменой GetAt функции-члена.

Примечание.

Оператор подстрочного ([]) можно использовать для получения значения символа в объекте CSimpleStringT, но его нельзя использовать для изменения значения символа в символе CSimpleStringT.

Пример

В следующем примере показано использование функции CSimpleStringT::operator [].

CSimpleString s(_T("abc"), pMgr);
ASSERT(s[1] == _T('b'));

CSimpleStringT::operator []

Вызовите эту функцию для доступа к одному символу массива символов.

Синтаксис

XCHAR operator[](int iChar) const;

Параметры

iChar
Отсчитываемый от нуля индекс символа в строке.

Замечания

Перегруженный оператор подстрочного ([]) возвращает один символ, заданный отсчитываемым от нуля индексом iChar. Этот оператор является удобной заменой GetAt функции-члена.

Примечание.

Оператор подстрочного ([]) можно использовать для получения значения символа в объекте CSimpleStringT, но его нельзя использовать для изменения значения символа в символе CSimpleStringT.

CSimpleStringT::operator +=

Присоединяет новую строку или символ к концу существующей строки.

Синтаксис

CSimpleStringT& operator +=(PCXSTR pszSrc);
CSimpleStringT& operator +=(const CSimpleStringT& strSrc);
template<int t_nSize>
CSimpleStringT& operator+=(const CStaticString< XCHAR, t_nSize >& strSrc);
CSimpleStringT& operator +=(char ch);
CSimpleStringT& operator +=(unsigned char ch);
CSimpleStringT& operator +=(wchar_t ch);

Параметры

pszSrc
Указатель на строку, завершаемую значением NULL.

strSrc
Указатель на существующий CSimpleStringT объект.

ch
Символ значение для добавления.

Замечания

Оператор принимает другой CSimpleStringT объект или символ. Обратите внимание, что исключения памяти могут возникать при использовании этого оператора объединения, так как новое хранилище может быть выделено для символов, добавленных в этот CSimpleStringT объект.

Пример

В следующем примере показано использование функции CSimpleStringT::operator +=.

CSimpleString str(_T("abc"), pMgr);
ASSERT(_tcscmp((str += _T("def")), _T("abcdef")) == 0);

CSimpleStringT::operator =

Назначает новое значение объекту CSimpleStringT .

Синтаксис

CSimpleStringT& operator =(PCXSTR pszSrc);
CSimpleStringT& operator =(const CSimpleStringT& strSrc);

Параметры

pszSrc
Указатель на строку, завершаемую значением NULL.

strSrc
Указатель на существующий CSimpleStringT объект.

Замечания

Если целевая строка (левая сторона) уже достаточно велика для хранения новых данных, не выполняется выделение новой памяти. Обратите внимание, что исключения памяти могут возникать всякий раз, когда используется оператор назначения, так как новое хранилище часто выделяется для хранения результирующего CSimpleStringT объекта.

Пример

В следующем примере показано использование функции CSimpleStringT::operator =.

CSimpleString s1(pMgr), s2(pMgr);
// Empty CSimpleStringT objects

s1 = _T("cat");
// s1 = "cat"
ASSERT(_tcscmp(s1, _T("cat")) == 0);

s2 = s1;               // s1 and s2 each = "cat"
ASSERT(_tcscmp(s2, _T("cat")) == 0);

s1 = _T("the ") + s1;
// Or expressions
ASSERT(_tcscmp(s1, _T("the cat")) == 0);

s1 = _T("x");
// Or just individual characters
ASSERT(_tcscmp(s1, _T("x")) == 0);

CSimpleStringT::operator PCXSTR

Непосредственно обращается к символам, хранящимся в объекте CSimpleStringT в виде строки стиля C.

Синтаксис

operator PCXSTR() const throw();

Возвращаемое значение

Указатель символа на данные строки.

Замечания

Символы не копируются; Возвращается только указатель. Будьте осторожны с этим оператором. При изменении CString объекта после получения указателя символов может возникнуть перемещение памяти, которая делает указатель недействительным.

Пример

В следующем примере показано использование функции CSimpleStringT::operator PCXSTR.

// If the prototype of a function is known to the compiler,
// the PCXSTR cast operator may be invoked implicitly.

CSimpleString strSports(L"Soccer is Best!", pMgr);
WCHAR sz[1024];

wcscpy_s(sz, strSports);

// If the prototype isn't known or is a va_arg prototype,
// you must invoke the cast operator explicitly. For example,
// the va_arg part of a call to swprintf_s() needs the cast:

swprintf_s(sz, 1024, L"I think that %s!\n", (PCWSTR)strSports);

// While the format parameter is known to be an PCXSTR and
// therefore doesn't need the cast:

swprintf_s(sz, 1024, strSports);

// Note that some situations are ambiguous. This line will
// put the address of the strSports object to stdout:

wcout << strSports;

// while this line will put the content of the string out:

wcout << (PCWSTR)strSports;

CSimpleStringT::PCXSTR

Указатель на константную строку.

Синтаксис

typedef ChTraitsBase< BaseType >::PCXSTR PCXSTR;

CSimpleStringT::Preallocate

Выделяет определенный объем байтов для CSimpleStringT объекта.

Синтаксис

void Preallocate( int nLength);

Параметры

nLength
Точный размер буфера CSimpleStringT символов в символах.

Замечания

Вызовите этот метод, чтобы выделить определенный размер буфера CSimpleStringT для объекта.

CSimpleStringT создает STATUS_NO_MEMORY исключение, если не удается выделить пространство для буфера символов. По умолчанию выделение памяти выполняется функциями HeapAlloc API WIN32 или HeapReAlloc.

Пример

В следующем примере показано использование функции CSimpleStringT::Preallocate.

CAtlString basestr;
IAtlStringMgr* pMgr = basestr.GetManager();

CSimpleString str(pMgr);
_tprintf_s(_T("Allocated length: %d\n"), str.GetAllocLength());
str.Preallocate(100);
_tprintf_s(_T("Allocated length: %d\n"), str.GetAllocLength());

Выходные данные из этого примера приведены следующим образом:

Allocated length: 0
Allocated length: 103

CSimpleStringT::PXSTR

Указатель на строку.

Синтаксис

typedef ChTraitsBase< BaseType >::PXSTR PXSTR;

CSimpleStringT::ReleaseBuffer

Освобождает элемент управления буфером, выделенным GetBuffer.

Синтаксис

void ReleaseBuffer(int nNewLength = -1);

Параметры

nNewLength
Новая длина строки в символах, а не подсчет конца null. Если строка завершается null, значение -1 по умолчанию задает CSimpleStringT размер текущей длины строки.

Замечания

Вызовите этот метод, чтобы перераспределить или освободить буфер объекта строки. Если вы знаете, что строка в буфере завершается null, можно опустить nNewLength аргумент. Если строка не завершена null, используйте nNewLength для указания его длины. Адрес, возвращенный недопустимым GetBuffer после вызова ReleaseBuffer или любой другой CSimpleStringT операции.

Пример

В следующем примере показано использование функции CSimpleStringT::ReleaseBuffer.

const int bufferSize = 1024;
CSimpleString s(_T("abc"), pMgr);
LPTSTR p = s.GetBuffer(bufferSize);
_tcscpy_s(p, bufferSize, _T("abc"));

// use the buffer directly
ASSERT(s.GetLength() == 3);

// String length = 3
s.ReleaseBuffer();

// Surplus memory released, p is now invalid.
ASSERT(s.GetLength() == 3);

// Length still 3

CSimpleStringT::ReleaseBufferSetLength

Освобождает элемент управления буфером, выделенным GetBuffer.

Синтаксис

void ReleaseBufferSetLength(int nNewLength);

Параметры

nNewLength
Длина выпуска строки

Замечания

Эта функция функционально похожа на ReleaseBuffer то, что допустимая длина для строкового объекта должна быть передана.

CSimpleStringT::SetAt

Задает один символ из CSimpleStringT объекта.

Синтаксис

void SetAt(int iChar, XCHAR ch);

Параметры

iChar
Отсчитываемый от нуля индекс символа в объекте CSimpleStringT . Параметр iChar должен быть больше или равен 0 и меньше значения, возвращаемого GetLength.

ch
Новый символ.

Замечания

Вызовите этот метод, чтобы перезаписать символ, расположенный по адресу iChar. Этот метод не увеличит строку, если iChar превышает границы существующей строки.

Пример

В следующем примере показано использование функции CSimpleStringT::SetAt.

CSimpleString s(_T("abcdef"), pMgr);
s.SetAt(1, _T('a'));
ASSERT(_tcscmp(s, _T("aacdef")) == 0);

CSimpleStringT::SetManager

Задает диспетчер CSimpleStringT памяти объекта.

Синтаксис

void SetManager(IAtlStringMgr* pStringMgr);

Параметры

pStringMgr
Указатель на новый диспетчер памяти.

Замечания

Вызовите этот метод, чтобы указать новый диспетчер памяти, используемый CSimpleStringT объектом. Дополнительные сведения о диспетчерах памяти и строковых объектах см. в разделе "Управление памятью" и CStringT..

Пример

В следующем примере показано использование функции CSimpleStringT::SetManager.

CSimpleString s(pMgr);
s.SetManager(pCustomMgr);

CSimpleStringT::SetString

Задает строку CSimpleStringT объекта.

Синтаксис

void SetString(PCXSTR pszSrc, int nLength);
void SetString(PCXSTR pszSrc);

Параметры

pszSrc
Указатель на строку, завершаемую значением NULL.

nLength
Количество символов в pszSrc.

Замечания

Скопируйте строку в CSimpleStringT объект. SetString перезаписывает старые строковые данные в буфере.

Обе версии SetString проверки, является ли pszSrc указатель null, и если это так, возникает E_INVALIDARG ошибка.

Версия SetString одного параметра указывает pszSrc на строку, завершаемую значением NULL.

Версия SetString двух параметров также ожидает pszSrc , что она будет строкой, завершающейся значением NULL. Она используется nLength в качестве длины строки, если она не встречается с конечным элементом NULL.

Версия SetString двух параметров также проверяет, указывает ли pszSrc расположение в текущем буфере CSimpleStringT. В этом случае использует функцию копирования памяти, SetString которая не перезаписывает строковые данные, так как она копирует строковые данные обратно в буфер.

Пример

В следующем примере показано использование функции CSimpleStringT::SetString.

CSimpleString s(_T("abcdef"), pMgr);
ASSERT(_tcscmp(s, _T("abcdef")) == 0);
s.SetString(_T("Soccer"), 6);
ASSERT(_tcscmp(s, _T("Soccer")) == 0);

CSimpleStringT::StringLength

Возвращает количество символов в указанной строке.

Синтаксис

ATL_NOINLINE static int StringLength(PCXSTR psz) throw();

Параметры

psz
Указатель на строку, завершаемую значением NULL.

Возвращаемое значение

Число символов в psz; не подсчитывает терминатор NULL.

Замечания

Вызовите этот метод, чтобы получить количество символов в строке, на которую указывает psz.

Пример

В следующем примере показано использование функции CSimpleStringT::StringLength.

ASSERT(CSimpleString::StringLength(_T("soccer")) == 6);

CSimpleStringT::Truncate

Усечение строки до новой длины.

Синтаксис

void Truncate(int nNewLength);

Параметры

nNewLength
Новая длина строки.

Замечания

Вызовите этот метод, чтобы усечь содержимое строки до новой длины.

Примечание.

Это не влияет на выделенную длину буфера. Чтобы уменьшить или увеличить текущий буфер, см FreeExtra . и Preallocate.

Пример

В следующем примере показано использование функции CSimpleStringT::Truncate.

CAtlString basestr;
IAtlStringMgr* pMgr = basestr.GetManager();
CSimpleString str(_T("abcdefghi"), pMgr);
_tprintf_s(_T("String length: %d / Allocated length: %d\n"), str.GetLength(), str.GetAllocLength());
_tprintf_s(_T("Contents: %s\n"), (LPCTSTR)str);
str.Truncate(4);
_tprintf_s(_T("String length: %d / Allocated length: %d\n"), str.GetLength(), str.GetAllocLength());
_tprintf_s(_T("Contents: %s\n"), (LPCTSTR)str);

Выходные данные из этого примера:

String length: 9 / Allocated length: 15
Contents: abcdefghi
String length: 4 / Allocated length: 15
Contents: abcd

CSimpleStringT::UnlockBuffer

Разблокирует буфер CSimpleStringT объекта.

Синтаксис

void UnlockBuffer() throw();

Замечания

Вызовите этот метод, чтобы сбросить число ссылок строки до 1.

Деструктор CSimpleStringT автоматически вызывается UnlockBuffer , чтобы убедиться, что буфер не заблокирован при вызове деструктора. Пример этого метода см. в разделе LockBuffer.

CSimpleStringT::~CSimpleStringT

Уничтожает объект CSimpleStringT .

Синтаксис

~CSimpleStringT() throw();

Замечания

Вызовите этот метод для уничтожения CSimpleStringT объекта.

См. также

Диаграмма иерархии
Общие классы ATL/MFC