Массивы с пользовательскими индексами

Поскольку многие могут принимать за само собой разумеющееся, что все массивы индексируются, начиная с единицы, при использовании массивов с нестандартным индексированием всегда есть шанс возникновения ошибок. Самое неприятное — это получение неверных результатов или аварийное завершение программы (сбой Julia). Например, рассмотрим следующую функцию.

В этом коде неявно предполагается, что векторы индексируются от единицы; если dest будет начинаться не с того же индекса, что и src, есть вероятность аварийного завершения. (Если такое происходит, то, чтобы выяснить причину, попробуйте запустить Julia с параметром --check-bounds=yes.)

Метод axes(A) (похожий на size(A)) возвращает кортеж объектов AbstractUnitRange{<:Integer}, определяющих допустимый диапазон индексов по каждому измерению массива A. Если A индексируется нестандартным образом, диапазоны могут начинаться не с единицы. Чтобы получить диапазон для определенного измерения d, используйте вызов axes(A, d).

В модуле Base реализован пользовательский тип диапазона OneTo: OneTo(n) означает то же самое, что и 1:n, но гарантирует (посредством системы типов), что нижний индекс равен 1. Для любого нового типа AbstractArray объект этого типа возвращается по умолчанию функцией axes. Это означает, что данный тип массива использует традиционное индексирование — начиная с единицы.

Обратите внимание, что для проверки границ существуют специальные функции checkbounds и checkindex, которые иногда могут упростить эту задачу.

Некоторые алгоритмы удобнее всего (или эффективнее) реализуются посредством линейных индексов A[i], даже если A — многомерный массив. Какими бы ни были собственные индексы массива, линейные индексы всегда имеют диапазон 1:length(A). Однако в случае с одномерными массивами (то есть AbstractVector) возникает неоднозначность: означает ли v[i] линейное индексирование или декартово индексирование с собственными индексами массива?

По этой причине оптимальным решением может быть перебор массива с помощью eachindex(A) или, если индексы должны быть последовательными целыми числами, получение диапазона индексов путем вызова LinearIndices(A). В результате будет возвращено axes(A, 1), если A — это AbstractVector, либо эквивалент 1:length(A) в противном случае.

Согласно этому определению одномерные массивы всегда используют декартово индексирование с собственными индексами массива. В подтверждение этого факта стоит отметить, что функции преобразования индексов выдают ошибку, если форма массива соответствует одномерному массиву с нестандартным индексированием (то есть Tuple{UnitRange}, а не кортеж OneTo). Для массивов со стандартным индексированием эти функции будут работать как обычно.

Вот один из способов переписать mycopy!, используя axes и LinearIndices.

Место для хранения часто выделяется с помощью Array{Int}(undef, dims) или similar(A, args...). Если результат должен соответствовать индексам какого-либо другого массива, этого не всегда может быть достаточно. Универсальной заменой таким шаблонам является использование similar(storagetype, shape). storagetype означает нужный тип базового, стандартного поведения, например Array{Int}, BitArray или даже dims->zeros(Float32, dims) (в этом случае в памяти размещается массив из одних нулей). shape — это кортеж значений Integer или AbstractUnitRange, определяющий индексы, которые должны использоваться в результате. Обратите внимание: для получения массива из одних нулей, соответствующего индексам A, удобно просто использовать zeros(A).

Разберем пару наглядных примеров. Во-первых, если у A стандартные индексы, то similar(Array{Int}, axes(A)) приведет к вызову Array{Int}(undef, size(A)) и вернет массив. Если A — это тип AbstractArray с нестандартным индексированием, то вызов similar(Array{Int}, axes(A)) должен вернуть что-то похожее по поведению на Array{Int}, но имеющее форму (включая индексы), соответствующую A. (Наиболее очевидной реализацией является размещение в памяти объекта Array{Int}(undef, size(A)) с последующей его инкапсуляцией в тип со сдвигом индексов.)

Также имейте в виду, что вызов similar(Array{Int}, (axes(A, 2),)) разместит в памяти объект AbstractVector{Int} (то есть одномерный массив), соответствующий индексам столбцов A.

Если вы создаете тип массива с индексированием не от единицы, вам потребуется специализировать функцию axes так, чтобы она возвращала объект UnitRange или (что, возможно, еще лучше) пользовательский объект AbstractUnitRange. Преимуществом пользовательского типа является то, что он сообщает о типе выделения памяти таким функциям, как similar. При написании типа массива с индексированием от нуля, скорее всего, будет лучше начать с создания нового типа AbstractUnitRange — ZeroRange, где ZeroRange(n) эквивалентно 0:n-1.

В общем случае не следует экспортировать ZeroRange из пакета: могут быть другие пакеты, в которых реализован собственный тип ZeroRange, а наличие нескольких отдельных типов ZeroRange, как это ни странно, является преимуществом. ModuleA.ZeroRange указывает на то, что функция similar должна создать ModuleA.ZeroArray, а ModuleB.ZeroRange соответствует типу ModuleB.ZeroArray. Такой подход обеспечивает мирное сосуществование множества разных пользовательских типов массивов.

Обратите внимание: чтобы не писать собственный тип ZeroRange, иногда можно использовать пакет Julia CustomUnitRanges.jl.

После создания собственного типа AbstractUnitRange необходимо специализировать функцию axes.

Здесь предполагается, что у ZeroArray есть поле с именем size (реализовать это можно и иными способами).

В некоторых случаях резервное определение axes(A, d).

может не отвечать вашим потребностям: вам может потребоваться специализировать его так, чтобы оно возвращало что-то, отличное от OneTo(1) при d > ndims(A). Аналогичным образом, в Base есть специальная функция axes1, которая эквивалентна axes(A, 1), но игнорирует проверку ndims(A) > 0 (во время выполнения). (Ее назначение заключается исключительно в повышении производительности.) Определяется она следующим образом.

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

Для собственного типа ZeroRange необходимо также добавить следующие две специализации similar.

Обе они должны реализовывать ваш пользовательский тип массива.

При необходимости определите следующий метод.

Это позволит изменить форму (reshape) массива так, чтобы у него были пользовательские индексы.

Значение метода has_offset_axes зависит от того, определен ли метод axes для объектов, для которых он вызывается. Если по какой-либо причине метод axes не определен для объекта, можно определить следующий метод.

Это позволит выявить проблему в коде, в котором предполагается индексирование от единицы, и выдать полезное сообщение об ошибке вместо возврата неверных результатов или аварийного завершения Julia.

Если новый тип массива вызывает ошибки где-то в другом коде, для отладки можно попробовать закомментировать @boundscheck в вашей реализации getindex и setindex!. Это позволит убедиться в том, что при обращении к каждому элементу происходит проверка границ. Либо же можно перезапустить Julia с параметром --check-bounds=yes.

В некоторых случаях может быть полезно временно отключить функции size и length для нового типа массива, так как они часто используются в коде с неверными допущениями.