Interfaces

Two mandatory methods are always required.

There are several other methods that should be determined in specific circumstances. Note that you should always define at least one of the Base' methods.IteratorSize(IterType) and length(iter), since the default is Base.IteratorSize(IterType) is defined as Base.HasLength().

Sequential iteration is implemented using the function iterate. Instead of changing objects as they iterate, Julia iterators can track the iteration state outside of the object. The return value of an iteration is always either a tuple of the value and state, or nothing if there are no elements left. The state object will be passed back to the iteration function at the next iteration and is usually considered an implementation detail private to the iterated object.

Any object that this function defines is iterable and can be used in many functions where iteration is applied. It can also be used directly in a loop. for, because the syntax

converted to

A simple example is an iterable sequence of squares of numbers of a certain length:

Having only a definition iterate, the Squares type is already quite powerful. You can iterate over all the elements.:

You can use many built-in methods that work with iterable collections, for example in or sum:

There are several other methods that can be extended to provide Julia with more information about this iterable collection. We know that the elements in the Squares' sequence will always be of type `Int'. Extending the method 'eltype, this information can be passed to Julia to create more specialized code in more complex methods. We also know the number of elements in the sequence, so we can also extend the function length:

Now that Julia requires collecting all the elements in an array using the method collect, Julia can pre-select Vector{Int} the right size instead of sending each item to push! using the Vector' function{Any}:

While it is possible to rely on general implementations, it is also possible to extend specific methods if it is known that a simpler algorithm is available in them. For example, there is a formula for calculating the sum of squares, so the universal iterative version can be redefined with a more efficient solution.:

There is a common pattern in Julia Base: a small set of necessary methods defines an informal interface that implements many non-standard behaviors. In some cases, types will need to further specialize these behaviors when they know that a more efficient algorithm can be used in their particular case.

In addition, it is often useful to allow the collection to iterate in_ reverse order by iterating using the function Iterators.reverse(iterator). However, to actually support iteration in reverse, the iterator type T must implement iterate for Iterators.Reverse{T}. (Considering r::Iterators.Reverse{T}, the base iterator of type T is r.itr'.) In the following `Squares example, the Iterators.Reverse' methods are implemented.{Squares}:

For the iterated Squares object shown above, you can easily calculate the i’th element of the sequence by squaring it. The process can be represented as an indexing expression `S[i]. To accept this behavior, Squares just needs to define a function getindex:

In addition, to support the syntax of S[begin] and S[end], it is necessary to define firstindex and lastindex to specify the first and last valid indexes, respectively:

For multidimensional indexing of begin/end', as, for example, in `a[3, begin, 7], it is necessary to define firstindex(a, dim) and lastindex(a, dim) (which by default call first and last for `axes(a, dim)', respectively).

Note, however, that the above example defines only a function getindex with a single integer index. Indexing with anything other than Int will result in an error. MethodError, informing about the absence of a suitable method. To support indexing with ranges or Int vectors, you need to write separate methods.:

Although it will support more operations. indexing supported by some built-in types is still missing a number of features. This sequence of Squares' starts to look more and more like a vector as behaviors are added to it. Instead of defining all these behaviors yourself, it can be officially defined as a subtype. `AbstractArray.

If a type is defined as a subtype of AbstractArray, it inherits a very large set of diverse features, including iteration and multidimensional indexing based on singleton access. For more information about supported methods, see the manual page dedicated to arrays, and in this section is Julia Base.

The key element in defining the subtype of AbstractArray' is the type `IndexStyle. Since indexing is an important part of the array and is often found in hot loops, it is important to perform both indexing and indexed assignment as efficiently as possible. Array data structures are usually defined in one of two ways: either they access their elements as efficiently as possible using only one index (linear indexing), or they internally access elements with indexes set for each dimension. These two options in Julia are called IndexLinear() and `IndexCartesian()'. Converting a linear index to multiple subscripts is usually a very expensive operation, so there is a feature-based mechanism that allows you to create efficient universal code for all types of arrays.

This difference determines which scalar indexing methods should determine the type. The arrays IndexLinear() are simple: it is enough to define getindex(A::ArrayType, i::Int). When the array is subsequently indexed using a multidimensional set of indexes, the backup getindex(A::AbstractArray, I...) converts the indexes into a single linear index and then calls the above method. IndexCartesian() arrays, on the other hand, require defining methods for each supported dimension with ndims(A) Int indexes. For example, the type SparseMatrixCSC' from the standard library module `SparseArrays' supports only two dimensions, so it simply defines `getindex(A::SparseMatrixCSC, i::Int, j::Int). The same applies to setindex!.

If we take the sequence of squares shown above, it can be defined as a subtype of AbstractArray'.{Int, 1}:

Please note: it is very important to specify two AbstractArray parameters. The first defines the function 'eltype`, and the second one is a function ndims. This supertype and these three methods are all that is needed for the SquaresVector to become an iterable, indexed, and fully functional array.:

Let’s take a more complex example and define our own model N-dimensional sparse array type based on Dict:

Note that this is an array of IndexCartesian', so you need to manually define `getindex and setindex! in the dimension of the array. Unlike the SquaresVector', it is possible to define `setindex! and therefore it is possible to modify the array:

The result of indexing AbstractArray can itself be an array (for example, when indexing by AbstractRange'). The backup methods of `AbstractArray' use the function 'similar to select an Array of the appropriate size and type of elements, which is filled using the basic indexing method described above. However, when implementing an array wrapper, it is often required that the result is also enclosed in the wrapper.:

In the example above, this is achieved by defining Base.similar(A::SparseArray, ::Type{T}, dims::Dims) where T to create the corresponding enclosed array. (Note that although 'similar` supports one- and two-argument forms, in most cases only the three-argument form needs to be specialized.) For this, it is important that SparseArray is mutable (supports setindex!). By defining similar, getindex and setindex! for SparseArray, you can copy the array using the function copy:

In addition to all the iterated and indexed methods above, these types can also interact with each other and use most of the methods defined in Julia Base for AbstractArrays:

If you are defining an array type that allows non-traditional indexing (indexes starting with a value other than 1), you need to specialize axes. You should also specialize similar so that the dims argument (usually a tuple of Dims sizes) can accept AbstractUnitRange objects, possibly the Ind range types of your own design. For more information, see the chapter Arrays with custom indexes.

An array with a specified step is a subtype of the AbstractArray array, whose records are stored in memory with fixed steps. Provided that the array element type is compatible with BLAS, an array with a given step can use BLAS and LAPACK routines for more efficient linear algebra procedures. A standard example of a user-defined array with a specified step is an array that encloses a standard array Array in an additional structure.

Warning. Do not implement these methods if the underlying storage does not have the specified steps, as this may lead to incorrect results or segmentation errors.

Below are examples of array types with and without specified steps.

Broadcast is activated explicitly by calling broadcast or broadcast! or implicitly by using point operations such as A .+ b or f.(x, y). Any object that has axes and indexing-enabled, can participate as an argument in the translation. By default, the result is stored in an Array. There are three main ways for this basic platform to be extensible:

axes and indexing are not supported by all types, but many can be enabled in translation. Function Base.broadcastable is called for each broadcast argument, which allows you to return something else that supports axes and indexing. By default, this is the identity function for all AbstractArray and Number — they already support axes and indexing.

If the type is supposed to act as a "0-dimensional scalar" (a separate object), and not a container for translation, then the following method must be defined:

which returns an argument enclosed in a 0-dimensional container Ref. For example, such a wrapper method is defined for the types themselves, functions, and special single objects such as missing and nothing, and dates.

Custom array-like types can specialize Base.broadcastable to define their form, but they must follow the convention that collect(Base.broadcastable(x)) == collect(x). A significant exception is `AbstractString'. Strings have a special case to act as scalars for translation purposes, although they are iterable collections of their characters (for more information, see Lines).

The next two steps (selection of the output array and implementation) depend on defining a single solution for a given set of arguments. A broadcast should take all the different types of its arguments and reduce them to a single output array and a single implementation. In broadcasting, this single solution is called "style". Each broadcast object has its own preferred style, and to combine these styles into a single solution - the "destination style" - a system similar to promotion is used.

Sometimes it is desirable to change the way the end user interacts with the object fields. Instead of providing direct access to type fields, you can introduce an additional level of abstraction between the user and the code by overloading object.field. Properties are how the user sees the object, and fields are what the object actually represents.

By default, the properties and fields match. However, this behavior can be changed. For example, take the representation of a point on a plane in https://en.wikipedia.org/wiki/Polar_coordinate_system [polar coordinates]:

As described in the table above, access via the dot notation p.r is equivalent to calling getproperty(p, :r), which by default is equivalent to getfield(p, :r):

However, we may need users not to know that the coordinates in Point are stored as r and ϕ (fields), but instead interact with x and y (properties). You can define the methods in the first column by adding new functionality.:

It is important to use the getfield and setfield calls inside getproperty and setproperty! instead of the dot syntax, since dot syntax will make functions recursive, which can lead to problems with type inference. Now you can experience the new functionality.:

In conclusion, it is worth noting that in Julia, instance properties are rarely added in this way. As a rule, there must be a good reason for this.

To support rounding in a new type, it is usually sufficient to define one method round(x::ObjType, r::RoundingMode). The transmitted rounding mode determines in which direction the value should be rounded. The most commonly used rounding modes are RoundNearest, RoundToZero, RoundDown and RoundUp, as they are used in definitions of a single argument, round, method, and trunk, floor and `ceil', respectively.

In some cases, it is possible to define a three-argument round method that is more accurate or productive than a two-argument method followed by a transformation. In this case, you can define a three-argument method in addition to a two-argument one. If it is impossible to represent the rounded result as a type T object, the method with three arguments should raise the error `InexactError'.

For example, if there is an Interval type that represents a range of possible values, like https://github.com/JuliaPhysics/Measurements.jl , you can define rounding for this type as follows