Значение в массив в 1С через БСП: ЗначениеВМассиве и работа с массивами

ЗначениеВМассиве: положить значение в массив одной строкой

Задача «одно значение → массив из одного элемента» встречается везде, где API ждёт коллекцию: параметр запроса под оператор В, отбор динамического списка, аргумент типового метода. Вместо трёх строк с Новый Массив и Добавить() в БСП есть готовая функция:

// Вместо:
// Массив = Новый Массив;
// Массив.Добавить(КонтрагентСсылка);

МассивКонтрагентов = ОбщегоНазначенияКлиентСервер.ЗначениеВМассиве(КонтрагентСсылка);

Запрос = Новый Запрос;
Запрос.Текст = "ВЫБРАТЬ Ссылка ИЗ Документ.РеализацияТоваровУслуг
    |ГДЕ Контрагент В (&Контрагенты)";
Запрос.УстановитьПараметр("Контрагенты", МассивКонтрагентов);

Функция ничего не проверяет: Неопределено, пустая ссылка, строка, ещё один массив — всё будет добавлено как единственный элемент. Если на вход придёт массив, вы получите массив из одного массива, а не «плоскую» копию. Для объединения коллекций нужна ДополнитьМассив() (см. ниже).

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

Где лежит функция: ОбщегоНазначенияКлиентСервер, а не ОбщегоНазначения

В БСП есть три близких по названию общих модуля, и путать их — источник ошибок компиляции и «неожиданно серверного» кода:

• ОбщегоНазначенияКлиентСервер — клиент-серверный модуль без повторного использования. Здесь живут все функции работы с массивами, включая ЗначениеВМассиве, СвернутьМассив, ДополнитьМассив, РазностьМассивов.
• ОбщегоНазначения — серверный модуль: работа с метаданными, ссылками, запросами к базе. Функций по массивам в нём нет.
• ОбщегоНазначенияКлиент — только клиентские сценарии (диалоги, работа с формами).

Практический вывод: ОбщегоНазначенияКлиентСервер.ЗначениеВМассиве() вызывается из любого контекста — из модуля формы на клиенте, из модуля объекта, из процедуры &НаСервереБезКонтекста. Дополнительная директива и передача на сервер не нужны: функция работает с памятью и к базе не обращается.

Отдельно проверьте, что вы не вызываете одноимённую функцию из прикладного модуля конфигурации. В типовых встречаются локальные копии ЗначениеВМассиве с другой сигнатурой — код скомпилируется, но поведение будет иным.

Параметры запросов и отборы: где это нужно каждый день

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

// Отбор динамического списка: значение или список значений
Если ТипЗнч(ЗначениеОтбора) = Тип("Массив") Тогда
    ЗначенияОтбора = ОбщегоНазначенияКлиентСервер.СвернутьМассив(ЗначениеОтбора);
Иначе
    ЗначенияОтбора = ОбщегоНазначенияКлиентСервер.ЗначениеВМассиве(ЗначениеОтбора);
КонецЕсли;

ОбщегоНазначенияКлиентСервер.УстановитьЭлементОтбораДинамическогоСписка(
    Список,
    "Организация",
    ЗначенияОтбора,
    ВидСравненияКомпоновкиДанных.ВСписке);

Второй частый сценарий — обмен данными и правила регистрации. Методы планов обмена и типовые процедуры регистрации ждут коллекцию узлов или ссылок; когда узел один, его оборачивают тем же ЗначениеВМассиве(), а результаты нескольких выборок складывают через ДополнитьМассив().

Третий — вызов типовых функций БСП: множество методов принимают Массив из ЛюбаяСсылка и возвращают соответствие «ссылка — данные». Оборачивать одну ссылку вручную незачем.

Свернуть массив в 1С: уникальные значения через БСП

СвернутьМассив() возвращает копию исходного массива, в которой остались только уникальные значения. Исходный массив не меняется:

Номенклатура = Новый Массив;
Номенклатура.Добавить(ТоварА);
Номенклатура.Добавить(ТоварБ);
Номенклатура.Добавить(ТоварА);

Уникальные = ОбщегоНазначенияКлиентСервер.СвернутьМассив(Номенклатура);
// Уникальные = [ТоварА, ТоварБ], Номенклатура не изменилась

Внутри функция вызывает ДополнитьМассив(Результат, Массив, Истина), а уникальность считается через Соответствие. Отсюда два практических следствия. Первое: порядок сохраняется — остаётся первое вхождение каждого значения. Второе: сравнение идёт как у ключей соответствия, то есть строго по значению и типу; число 1 и строка "1" останутся двумя разными элементами.

Свернуть массив перед подстановкой в параметр запроса полезно не только «для чистоты»: дубли в списке значений оператора В увеличивают объём передаваемых данных, а при последующем обходе результата дают лишние итерации.

ДополнитьМассив: слияние массивов с контролем дублей

Процедура добавляет в МассивПриемник все значения из МассивИсточник. Третий параметр включает режим уникальности — только тогда дубли отсекаются:

ВсеСсылки = Новый Массив;

ОбщегоНазначенияКлиентСервер.ДополнитьМассив(ВсеСсылки, СсылкиИзДокументов);
ОбщегоНазначенияКлиентСервер.ДополнитьМассив(ВсеСсылки, СсылкиИзРегистров, Истина);

// Без третьего параметра значения добавляются "как есть", вместе с повторами

Приёмник меняется по ссылке, поэтому процедура ничего не возвращает — присваивать результат нечему. В режиме уникальности функция сначала индексирует уже имеющиеся элементы приёмника, а затем добавляет из источника только те, которых нет: повторы внутри самого приёмника при этом не удаляются, для этого нужен СвернутьМассив().

Рядом лежит ДополнитьТаблицуИзМассива(Таблица, Массив, ИмяПоля) — заливает значения массива в указанную колонку таблицы значений построчно. Удобно, когда список ссылок нужно передать в запрос временной таблицей, а не параметром.

Удаление значений из массива: одно вхождение, все вхождения, по типу

В БСП три разные процедуры удаления, и различие между ними принципиально:

// Удалит только ПЕРВОЕ вхождение
ОбщегоНазначенияКлиентСервер.УдалитьЗначениеИзМассива(Массив, ТоварА);

// Удалит ВСЕ вхождения значения
ОбщегоНазначенияКлиентСервер.УдалитьВсеВхожденияЗначенияИзМассива(Массив, ТоварА);

// Удалит все элементы указанного типа
ОбщегоНазначенияКлиентСервер.УдалитьВсеВхожденияТипаИзМассива(Массив, Тип("Неопределено"));

УдалитьЗначениеИзМассива() ищет элемент через Массив.Найти() и удаляет его по индексу. Если значения нет, процедура молча ничего не делает — ошибки не будет. УдалитьВсеВхожденияЗначенияИзМассива() обходит массив от конца к началу, поэтому индексы не «съезжают» и удаляются действительно все совпадения.

УдалитьВсеВхожденияТипаИзМассива() сравнивает ТипЗнч(Элемент) = Тип — это точное совпадение типа, без учёта иерархии. Для составного набора ссылок разных справочников придётся вызвать процедуру на каждый тип отдельно.

РазностьМассивов: вычесть один массив из другого

Функция возвращает новый массив со всеми элементами первого массива, которых нет во втором. Типовой случай — вычислить, какие объекты добавились или выпали при сравнении «было / стало» в обмене данными:

// А = [1, 3, 5, 7]; В = [3, 7, 9]
Результат = ОбщегоНазначенияКлиентСервер.РазностьМассивов(А, В);
// Результат = [1, 5]

Добавленные = ОбщегоНазначенияКлиентСервер.РазностьМассивов(СтавшиеСсылки, БывшиеСсылки);
Удалённые   = ОбщегоНазначенияКлиентСервер.РазностьМассивов(БывшиеСсылки, СтавшиеСсылки);

Внутри — линейный поиск МассивВычитания.Найти(Элемент) для каждого элемента, то есть сложность порядка N * M. На сотнях элементов это незаметно, на десятках тысяч сравнение лучше делать соответствием или запросом на стороне СУБД. Дубли из первого массива в результат попадут все: если нужен чистый список, оберните результат в СвернутьМассив().

Массив в строку и ключи структуры: КлючиСтруктурыВСтроку

Отдельной функции «массив в строку» в БСП нет — для этого достаточно платформенного СтрСоединить(). А вот для структуры готовый метод есть: КлючиСтруктурыВСтроку() собирает имена ключей через разделитель.

// Массив в строку — платформенный метод
ТекстСписка = СтрСоединить(МассивКодов, ", ");

// Ключи структуры в строку — БСП
Параметры = Новый Структура("Организация, Склад, Период");
ИменаПолей = ОбщегоНазначенияКлиентСервер.КлючиСтруктурыВСтроку(Параметры);
// ИменаПолей = "Организация,Склад,Период"

// Обратная операция для строки: разложить в массив слов
Слова = СтроковыеФункцииКлиентСервер.РазложитьСтрокуВМассивСлов("один-@#два2_!три");

Разделитель по умолчанию — запятая без пробела, поэтому результат сразу годится для ЗаполнитьЗначенияСвойств(Приемник, Источник, ИменаПолей) и для конструктора Новый Структура(...). Если нужен человекочитаемый вид, передайте ", " вторым аргументом.

Для подстановки значений массива в шаблон сообщения используйте СтроковыеФункцииКлиентСервер.ПодставитьПараметрыВСтрокуИзМассива(ШаблонСтроки, Параметры): элементы массива подставляются на места %1, %2 и далее.

Частые ошибки при работе с массивами БСП

• Вызов через ОбщегоНазначения. ОбщегоНазначения.ЗначениеВМассиве() не существует: функции работы с массивами объявлены только в клиент-серверном модуле ОбщегоНазначенияКлиентСервер.
• Присваивание результата процедуры. ДополнитьМассив(), УдалитьЗначениеИзМассива() и обе процедуры удаления вхождений — это процедуры, они меняют массив на месте и ничего не возвращают. Массив = ДополнитьМассив(...) не скомпилируется.
• Ожидание уникальности от ДополнитьМассив() по умолчанию. Третий параметр ТолькоУникальныеЗначения равен Ложь, дубли добавятся.
• Путаница «одно вхождение / все вхождения». УдалитьЗначениеИзМассива() убирает только первое найденное значение. Если в массиве три одинаковых ссылки, останутся две.
• Передача массива в ЗначениеВМассиве(). Получится массив из одного элемента-массива, и параметр запроса с оператором В отработает вхолостую. Для объединения нужен ДополнитьМассив().
• Изменение массива, переданного в параметр запроса. После УстановитьПараметр() запрос хранит ссылку на ту же коллекцию: правки до Выполнить() изменят отбор, а после выполнения — уже нет.
• РазностьМассивов() на больших объёмах. Линейный поиск по второму массиву даёт квадратичную сложность; на десятках тысяч элементов переходите на Соответствие или сравнение запросом.
• Ожидание сравнения по представлению. Уникальность и поиск идут строго по значению и типу: 1 и "1" — разные элементы, ссылка и её строковое представление тоже.

Частые вопросы про массивы в БСП