adjust interface

Author: Alessandro Cheli

src/TermInterface.jl

@@ -69,20 +69,30 @@ export operation
 
 Returns the arguments to the function call in a function call expression.
 `iscall(x)` must be true as a precondition.
+
+Depending on the type and internal representation of `x`,
+`arguments(x)` may return an unsorted collection nondeterministically,
+This is to make sure to retrieve the arguments of an expression when the order of arguments does not matter 
+but the speed of the operation does.
+To ensure to retrieve arguments in a sorted manner, you can use 
+and implement the function `sorted_arguments`.
 """
 function arguments end
 export arguments
 
 """
-    unsorted_arguments(x::T)
+    sorted_arguments(x::T)
 
-If x is a expression satisfying `iscall(x)` and your expression type `T` provides
-and optimized implementation for storing the arguments, this function can 
-be used to retrieve the arguments when the order of arguments does not matter 
-but the speed of the operation does.
+Returns the arguments to the function call in a function call expression, in a **sorted fashion**.
+`iscall(x)` must be true as a precondition. Analogous to `arguments`, 
+but ensures that the operation is deterministic and always returns 
+the arguments in the order they are stored.
+
+By default, this redirects to `arguments`, therefore implementing 
+it is optional.
 """
-unsorted_arguments(x) = arguments(x)
-export unsorted_arguments
+sorted_arguments(x) = arguments(x)
+export sorted_arguments
 
 
 """

test/runtests.jl

@@ -20,3 +20,27 @@ using Test
     @test !iscall(ex)
     @test ex == maketerm(Expr, :ref, [:arr, :i, :j], nothing)
 end
+
+@testset "Unsorted arguments" begin
+    struct Sum
+        d::Dict{Int, Any}
+        Sum(xs...) = new(Dict{Int, Any}(xs...))
+    end
+
+    TermInterface.isexpr(s::Sum) = true 
+    TermInterface.head(::Sum) = (+)
+    TermInterface.operation(s::Sum) = head(s)
+    TermInterface.arguments(s::Sum) = [:($coeff * $val) for (coeff, val) in s.d]
+    TermInterface.children(s::Sum) = sorted_arguments(s)
+    TermInterface.sorted_arguments(s::Sum) = [:($coeff * $val) for (coeff, val) in sort!(collect(pairs(s.d)))]
+
+    s = Sum(1 => :A, 2 => :B, 3 => :C)
+    @test operation(s) == head(s) == (+)
+    args = arguments(s)
+    @test :(1A) in args
+    @test :(2B) in args
+    @test :(3C) in args
+    
+    @test sorted_arguments(s) == [:(1A), :(2B), :(3C)]
+    @test children(s) == sorted_arguments(s)
+end