BaseInterfaces reference

BaseInterfaces

BaseInterfaces.jl is a subpackage of Interfaces.jl that provides predifined definition and testing for Base Julia interfaces.

Currently this includes:

• A general iteration interface: IterationInterface
• AbstractArray interface: ArrayInterface
• AbstractSet interface: SetInterface
• AbstractDict interface: DictInterface
• AbstractString interface: StringInterface

None of these should be considered complete or authoritative, due both to the size of the task and that many of the interfaces not documented in Base Julia. However, they may be helpful in testing your objects basically conform. Please make issues and PRs with missing behaviours if you find them.

Declaring that it follows the interface is done with:

@implements DictInterface{(:component1, :component2)} MyDict [MyDict(some_values...), MyDict(other_values...)]

Optional components can be chosen from Interfaces.optional_keys(DictInterface).

After this you can easily test it with:

Interfaces.test(DictInterface, MyDict)

See the docs for use.

If you want to add more Base julia interfaces here, or think the existing ones could be improved, please make an issue or pull request.

    ArrayInterface

An Interfaces.jl Interface with mandatory components (:eltype, :ndims, :size, :getindex, :indexstyle) and optional components (:logical, :setindex!, :similar_type, :similar_eltype, :similar_size, :similar_eltype_size).

Base Julia AbstractArray interface

Extended help

Mandatory keys:

• eltype
• ndims
• size:
  • size(A) returns a tuple of Integer
  • length of size(A) matches ndims(A)
• getindex:
  • Can index with begin/firstindex
  • Can index with end/lastindex
  • Can index with all indices in eachindex(A)
  • Can index with Int for multiple dimensions
  • Can index with Int for multiple dimensions and trailing ones
  • Can index with Int for multiple dimensions and trailing colons
  • Can index with CartesianIndex
  • Can index with CartesianIndex and trailing ones
  • Can index with CartesianIndices
  • Can index with CartesianIndices and trailing ones
  • Can index with CartesianIndices and trailing colons
  • Can index with UnitRange
  • Can index with UnitRange and trailing ones
  • Can index with UnitRange and trailing colons
  • Can index with StepRange
  • Can index with StepRange and trailing ones
  • Can index with StepRange and trailing colons
  • Can index with a Vector of Int
  • Can index with a Vector of Int32
  • Can index with a Vector of Int with trailing ones
  • Can index with a Vector of Int with trailing colons
• indexstyle: IndexStyle returns IndexCartesian or IndexLinear

Optional keys:

• logical:
  • Can index with logical indices
  • Can index with logical indices and trailing ones
  • Can index with logical indices and trailing colons
  • Can index with multidimensional logical indices
  • Can index with multidimensional logical indices and trailing ones
  • Can index with multidimensional logical indices and trailing colons
• setindex!
• similar_type: similar(A) returns an object the same type and size as A
• similar_eltype: similar(A, T::Type) returns an object the same base type as A with eltype of T
• similar_size: similar(A, s::NTuple{Int}) returns an object the same type as A with size s
• similar_eltype_size: similar(A, T::Type, s::NTuple{Int}) returns an object the same type as A with eltype T and size s

    DictInterface

An Interfaces.jl Interface with mandatory components (:iterate, :length, :eltype, :keytype, :valtype, :keys, :values, :getindex) and optional components (:setindex!, :get!, :delete!, :empty!).

AbstractDict interface

Requires test data wrapped with Interfaces.Arguments, with

• d = the_dict mandatory

When get! or setindex! is needed

• k: any valid key not initially in d
• v: any valid value

Extended help

Mandatory keys:

• iterate: AbstractDict follows the IterationInterface
• length: length is defined
• eltype:
  • eltype is a Pair
  • the first value isa eltype
• keytype: keytype is the same as the first type in eltype parameters
• valtype: valtype is the same as the second type in eltype paremeters
• keys: keys are all of type keytype
• values: values are all of type valtype
• getindex:
  • getindex of the first key is the first object in values
  • getindex of all keys match values

Optional keys:

• setindex!:
  • test object d does not yet have test key k
  • can set key k to value v
• get!:
  • test object d does not yet have test key k
  • can set and get key k to value v with using get!
• delete!: can delete existing keys from the object
• empty!: can empty the dictionary

    IterationInterface

An Interfaces.jl Interface with mandatory components (:isempty, :iterate, :isiterable, :eltype, :size, :in) and optional components (:reverse, :indexing).

An interface for Base Julia iteration.

Test objects must not be empty, so that isempty(obj) == false.

Extended help

Mandatory keys:

• isempty: test iterator is not empty
• iterate:
  • iterate does not return nothing
  • iterate returns a Tuple
  • second iterate returns a Tuple or Nothing
• isiterable
• eltype
• size
• in: in returns true for all values in x

Optional keys:

• reverse
• indexing:
  • can call firstindex
  • can call lastindex
  • can call getindex
  • getindex matches iteration order

    SetInterface

An Interfaces.jl Interface with mandatory components (:isempty, :eltype, :length, :iteration) and optional components (:copy, :empty, :hasfastin, :setdiff, :intersect, :union, :copymutable, :emptymutable, :empty!, :delete!, :push!, :sizehint!).

The AbstractSet interface

Extended help

Mandatory keys:

• isempty: defines isempty and testdata is not empty
• eltype: elements eltype of set s are subtypes of eltype(s)
• length: set defines length and test object has length larger than zero
• iteration: follows the IterationInterface

Optional keys:

• copy: creates an identical object with the same values, that is not the same object
• empty:
  • returns an empty set able to hold elements of type U
  • returns an empty set able to hold elements of arbitrary types
• hasfastin: hasfastin returns a Bool
• setdiff:
  • setdiff with itself is an empty set of the same type
  • setdiff with an empty set is equal to itself
• intersect:
  • intersect of set with itself is itself
  • intersect of set with an empty set is an empty set
• union:
  • union of a set with itself equals itself
  • union of a set an empty set equals itself
• copymutable: creates an identical mutable object with the same values, that is not the same object
• emptymutable:
  • returns an empty set able to hold elements of type U
  • returns an empty set able to hold elements of arbitrary types
• empty!: empty! removes all elements from the set
• delete!: delete! removes element valued x of the set
• push!: push! adds an element to the set
• sizehint!: can set a size hint

    StringInterface

An Interfaces.jl Interface with mandatory components (:ncodeunits, :iterate, :codeunit, :isvalid, :eltype) and optional components (:length,).

AbstractString interface

Test objects must not be empty, so that isempty(obj) == false.

Extended help

Mandatory keys:

• ncodeunits: ncodeunit returns an Int
• iterate: AbstractString follows the IterationInterface
• codeunit: the first codeunit is a UInt8/16/32
• isvalid: isvalid returns a Bool
• eltype: eltype returns a type <: AbatractChar

Optional keys:

• length: length return an Int