List.Add

Add (Добавление элемента)
Объект: Список Статус разработки: Реализована Тип: Функция Обращение к БД: Нет Исключения: Виз. объект только для чтения Визуальность: Нет

• Начальная страница
• Общее описание
• Объекты
• Список

Функция добавляет к списку значение и присваивает ему строковое представление и иконку, сохраняя сортировку списка при необходимости

Синтаксис

List.Add(<Значение>,<Строковое представление (STRING)>,<Индекс иконки (INT)>,<Сортировка (INT)>=0):<Позиция добавленного значения (INT)>

Аргументы

• <Значение> - Добавляемое значение
• <Строковое представление (STRING)> - (необязательный аргумент) Строковое представление добавляемого значения
• <Индекс иконки (INT)> - (необязательный аргумент) Индекс иконки добавляемого значения
• <Сортировка (INT)>=0 - (необязательный аргумент) Если список отсортирован по значениям по неубыванию, функция Add вставляет новое значение таким образом, чтобы не нарушилась сортировка. Режим может использоваться при необходимости последовательного добавления элементов в список, для которого важна сортировка (к примеру, будет использоваться функция Find с флагом сортировки). Как альтернатива, список можно отсортировать перед началом блока с поиском, но в случае, если в одном блоке происходит и добавление элементов и поиск элементов, данный режим будет работать гораздо быстрее, чем последовательные вызовы сортировки перед каждым поиском (см. пример ниже). Возможные значения:
  • 0 -- Список не был отсортирован, сортировка не будет сохранена.
  • 1 -- Список был отсортирован, если в списке уже имеются значения, равные добавляемому, значение будет добавлено после всех существующих значений, сортировка будет сохранена.
  • 2 -- Список был отсортирован, если в списке уже имеются значения, равные добавляемому, значение будет добавлено в произвольное место среди этих значений, сортировка будет сохранена (данный режим немного быстрее режима 1).

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

Функция возвращает индекс (позицию) добавленного значения.

Примеры

a:=List.Create();			//Список пуст
a.Add(123);				//Список содержит значение 123
a.Add(234,"Второй");			//Список содержит значения 123 и 234, у второго элемента есть строковое представление "Второй"

Сравнение скорости работы функций с сортировкой и функций без сортировки

Данный пример сравнивает скорость работы функции Find для сортированного и не сортированного списков. Внутри цикла поиска также происходит увеличение массива с помощью функции Add для проверки корректности ее работы.

ProfilerClear();
ProfilerStart();

randomize(1);
aList:=List.Create();
For i:=1 To 100000 Do
  aList.Add(Random(10000));
EndDo;

aList.Sort();
For i:=1 To 10000 Do
  j:=Random(aList.Size())+1;
  aNum:=aList.Get(j);
  While _And(j>1,aList.Get(j-1)=aNum) Do
    j:=j-1;
  EndDo;
  j2:=aList.Find(aNum,,1);
  If j<>j2 Then
    Message("Проблема при поиске значения!","!");
  EndIf;
  //Добавление случайного значения внутри цикла поиска
  aList.Add(Random(10000),,,1);
EndDo;  

randomize(1);
aList:=List.Create();
For i:=1 To 100000 Do
  aList.Add(Random(10000));
EndDo;

aList.Sort();
For i:=1 To 10000 Do
  j:=Random(aList.Size())+1;
  aNum:=aList.Get(j);
  While _And(j>1,aList.Get(j-1)=aNum) Do
    j:=j-1;
  EndDo;
  j2:=aList.Find(aNum);
  If j<>j2 Then
    Message("Проблема при поиске значения (2)!","!");
  EndIf;
  //Добавление случайного значения внутри цикла поиска, в данном примере нас интересует сравнительная скорость работы функции Add с сортировкой, поэтому
  //  этот блок не имеет большого значения, кроме как поддержание соответствия может циклами
  //Дополнение: j2 не будет возвращать 0 для последовательности, инициированной randomize(1), в ином случае, возможно, потребуется дополнительная проверка
  j:=Random(10000);
  j2:=aList.Find(j,,1);
  aList.Insert(j2,j);
EndDo;  

ProfilerStop();
debugbreak;

Message("Done!");
//Для i5, конечные результаты для среднего времени исполнения каждой операции:
//aList.Sort();                   -- 3 сек./1
//j2:=aList.Find(aNum,,1);        -- 30.5 мс./10000
//aList.Add(Random(10000),,,1);   -- 640 мс./10000
//j2:=aList.Find(aNum);           -- 31733 мс./10000
//aList.Insert(j2,j);             -- 690 мс./10000
//
//Как показывает эксперимент, для больших массивов поиск в сортированном массиве имеет очень большое преимущество перед поиском без учета сортировки (1000 раз в нашем случае), 
//  преимущество будет только расти при увеличении количества элементов в массиве
//Сортировка больших массивов работает достаточно медленно, поэтому, в циклах, где происходит одновременное добавление и поиск элементов списка, гораздо выгоднее использовать
//  функцию добавления с сортировкой, нежели множественные вызовы сортировки перед поиском.