Содержание

3.10:   Класс "IndexedTable" рус - "ИндексированнаяТаблица"

Аналог встроенного типа "ТаблицаЗначений", дополненный возможностью создавать и использовать индексы над таблицей. Индексы строятся в виде двоичных поисковых деревьев, таким образом получаем затраты на поиск O(log2(N)), тогда как в стандартном типе "ТаблицаЗначений" поиск осуществляется перебором строк, и следовательно затраты на поиск O(N).

Индекс может быть двух типов:
  1. по всем строкам таблицы;
  2. по строкам с уникальными значениями ключа. Строки с повторяющимися значениями ключа будут проигнорированы, и в операции перебора строк, суммирования, свёртки, выгрузки, загрузки не попадут.
Использование индексов даёт и другие преимущества, кроме ускорения поиска:
  • возможность поиска по нескольким значениям (по составному ключу);
  • наличие нескольких индексов для одной таблицы, независимые выборки для каждого индекса;
  • поиск по условиям "больше либо равно", "меньше либо равно";
  • построение индекса только по уникальным значениям даёт возможность получить список уникальных ключей без свёртывания таблицы;
  • свёртка по существующему индексу - при этом не теряется время на построение временного индекса;
  • динамическая фильтрация строк;
  • суммирование и свёртка по динамическому фильтру.

Таблица всегда имеет 1 индекс (в дальнейшем будем называть его "основной индекс"), который нельзя удалить. Номер этого индекса - 1, имя - "" (пустая строка). Если в операциях, использующих индекс, не указано имя индекса, то используется основной индекс. При операциях перепозиционирования (ВНачало(), СледующаяСтрока(), ПредыдущаяСтрока() и т.д.) основной индекс позиционируется на ту же строку.

3.10.1:   Свойства

НомерСтроки / RowNumber

Доступ: чтение / запись.

Тип: Число.

Описание: Номер текущей строки в основном индексе. Если строка не выбрана, то 0.

<ИмяКолонки>

Доступ: чтение / запись.

Описание: Обращение к значениям колонок, созданных методом НоваяКолонка().

3.10.2:   Методы

НоваяКолонка / NewColumn

Описание: Создаёт колонку в таблице.

Синтаксис: НоваяКолонка(стрИмяКолонки)

Параметры:
  • стрИмяКолонки - строка, идентификатор создаваемой колонки.

Возвращаемое значение: число, номер созданной колонки.

УдалитьКолонку / RemoveColumn

Описание: Удаляет указанную колонку.

Синтаксис: УдалитьКолонку(Колонка)

Параметры
  • Колонка - идентификатор или номер колонки.

КоличествоКолонок / ColumnCount

Описание: Возвращает количество колонок в таблице.

Синтаксис: КоличествоКолонок()

Возвращаемое значение: число, количество колонок в таблице.

ИмяКолонки / ColumnName

Описание: Возвращает имя указанной колонки.

Синтаксис: ИмяКолонки(Колонка)

Параметры
  • Колонка - идентификатор или номер колонки.

Возвращаемое значение: строка, идентификатор колонки.

НомерКолонки / ColumnNumber

Описание: Возвращает строковый идентификатор указанной колонки.

Синтаксис: НомерКолонки(Колонка)

Параметры
  • Колонка - идентификатор или номер колонки.

Возвращаемое значение: число, номер колонки.

НоваяСтрока / NewRow

Описание: Cоздаёт новую строку в конце таблицы.

Синтаксис: НоваяСтрока()

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

УдалитьСтроку / RemoveRow

Описание: Удаляет указанную строку.

Синтаксис: УдалитьСтроку(чСтрока)

Параметры
  • чСтрока - номер удаляемой строки

УдалитьСтроки / RemoveRows

Описание: Удаляет строки из таблицы. Если указан индекс, то при удалении учитывается наложенный фильтр.

Синтаксис: УдалитьСтроки([Индекс], [чНеВходящие])

Параметры
  • Индекс - идентификатор или номер индекса. Если параметр указан, и по данному индексу установлен фильтр, то удалятся строки, удовлетворяющие условиям фильтра.
  • чНеВходящие - число, 1 - будут удалены строки, не входящие в фильтр. Имеет смысл только с параметром Индекс.

КоличествоСтрок / RowCount

Описание: Возвращает количество строк в таблице.

Синтаксис: КоличествоСтрок([Индекс = ""])

Параметры
  • Индекс - идентификатор или номер индекса. Если параметр указан, и по данному индексу установлен фильтр, то считаются только строки, удовлетворяющие условиям фильтра.

Возвращаемое значение: число, количество строк в таблице.

НомерСтроки / RowNumber

Описание: Возвращает текущий номер строки в выборке для указанного индекса.

Синтаксис: НомерСтроки(Индекс)

Параметры
  • Индекс - идентификатор или номер индекса.

Возвращаемое значение: число, номер текущей строки в указанном индексе. Если строка не выбрана, то 0.

Очистить / Clenup

Описание: Полная очистка таблицы. Удаляются все индексы, строки и колонки.

Синтаксис: Очистить()

ДобавитьИндекс / AddIndex

Описание: Добавляет индекс к таблице.

Синтаксис: ДобавитьИндекс(стрИдентификатор, стрВыражение, [чТолькоУникальныеЗначения = 0])

Параметры
  • стрИдентификатор - строка, идентификатор создаваемого индекса;
  • стрВыражение - строка, индексное выражение. Индексное выражение состоит из списка идентификаторов колонок, разделённого запятыми. Если перед именем колонки стоит символ '-', то сортировка осуществляется в обратном порядке. Если перед именем колонки стоит символ '*', то сортировка осуществляется в по внутреннему представлению объекта. Если перед именем колонки стоит символ '#', то перед сравнением строк обрезаются пробелы слева и справа. Если перед именем колонки стоит символ '^', то строки сравниваются без учёта регистра. Модификаторы сортировки ('-', '*', "#", "^") можно использовать в любых сочетаниях. Индексное выражение может быть пустой строкой - это эквивалентно сортировке по номеру строки, или отсутствию сортировки (фильтр на такой индекс установить нельзя).
  • чТолькоУникальныеЗначения - число. Если 1, то в индекс попадут только строки, содержащие уникальные значения индекса. Строки с повторяющимися индексами будут проигнорированы, и в операции перебора строк, суммирования, свёртки, выгрузки, загрузки не попадут.

Возвращаемое значение: число, номер созданного индекса.

УдалитьИндекс / DropIndex

Описание: Удаление указанного индекса.

Синтаксис: УдалитьИндекс(Индекс)

Параметры
  • Индекс - идентификатор или номер индекса.

Сортировать / Sort

Описание: Изменение сортировки в основном индексе.

Синтаксис: Сортировать(стрВыражение)

Параметры
  • стрВыражение - строка, индексное выражение. Индексное выражение состоит из списка идентификаторов колонок, разделённого запятыми. Если перед именем колонки стоит символ '-', то сортировка осуществляется в обратном порядке. Если перед именем колонки стоит символ '*', то сортировка осуществляется в по внутреннему представлению объекта. Если индексное выражение - пустая строка, то сортировка выключается (фильтр на такой индекс установить нельзя).

ИндексУникален / IndexIsUnique

Описание: проверяет, уникален ли индекс.

Синтаксис: ИндексУникален([Индекс = ""])

Параметры
  • Индекс - идентификатор или номер индекса.

Возвращаемое значение: число, 1 - в таблице нет строк, с повторяющимися значениями ключа; 0 - таблица содержит строки с одинаковыми значениями ключа.

КоличествоУникальныхКлючей / UniqueKeyCount

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

Синтаксис: КоличествоУникальныхКлючей([Индекс = ""])

Параметры
  • Индекс - идентификатор или номер индекса.

Возвращаемое значение: число, количество уникальных ключей.

КоличествоЗначенийКлюча / KeyValueCount

Описание: возвращает количество строк, для которых значение ключа равно параметру Ключ.

Синтаксис: КоличествоЗначенийКлюча([Индекс = ""], Ключ)

Параметры
  • Индекс - идентификатор или номер индекса.
  • Ключ - если индекс построен по одной колонке - то значение поиска. Если же индекс по нескольким колонкам, то это должен быть СписокЗначений, содержащий значения ключевых колонок, заданных в методе ДобавитьИндекс().

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

НайтиСтроку / FindRow

Описание: Найти строку, точно соответствующую ключу.

Синтаксис: НайтиСтроку(Индекс, Ключ, [чНайтиПоследнюю = 0], [чСпозиционироваться = 0])

Параметры
  • Индекс - идентификатор или номер индекса.
  • Ключ - если индекс построен по одной колонке - то значение поиска. Если же индекс по нескольким колонкам, то это должен быть СписокЗначений, содержащий значения ключевых колонок, заданных в методе ДобавитьИндекс().
  • чНайтиПоследнюю - число, если 1, то будет найдена последняя строк с совпадающим значением ключа.
  • чСпозиционироваться - число, если 1, то индекс будет спозиционирован на найденной строке. Основной индекс также перепозиционируется.

Возвращаемое значение: число, номер найденной строки. Если ничего не найдено, то 0.

НайтиБлижайшуюБольше / FindNearestGE

Описание: Найти строку, которая равна или больше ключа.

Синтаксис: НайтиБлижайшуюБольше(Ключ, [Индекс = ""])

Параметры
  • Ключ - если индекс построен по одной колонке - то значение поиска. Если же индекс по нескольким колонкам, то это должен быть СписокЗначений, содержащий значения ключевых колонок, заданных в методе ДобавитьИндекс().
  • Индекс - идентификатор или номер индекса. По умолчанию используется основной индекс.

Возвращаемое значение: число, номер найденной строки. Если ничего не найдено, то 0.

НайтиБлижайшуюМеньше / FindNearestLE

Описание: Найти строку, которая равна или меньше ключа.

Синтаксис: НайтиБлижайшуюМеньше(Ключ, [Индекс = ""])

Параметры
  • Ключ - если индекс построен по одной колонке - то значение поиска. Если же индекс по нескольким колонкам, то это должен быть СписокЗначений, содержащий значения ключевых колонок, заданных в методе ДобавитьИндекс().
  • Индекс - идентификатор или номер индекса. По умолчанию используется основной индекс.

Возвращаемое значение: число, номер найденной строки. Если ничего не найдено, то 0.

УстановитьФильтр / SetFilter

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

Синтаксис: УстановитьФильтр(КлючМин, КлючМакс, [Индекс = ""])

Параметры
  • КлючМин - нижняя граница фильтра;
  • КлючМакс - верхняя границы фильтра;
  • Индекс - идентификатор или номер индекса. По умолчанию используется основной индекс.

Если индекс построен по одной колонке, то в качестве ключей можно использовать значение колонки. Если же индекс по нескольким колонкам, то ключ должен быть СписокЗначений, содержащий значения ключевых колонок, заданных в методе ДобавитьИндекс().

Подмножество / Subset

Описание: устанавливает фильтр, фиксируя значения первых колонок индекса.

Пример:

ТЗ.УстановитьФильтр("и1", "к1, к2");
сзКлюч = СоздатьОбъект("СписокЗначений");
сзКлюч.ДобавитьЗначение(5);
ТЗ.Подмножество(сзКлюч, 1, "и1");

в результате в выборке будут только те строки, у которых колонка к1 = 5.

Синтаксис: Подмножество(сзКлюч, чКоличествоФиксКолонок, [Индекс = ""])

Параметры
  • сзКлюч - список значений, содержащий значения фиксируемых колонок индекса.
  • чКоличествоФиксКолонок - число, количество фиксируемых колонок индекса
  • Индекс - идентификатор или номер индекса. По умолчанию используется основной индекс.

ВыключитьФильтр / DropFilter

Описание: выключает фильтр у указанного индекса.

Синтаксис: ВыключитьФильтр(Индекс)

Параметры
  • Индекс - идентификатор или номер индекса.

ВНачало / FirstRow

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

Синтаксис: ВНачало([Индекс = ""])

Параметры
  • Индекс - идентификатор или номер индекса. По умолчанию используется основной индекс.

Возвращаемое значение число, 1 - операция завершилась успешно, 0 - выборка пуста.

ВыбратьСтроки / SelectRows

Описание: позиционируется перед первой строкой указанного индекса, так что метод ПолучитьСтроку() спозиционируется на первой строке.

Синтаксис: ВыбратьСтроки([Индекс = ""])

Параметры
  • Индекс - идентификатор или номер индекса. По умолчанию используется основной индекс.

Возвращаемое значение число, 1 - операция завершилась успешно, 0 - выборка пуста.

ВКонец / LastRow

Описание: позиционируется после последней строки указанного индекса, так что метод ПредыдущаяСтрока() спозиционируется на последней строке.

Синтаксис: ВКонец([Индекс = ""])

Параметры
  • Индекс - идентификатор или номер индекса. По умолчанию используется основной индекс.

Возвращаемое значение число, 1 - операция завершилась успешно, 0 - выборка пуста.

ПолучитьСтроку / GetRow

Описание: переход к следующей строке индекса.

Синтаксис: ПолучитьСтроку([Индекс = ""], [чТолькоУникальные = 0])

Параметры
  • Индекс - идентификатор или номер индекса. По умолчанию используется основной индекс.
  • чТолькоУникальные - если 1, то будет получена следующая строка с отличающимся значением ключа, все повторяющиеся строки будут пропущены.

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

ПолучитьЗначение / GetValue

Описание: возвращает значение в указанной ячейке таблицы.

Синтаксис: ПолучитьЗначение(чСтрока, Колонка)

Параметры
  • чСтрока - число, номер строки;
  • Колонка - число или строка, номер или идентификатор колонки.

Возвращаемое значение значение ячейки таблицы.

Получить / Get

Описание: синоним метода ПолучитьЗначение().

Синтаксис: Получить(чСтрока, Колонка)

УстановитьЗначение / SetValue

Описание: устанавливает значение указанной ячейки.

Синтаксис: УстановитьЗначение(чСтрока, Колонка, Значение)

Параметры
  • чСтрока - число, номер строки;
  • Колонка - число или строка, номер или идентификатор колонки;
  • Значение - новое значение ячейки.

Установить / Set

Описание: синоним метода УстановитьЗначение().

Синтаксис: Установить(чСтрока, Колонка, Значение)

Свернуть / GroupBy

Описание: сворачивает таблицу по колонкам <КолонкиСвёртки>, суммируя значения в колонках <КолонкиСумм>. Колонки, не вошедшие в <КолонкиСвёртки> и <КолонкиСумм> из таблицы не удаляются. Свёртка возможна и по существующему индексу - при этом не теряется время на построение временного индекса, и возможна выборочная свёртка по текущему фильтру индекса.

Синтаксис: Свернуть(стрКолонкиСвёртки, стрКолонкиСумм [, ИмяСуществующегоИндекса])

Параметры
  • стрКолонкиСвёртки - строка, список колонок, по которым будет осуществляться свёртка. Эта строка полностью аналогична индексному выражению в методе ДобавитьИндекс(). Для свёртки таблица сначала индексируется по этому выражению, а затем строки с одинаковым индексом суммируются. Результат всегда помещается в первую по номеру строку, все остальные строки удаляются.
  • стрКолонкиСумм - строка, список колонок, которые нужно просуммировать. Разделитель - символ ','. Пробелы игнорируются.
  • ИмяСуществующегоИндекса - число или строка. Если указано имя индекса, то КолонкиСвёртки игнорируются, а свёртка осуществляется по указанному индексу. В свёртке учавствуют только те строки, которые входят в фильтр.

Итог / Sum

Описание: считает сумму по указанной колонке, при этом учитывается фильтр индекса.

Синтаксис: Итог(КолонкаСуммы [, Индекс])

Параметры
  • КолонкаСуммы - строка или число, колонка, по которой нужно получить сумму.
  • Индекс - идентификатор или номер индекса. По умолчанию используется основной индекс.

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

ИтогПоУзлу / NodeSum

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

Синтаксис: ИтогПоУзлу(КолонкаСуммы [, Индекс])

Параметры
  • КолонкаСуммы - строка или число, колонка, по которой нужно получить сумму.
  • Индекс - идентификатор или номер индекса. По умолчанию используется основной индекс.

Возвращаемое значение число, сумма по указанной колонке. Если выборка не активна (нет текущего узла), то возвращает 0.

Группировать / Group

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

Пример: на входе имеем таблицу

Фамилия Имя Сумма
Иванов Иван 100
Иванов Сергей 120
Петров Пётр 130
Петров Александр 200

группируем её:

ТЗ.Группировать("Фамилия: Фамилия; Имя: Имя", "Сумма");

и получаем таблицу такого вида (в колонке тзПотомки показано содержимое таблицы тзПотомки):

Фамилия Имя Сумма тзПотомки
Фамилия Имя Сумма
Иванов Иван 220 Иванов Иван 100
Иванов Сергей 120
Петров Пётр 330 Петров Пётр 130
Петров Александр 200

Синтаксис: Группировать(стрГруппировки, стрКолонкиСумм, [чРасшифровкаПоследнегоУровня = 0])

Параметры
  • стрГруппировки - строка, описывающая группировки. Задаётся в виде <ИмяИндекса1>: <ИндексноеВыражение1> [; <ИмяИндекса2>: <ИндексноеВыражение2> ... ]
  • стрКолонкиСумм - строка с колонками, по которым нужно считать суммы.
  • чРасшифровкаПоследнегоУровня - число, если 1, то в каждой строке последнего уровня группировки будет таблица с расшифровкой, содержащая строки исходной таблицы в нетронутом виде.

ЗаполнитьСтроку / FillRow

Описание: заполняет текущую строку таблицы из строки другой таблицы, или из списка значений.

Синтаксис: ЗаполнитьСтроку(Источник, [чНомерСтрокиИсточника = 0], [чПоИменамКолонок = 0])

Параметры
  • Источник - ИндексированнаяТаблица, ТаблицаЗначений, или Список значений. Источник данных для заполнения строки.
  • чНомерСтрокиИсточника - число, номер строки в таблице-источнике. По умолчанию берётся текущая строка в предопределённом индексе. Если Источник - СписокЗначений, то этот параметр игнорируется.
  • чПоИменамКолонок - число, 0 - значения из источника копируются по номерам колонок; 1 - значения копируются по именам колонок. Если в приёмнике нет колонки с таким именем, то значение не копируется. Если Источник - СписокЗначений, то именами колонок считаются символьные представления значений.

Выгрузить / Unload

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

Синтаксис: Выгрузить(ТЗ [, Индекс])

Параметры
  • ТЗ - значение типа ИндексированнаяТаблица, ТаблицаЗначений или Неопределенный, переменная, в которую будет выгружена таблица. Если тип Неопределенный, то создаётся таблица типа ИндексированнаяТаблица.
  • Индекс - идентификатор или номер индекса. По умолчанию используется основной индекс.

Загрузить / Load

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

Синтаксис: Загрузить(ТЗ [, Индекс])

Параметры
  • ТЗ - значение типа ИндексированнаяТаблица или ТаблицаЗначений, таблица, из которой будут загружены данные.
  • Индекс - идентификатор или номер индекса в таблице - источнике. По умолчанию используется основной индекс. Если ТЗ имеет тип ТаблицаЗначений, то этот параметр игнорируется.

Объединить / Merge

Описание: добавляет строки из таблицы - источника в текущую таблицу. Если в таблице - источнике есть колонки, которых нет в текущей, то они создаются. Объединени осуществляется с учётом индекса и фильтра таблицы - источника.

Синтаксис: Объединить(ТЗ [, Индекс])

Параметры
  • ТЗ - значение типа ИндексированнаяТаблица или ТаблицаЗначений, таблица, из которой будут загружены данные.
  • Индекс - идентификатор или номер индекса в таблице - источнике. По умолчанию используется основной индекс. Если ТЗ имеет тип ТаблицаЗначений, то этот параметр игнорируется.

Пересечение / Conjunction

Описание: пересечение двух таблиц по ключевым полям. Результатом пересечения является таблица, в которой присутствуют строки текущей ТЗ, которые есть в ТЗ2, и строки ТЗ2, которые есть в текущей ТЗ. Совпадение строк определяется по индексам ИндексТекущейТЗ и ИндексТЗ2. Количество колонок в индексах должно быть одинаковым.

Синтаксис: Пересечение(ТЗ2, ИндексТекущейТЗ, ИндексТЗ2)

Параметры
  • ТЗ2 - таблица, с которой строится пересечение.
  • ИндексТекущейТЗ - номер или имя индекса в текущей таблицы.
  • ИндексВторойТЗ - номер или индекс в ТЗ2.

Копия / Copy

Описание: создаёт копию таблицы.

Синтаксис: Копия([чКопироватьИндексы = 0])

Параметры
  • чКопироватьИндексы - если 1, то индексы и фильтры тоже будут скопированы.

Возвращаемое значение: переменная типа ИндексированнаяТаблица, являющаяся копией объекта.

ВФайл / SaveToFile

Описание: записывает таблицу в файл.

Синтаксис: ВФайл(стрИмяФайла, [чФормат = 1], [Индекс = ""], [чСИменамиКолонок = 1])

Параметры
  • стрИмяФайла - строка, имя файла, в который нужно записать таблицу. Если файл уже существует, то он перезаписывается.
  • чФормат - число, формат файла. Может принимать следующие значения: 1 - запись значений во внутреннем формате; 2 - запись значений во внешнем формате; 3 - csv файл со значениями во внутреннем формате; 4 - csv файл со значениями во внешнем формате.
  • Индекс - идентификатор или номер индекса. По умолчанию используется основной индекс. Выгрузка в файл производится с учётом сортировки и фильтра (если есть) по указанному индексу.
  • чСИменамиКолонок - число, 1 - в первую строку файла будут записаны имена колонок. Имеет смысл только для csv-файлов.

ИзФайла / LoadFromFile

Описание: записывает таблицу в файл.

Синтаксис: ИзФайла(стрИмяФайла, [чФормат = 1], [чСИменамиКолонок = 1])

Параметры
  • стрИмяФайла - строка, имя файла, из которого нужно считать таблицу.
  • чФормат - число, формат файла. Может принимать следующие значения: 1 - запись значений во внутреннем формате; 2 - запись значений во внешнем формате; 3 - csv файл со значениями во внутреннем формате; 4 - csv файл со значениями во внешнем формате.
  • чСИменамиКолонок - число, 1 - в первой строке файла хранятся имена колонок. Имеет смысл только для csv-файлов. Если параметр = 0, то имена колонок образуются как __col__<НомерКолонки>.

Возвращаемое значение: число, 1 - таблица считана успешно; 0 - ошибка при чтении.