Add is_associated (#1629)

docs/make.jl

@@ -7,7 +7,10 @@ using Documenter, AbstractAlgebra
 # where `using AbstractAlgebra` is deliberately avoided.
 
 makedocs(
-         format = Documenter.HTML(),
+         format = Documenter.HTML(;
+            size_threshold_warn = 204800,
+            size_threshold = 409600,
+         ),
          sitename = "AbstractAlgebra.jl",
          modules = [AbstractAlgebra],
          clean = true,

docs/src/euclidean_interface.md

@@ -19,6 +19,8 @@ mulmod(f::T, g::T, m::T) where T <: RingElem
 powermod(f::T, e::Int, m::T) where T <: RingElem
 invmod(f::T, m::T) where T <: RingElem
 divides(f::T, g::T) where T <: RingElem
+is_divisible_by(f::T, g::T) where T <: RingElem
+is_associated(f::T, g::T) where T <: RingElem
 remove(f::T, p::T) where T <: RingElem
 valuation(f::T, p::T) where T <: RingElem
 gcd(f::T, g::T) where T <: RingElem

docs/src/integer.md

@@ -143,7 +143,11 @@ true
 is_divisible_by(a::BigInt, b::BigInt)
 ```
 
-** Examples **
+```@docs
+is_associated(a::BigInt, b::BigInt)
+```
+
+**Examples**
 
 ```jldoctest
 julia> r = ZZ(6)

src/AbstractAlgebra.jl

@@ -868,6 +868,7 @@ export inverse_fn
 export inverse_image_fn
 export inverse_mat
 export invmod
+export is_associated
 export is_compatible
 export is_constant
 export is_degree

src/Rings.jl

@@ -37,13 +37,27 @@ Base.:/(x::Union{Integer, Rational, AbstractFloat}, y::RingElem) = divexact(x, y
 
 Base.inv(x::RingElem) = divexact(one(parent(x)), x)
 
+@doc raw"""
+    is_divisible_by(x::T, y::T) where T <: RingElem
+
+Check if `x` is divisible by `y`, i.e. if $x = zy$ for some $z$.
+"""
 function is_divisible_by(x::T, y::T) where T <: RingElem
    if iszero(y)
       return iszero(x)
    end
    return divides(x, y)[1]
 end
 
+@doc raw"""
+    is_associated(x::T, y::T) where T <: RingElem
+
+Check if `x` and `y` are associated, i.e. if `x` is a unit times `y`.
+"""
+function is_associated(x::T, y::T) where T <: RingElem
+   return is_divisible_by(x, y) && is_divisible_by(y, x)
+end
+
 ###############################################################################
 #
 #   Evaluation

src/julia/Integer.jl

@@ -149,6 +149,16 @@ function is_divisible_by(a::BigInt, b::UInt)
                                                     (Ref{BigInt}, UInt), a, b))
 end
 
+@doc raw"""
+    is_associated(a::Integer, b::Integer)
+
+Return `true` if $a$ and $b$ are associated, i.e. if there exists a unit $c$ such that
+$a = bc$. For integers, this reduces to checking if $a$ and $b$ differ by a factor of $1$ or $-1$.
+"""
+function is_associated(a::Integer, b::Integer)
+   return a == b || a == -b
+end
+
 ###############################################################################
 #
 #   Exact division

test/Rings-test.jl

@@ -67,3 +67,19 @@ end
   @test is_finite(GF(2))
   @test !is_finite(QQ)
 end
+
+@testset "is_associated" begin
+   F = GF(13)
+   for x in F, y in F
+      @test is_associated(x, y) == (iszero(x) == iszero(y))
+   end
+
+   Fx, x = polynomial_ring(F)
+   f = x^3 + 4x + 3
+   @test is_associated(f, f)
+   @test is_associated(f, 6*f)
+   @test is_associated(7*f, f)
+   @test !is_associated(f, 0*f)
+   @test !is_associated(0*f, f)
+   @test !is_associated(f, 2x^2-x+2)
+end