Используется для добавления члена в коллекцию.

Объект члена коллекции может иметь любой действительный тип, который мог бы быть присвоен переменной памяти. Это включает простые типы данных, такие, как строки, числа, даты, логические или более сложные типа, такие, как объекты Visual FoxPro и объекты Component Object Model (COM).

Collection.Add( eItem [, cKey [, [eBefore |, eAfter ]]] )

Параметры

eItem

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

Определяет необязательный, уникальный, алфавитно-цифровое (символьного типа) выражение, которое представляет собой ключевую строку, используемую вместо позиционного индекса и которая может быть использована для доступа к члену коллекции. Для коллекций, использующих ключи, cKey представляет собой регистро-чувствительный параметр, который не может быть пустым или представлять собой null значение (.NULL.). По соображениям эффективности либо все добавляемые в коллекцию члены должны иметь установленным параметр cKey, либо ни один из них. Первый элемент, добавляемый в коллекцию определяет поведение всей коллекции. Вы можете протестировать присутствие ключей в коллекции с помощью простейшего кода: GetKey(1). Если ключ для члена уже существует в коллекции - произойдет ошибка. Однако, так как cKey является регистро-чувствительным, если в коллекцию будут добавлены элементы с одним и тем же ключом, но с разными регистрами символов. Ключ включает в себя также все хвостовые пробелы, присутствующие в параметре cKey.
[, [ eBefore|, eAfter]]

Определяет необязательное выражение, которое представляет собой позицию, куда будет вставлен новый член - до или после существующего элемента коллекции. Вы можете указать либо eBefore, либо eAfter выражения, но не их обоих одновременно, что приведет к генерации соответствующего сообщения. Это выражение может быть одного из двух возможных типов:
  • Численное. Выражения eBefore и eAfter должны иметь значение в диапазоне от  1 до значения свойства Count коллекции.

  • Строковое. Выражения eBefore и eAfter должны соответсвовать cKey, который был указан для ссылаемого элемента, когда тот добавлялся в коллекцию.

Вставка нового элемента в коллекцию до или после уже существующего, требует, чтобы коллекция уже была коллекцией с ключами. Когда вы указываете значение cKey с параметром eBefore или eAfter, новый элемент добавляется до или после индексного значения указанного ключа. В этом случае, значение свойства KeySort объекта Collection не имеет воздействия на порядок ввода элементов. Например, предположим, что cKey для нового элемента имеет значение "ZZZ", а у существующего в коллекции элемента cKey был определен при вводе, как "YYY" и его индексное значение равно 15. Новый элемент должен получить индексное значение 15, а уже существующий получит новое значение индекса, равное  16. Для вставки нового элемента перед существующим элементом коллекции, включите ключ элемента коллекции, в качестве которого вы желаете вставить новый элемент перед уже существующим до ключа существующего элемента, как это показано в приведенном ниже примере:
  Скопировать код
loItems.Add("Roses", "flower1", "flower2")
Для того, чтобы вставить новый элемент после существующего в коллекции элемента, включите клю элемента, который вы желаете вставить в коллекцию после ключа уже существующего элемента коллекции. Дополнительно, вы должны направить методу пустой третий параметр, для eBefore,  как это показано в приведенном ниже примере:
  Скопировать код
loItems.Add("Orchids", "flower3",, "flower2")
Если eBefore и eAfter не ссылаются на существующего члена коллекции, произойдет ошибка. Visual FoxPro добавляет элемент в конец коллекции, если ни eBefore,  ни eAfter не указаны.

Примечания

При добавлении объектов в коллекции, Visual FoxPro увеличивает счетчик ссылок для этого объекта. В соответствии с обычным поведением объектов вVisual FoxPro, вы может освободить объект, только в случае, когда его счетчик ссылок равен нулю. Поэтому, вы должны убедиться, что ссылка на объект в коррекции освобождена, когда вы освобождаете объект; в противном случае, Visual FoxPro не удаляет объект полностью из памяти.

Вы не ограничены в числе элементов, которые вы можете добавить в коллекцию. Однако, размер коллекции может подействовать на эффективность операци, таких как доступ, поиск и прохождение по элементам в коллекции. Например, создание большой коллекции, основанной на записях из очень большой таблицы (.dbf) не рекомендуется, так как вы не сможете использовать оптимизацию запроса и прочиек возможности, связанные с родным движком обработки данных Visual FoxPro.

Вы можете иметь коллекцию коллекций, так как сама коллекция представляет собой объект. Избегайте, однако, создания циркулярных ссылок, таких как попытка добавить внешнюю коллекцию, во внутреннюю.

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

  Скопировать код
DIMENSION x[3]
x[1] = 1
x[2] = 22
x[3] = 333
y = CREATEOBJECT("collection")
y.Add(@x)
z = y.item(1) && Возвращает именно первый элемент
? z[2] && Ошибка

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

Вы можете послать значение NULL как тип элемента и использовать фукнции TYPE( ) и VARTYPE( ) для запроса типа элемента коллекции.

Вы можете добавлять элементы смешанных типов. Однако, Visual FoxPro не обеспечивает соблюдения безопасности типа, так что должны предоставить это в классе, если это требуется. Если в качестве определенного параметра посылается некорректный тип, происходит ошибка.

Включите команду NODEFAULT в метод Add для объектов коллекции, для предотвращения ввода конкретного элемента в коллекцию.

Пример

Приведенный ниже пример иллюстрирует следующие задачи:

  • Добавляет четыре элемента в коллекцию, используя параметр cKey.

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

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

  • Проходит через все элементы коллекции, отображая их на экране.

  Скопировать код
CLEAR
LOCAL loItems, lcFlower
loItems = NEWOBJECT("Collection")
loItems.Add("Daffodils", "flower2")
* Добавляет "Roses" с ключом "flower1" перед "flower2".
loItems.Add("Roses", "flower1", "flower2")
loItems.Add("Daisies", "flower4")
* Добавляет "Orchids" с ключом "flower4" после "flower2".
loItems.Add("Orchids","flower3",,"flower2")
FOR EACH lcFlower IN loItems
? lcFlower
ENDFOR

Следующий пример генерирует ошибку, так как вы не можете одновременно указать оба - .eBefore и eAfter параметра.

  Скопировать код
* Генерирует ошиюка, так как указаны оба параметра eBefore и eAfter.
loItems.Add("Violets","flower5","flower2","flower1")

Смотрите также