Работа со строками

Группа функций, предназначенных для работы с данными типа string.

 

StringAdd

Присоединяет к концу строки по месту указанную подстроку.

bool StringAdd(
 string& string_var, // строка, к которой добавляем
 string add_substring // добавляемая строка
 );

Параметры

string_var — [in][out] Строка, которая будет дополнена.

add_substring — [in] Строка, которая будет добавлена в конец исходной строки.

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

В случае успешного выполнения возвращает true, иначе false. Для получения кода ошибки нужно вызвать функцию GetLastError().

Пример:

void OnStart()
{
   long length=1000000;
   string a="a",b="b",c;

   //--- первый способ
   uint start=GetTickCount(),stop;
   long i;

   for(i=0;i<length;i++)
   {
      c=a+b;
   }

   stop=GetTickCount();
   Print("time for 'c = a + b' = ",(stop-start)," milliseconds, i = ",i);

   //--- второй способ
   start=GetTickCount();
   for(i=0;i<length;i++)
   {
      StringAdd(a,b);
   }

   stop=GetTickCount();
   Print("time for 'StringAdd(a,b)' = ",(stop-start)," milliseconds, i = ",i);
 
   //--- третий способ
   start=GetTickCount();

   a="a"; // заново инициализируем переменную a
   for(i=0;i<length;i++)
   {
      StringConcatenate(c,a,b);
   }

   stop=GetTickCount();
   Print("time for 'StringConcatenate(c,a,b)' = ",(stop-start)," milliseconds, i = ",i);
}

 

StringBufferLen

Возвращает размер буфера, распределенного для строки.

int StringBufferLen(
 string string_var // строка
 )

Параметры

string_var — [in] Строка.

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

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

Пример:

void OnStart()
{
   long length=1000;
   string a="a",b="b";
   long i;

   Print("before: StringBufferLen(a) = ",StringBufferLen(a),
         "  StringLen(a) = ",StringLen(a));

   for(i=0;i<length;i++)
   {
      StringAdd(a,b);
   }

   Print("after: StringBufferLen(a) = ",StringBufferLen(a),
         "  StringLen(a) = +-",StringLen(a));
}

 

StringCompare

Сравнивает между собой две строки и возвращает результат сравнения в виде целого числа.

int StringCompare(
 const string& string1, // первая сравниваемая строка
 const string& string2, // вторая сравниваемая строка
 bool case_sensitive=true // режим учета регистра букв при сравнении
 );

Параметры

string1 — [in] Первая строка.

string2 — [in] Вторая строка.

case_sensitive=true — [in] Режим учета регистра букв. Если значения равно true, то «A»>»a». Если значение равно false, то «A»=»a». По умолчанию значение параметра равно true.

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

-1 (минус один), если string1<string2
0 (ноль), если string1=string2
1 (один), если string1>string2

Примечание

Строки сравниваются посимвольно, символы сравниваются в алфавитном порядке в соответствии с текущей кодовой страницей.

Пример:

void OnStart()
{
   //--- что больше, яблоко или дом?
   string s1="Apple";
   string s2="home";
 
   //--- сравним с учетом регистра 
   int result1=StringCompare(s1,s2);
   if(result1>0) PrintFormat("Сравнение с учетом регистра: %s > %s",s1,s2);
   else
   {
      if(result1<0)PrintFormat("Сравнение с учетом регистра: %s < %s",s1,s2);
       else PrintFormat("Сравнение с учетом регистра: %s = %s",s1,s2);
   }
 
   //--- сравним без учета регистра
   int result2=StringCompare(s1,s2,false);

   if(result2>0) PrintFormat("Сравнение без учета регистра: %s > %s",s1,s2);
   else
   {
      if(result2<0)PrintFormat("Сравнение без учета регистра: %s < %s",s1,s2);
       else PrintFormat("Сравнение без учета регистра: %s = %s",s1,s2);
   }

/* Результат:
 Сравнение с учетом регистра: Apple < home
 Сравнение без учета регистра: Apple < home
*/
}

 

StringConcatenate

Формирует строку из переданных параметров и возвращает размер сформированной строки. Параметры могут иметь любой тип. Количество параметров не может быть меньше 2 и не может превышать 64.

int StringConcatenate(
 string& string_var, // строка для формирования
 void argument1 // первый параметр любого простого типа 
 void argument2 // второй параметр любого простого типа
 ... // следующий параметр любого простого типа
 );

Параметры

string_var — [out] Строка, которая будет сформирована в результате конкатенации.

argumentN — [in] Любые значения, разделенные запятыми. От 2 до 63 параметров любого простого типа.

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

Возвращает длину строки, сформированной путем конкатенации преобразованных в тип string параметров. Параметры преобразуются в строки по тем же правилам, что и в функциях Print() и Comment().

 

StringFill

Заполняет указанную строку по месту указанными символами.

bool StringFill(
 string& string_var, // строка для заполнения
 ushort character // символ, которым будет заполнена строка
 );

Параметры

string_var — [in][out] Строка, которая будет заполнена указанным символом.

character — [in] Символ, которым будет заполнена строка.

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

В случае успешного выполнения возвращает true, иначе false. Для получения кода ошибки нужно вызвать функцию GetLastError().

Примечание

Заполнение строки по месту означает, что символы вставляются непосредственно в строку без промежуточных операций создания новой строки и копирования. Это позволяет уменьшить время работы со строкой в данной функции.

Пример:

void OnStart()
{
   string str;
   StringInit(str,20,'_');
   Print("str = ",str);
   StringFill(str,0);
   Print("str = ",str,": StringBufferLen(str) = ", StringBufferLen(str));

   // Результат
   //   str = ____________________
   //   str =  : StringBufferLen(str) = 20
}

 

StringFind

Поиск подстроки в строке.

int StringFind(
 string string_value, // строка, в которой ищем
 string match_substring, // что ищем
 int start_pos=0 // с какой позиции начинать поиск
 );

Параметры

string_value — [in] Строка, в которой производится поиск.

match_substring — [in] Искомая подстрока.

start_pos=0 — [in] Позиция в строке, с которой должен быть начат поиск.

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

Возвращает номер позиции в строке, с которой начинается искомая подстрока, либо -1, если подстрока не найдена.

 

StringGetCharacter

Возвращает значение символа, расположенного в указанной позиции строки.

ushort StringGetCharacter(
 string string_value, // строка
 int pos // позиция символа в строке
 );

Параметры

string_value — [in] Строка.

pos — [in] Позиция символа в строке. Может быть от 0 до StringLen(text) -1.

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

Код символа либо 0 в случае какой-либо ошибки. Для получения кода ошибки нужно вызвать функцию GetLastError().

 

StringInit

Инициализирует строку указанными символами и обеспечивает указанный размер строки.

bool StringInit(
 string& string_var, // строка для инициализации
 int new_len=0, // требуемая длина строки после инициализации
 ushort character=0 // символ, которым будет заполнена строка
 );

Параметры

string_var — [in][out] Строка, которая должна быть инициализирована или деинициализирована.

new_len=0 — [in] Длина строки после инициализации. Если размер=0, то деинициализирует строку, то есть, буфер строки освобождается и адрес буфера обнуляется.

character=0 — [in] Символ для заполнения строки.

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

В случае успешного выполнения возвращает true, иначе false. Для получения кода ошибки нужно вызвать функцию GetLastError().

Примечание

Если character=0 и размер new_len>0, то будет распределен буфер строки указанного размера и заполнен нулями. Размер строки будет равен нулю, так как весь буфер заполнен терминаторами строки.

Пример:

void OnStart()
{
   string str;
   StringInit(str,200,0);
   Print("str = ",str,": StringBufferLen(str) = ",
   StringBufferLen(str)," StringLen(str) = ",StringLen(str));
}

/* Результат
str = : StringBufferLen(str) = 200 StringLen(str) = 0
*/

 

StringLen

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

int StringLen(
 string string_value // строка
 );

Параметры

string_value — [in] Строка для вычисления длины.

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

Количество символов в строке без учета завершающего нуля.

 

StringReplace

Заменяет в строке все найденные подстроки на заданную последовательность символов.

int StringReplace(
 string& str, // строка, в которой будет осуществляться замена
 const string find, // искомая подстрока
 const string replacement // подстрока, которая будет вставлена в найденные места
 );

Параметры

str — [in][out] Строка, в которой необходимо произвести замены.

find — [in] Искомая подстрока для замены.

replacement — [in] Подстрока, которая будет вставлена вместо найденной.

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

Количество произведенных замен в случае успеха, в случае ошибки -1. Для получения кода ошибки нужно вызвать функцию GetLastError().

Примечание

Если функция успешно отработала, но замены не произведены (не найдена заменяемая подстрока), то возвращается 0.

Причиной ошибки могут быть неверные параметры str или find (пустая или неинициализировання строка, см. StringInit() ). Кроме того, ошибка возникнет, если для завершения замен недостаточно памяти.

Пример:

void OnStart()
{
   string text="The quick brown fox jumped over the lazy dog.";
   int replaced=StringReplace(text,"quick","slow");
 
   replaced+=StringReplace(text,"brown","black");
   replaced+=StringReplace(text,"fox","bear");

   Print("Replaced: ", replaced,". Result=",text);
 
   // Результат
   // Replaced: 3. Result=The slow black bear jumped over the lazy dog.
}

 

StringSetCharacter

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

bool StringSetCharacter(
 string& string_var, // строка
 int pos, // позиция
 ushort character // символ
 );

Параметры

string_var — [in][out] Строка.

pos — [in] Позиция символа в строке. Может быть от 0 до StringLen(text).

character — [in] Символьный код Unicode.

Примечание

Если значение pos меньше длины строки и значение символьного кода = 0, то строка усекается (но размер буфера, распределенного под строку остается неизменным). Длина строки становится равной значению pos.

Если значение параметра pos равняется значению длины строки, то указанный символ добавляется в конец строки, и таким образом длина строки увеличивается на единицу.

Пример:

void OnStart()
{
   string str="0123456789";
   Print("before: str = ",str,",StringBufferLen(str) = ",
   StringBufferLen(str)," StringLen(str) = ",StringLen(str));

   //--- вставим нулевое значение посреди строки
   StringSetCharacter(str,6,0);
   Print(" after: str = ",str,",StringBufferLen(str) = ",
   StringBufferLen(str)," StringLen(str) = ",StringLen(str));

   //--- добавим символ в конец строки
   int size=StringLen(str);
   StringSetCharacter(str,size,'+');
   Print("addition: str = ",str,",StringBufferLen(str) = ",
   StringBufferLen(str)," StringLen(str) =",StringLen(str));
}

/* Результат
 before: str = 0123456789 ,StringBufferLen(str) = 0 StringLen(str) = 10
 after: str = 012345 ,StringBufferLen(str) = 16 StringLen(str) = 6
 addition: str = 012345+ ,StringBufferLen(str) = 16 StringLen(str) = 7
*/

 

StringSplit

Получает из указанной строки подстроки по заданному разделителю и возвращает количество полученных подстрок.

int StringSplit(
 const string string_value, // строка для поиска подстрок
 const ushort separator, // разделитель, по которому в строке будут искаться подстроки
 string & result[] // массив, переданный по ссылке, для получения найденных подстрок
 );

Параметры

string_value — [in] Строка, из которой необходимо получить подстроки. Сама строка при этом не изменяется.

pos — [in] Код символа разделителя. Для получения кода можно использовать функцию StringGetCharacter().

result[] — [out] Массив строк, в который помещаются полученные подстроки.

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

Количество полученных строк в массиве result[]. Если разделитель в переданной строке не найден, то в массив будет помещена только одна исходная строка.

Если строка string_value пустая или NULL, то функция вернет ноль. В случае ошибки функция вернет -1. Для получения кода ошибки нужно вызвать функцию GetLastError().

Пример:

string to_split="_EURUSD_USDCHF_XAUUSD_"; // строка для разбивки на подстроки
string sep="_";                           // разделитель в виде символа
ushort u_sep;                             // код символа разделителя
string result[];                          // массив для получения строк


void OnStart()
{
   //--- получим код разделителя
   u_sep=StringGetCharacter(sep,0);

   //--- разобьем строку на подстроки
   int k=StringSplit(to_split,u_sep,result);

   //--- выведем комментарий 
   PrintFormat("Получено строк: %d. Использован разделитель '%s' с кодом %d",k,sep,u_sep);

   //--- теперь выведем все полученные строки
   if(k>0)
   {
       for(int i=0;i<k;i++)
       {
            PrintFormat("result[%d]=\"%s\"",i,result[i]);
       }
   }
}

 

StringSubstr

Извлекает подстроку из текстовой строки, начинающейся c указанной позиции.

string StringSubstr(
 string string_value, // строка
 int start_pos, // с какой позиции начать
 int length=-1 // длина извлекаемой строки
 );

Параметры

string_value — [in] Строка, из которой должна быть извлечена подстрока.

start_pos — [in] Начальная позиция подстроки. Может быть от 0 до StringLen(text) -1.

length=-1 — [in] Длина извлекаемой подстроки. Если значение параметра равно -1 либо параметр не задан, то будет извлекаться подстрока, начиная с указанной позиции и до конца строки.

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

Копия извлеченной подстроки, если возможно, иначе возвращается пустая строка.

 

StringToLower

Преобразует все символы указанной строки в строчные (маленькие) по месту.

bool StringToLower(
 string& string_var // строка для обработки
 );

Параметры

string_var — [in][out] Строка.

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

В случае успешного выполнения возвращает true, иначе false. Для получения кода ошибки нужно вызвать функцию GetLastError().

 

StringToUpper

Преобразует все символы указанной строки в прописные (большие) по месту.

bool StringToUpper(
 string& string_var // строка для обработки
 );

Параметры

string_var — [in][out] Строка.

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

В случае успешного выполнения возвращает true, иначе false. Для получения кода ошибки нужно вызвать функцию GetLastError().

 

StringTrimLeft

Удаляет символы перевода каретки, пробелы и символы табуляции с начала строки до первого значимого символа. Строка модифицируется по месту.

int StringTrimLeft(
 string& string_var // строка для обрезки
 );

Параметры

string_var — [in][out] Строка, которая должна быть обрезана слева.

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

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

 

StringTrimRight

Удаляет символы перевода каретки, пробелы и символы табуляции от последнего значимого символа до конца строки. Строка модифицируется по месту.

int StringTrimRight(
 string& string_var // строка для обрезки
 );

Параметры

string_var — [in][out] Строка, которая должна быть обрезана справа.

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

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