# Generic Element Functions ## Parent and Category ### `Parent(r): RngElt -> Rng` The (default) parent ring of ring element $r$. Usually the parent of $r$ has been created explicitly before, but in certain cases, such as literal integers, rationals, reals, and values returned by certain functions a default parent is created in the background. ### `Category(r): RngElt -> Cat` ### `Type(r): RngElt -> Cat` The ‘type’ of $r$, that is, the Magma category to which the ring element $r$ belongs. The procedure call `ListCategories()` gives a list of all the categories, as does the Appendix. ## Creation of Elements ### `Zero(R): Rng -> RngElt` The zero element of ring $R$; this is equivalent to `R ! 0`. ### `One(R): Rng -> RngElt` ### `Id(R): Rng -> RngElt` The multiplicative identity $1$ of ring $R$; this is equivalent to `R ! 1`. ### `R ! a: Rng, RngElt -> RngElt` Coerce the element $a$ of some ring into the ring $R$. (The rules on coercion are explained earlier in this Chapter.) If $a$ is an integer, the coercion will always succeed: the element $a\cdot 1_R$ will be returned, where $1_R$ is the unit element of $R$. ### `Random(R): Rng -> RngElt` A random element of the finite ring $R$ (every element of $R$ has the same probability of being returned). ### `Representative(R): Rng -> RngElt` ### `Rep(R): Rng -> RngElt` A representative element of the finite ring $R$. ## Arithmetic Operations ### `+ a: RngElt -> RngElt` Element $a$. ### `- a: RngElt -> RngElt` The negation (additive inverse) of element $a$. ### `a + b: RngElt, RngElt -> RngElt` The sum of the ring elements $a$ and $b$; if $a$ and $b$ do not belong to the same ring $R$, an attempt will be made to find a common overstructure in which the sum can be taken. ### `a - b: RngElt, RngElt -> RngElt` The difference of the ring elements $a$ and $b$; if $a$ and $b$ do not belong to the same ring $R$, an attempt will be made to find a common overstructure in which the difference can be taken. ### `a * b: RngElt, RngElt -> RngElt` The product of the ring elements $a$ and $b$; if $a$ and $b$ do not belong to the same ring $R$, an attempt will be made to find a common overstructure in which the product can be taken. ### `a ^ k: RngElt, RngIntElt -> RngElt` Form the $k$-th power of the ring element $a$, for small $k$. If $k = 0$, then $a^k$ returns $1$, even when $a = 0$. If $k$ is negative, $a$ must have a multiplicative inverse and the result is $(a^{-1})^{-k}$. ### `a / b: RngElt, RngElt -> RngElt` Given an element $a$ of $R$ and a unit $b$ of $R$, form the quotient of the elements $a$ and $b$. If $b$ is not invertible in $R$, an error results, unless both $a$ and $b$ are integers, in which case `a / b` returns the rational number $a/b$. If $a$ and $b$ do not belong to the same ring $R$, an attempt will be made to find a common overstructure in which the quotient can be taken. ### `a +:= b: RngElt, RngElt -> RngElt` Mutation assignment: change $a$ into the sum of $a$ and $b$. ### `a -:= b: RngElt, RngElt -> RngElt` Mutation assignment: change $a$ into the difference of $a$ and $b$. ### `a *:= b: RngElt, RngElt -> RngElt` Mutation assignment: change $a$ into the product of $a$ and $b$. ### `a /:= b: RngElt, RngElt -> RngElt` Mutation assignment: change $a$ into the quotient of $a$ and $b$. ### `a ^:= k: RngElt, RngIntElt -> RngElt` Mutation assignment: change $a$ into the power $a^k$. ## Equality and Membership ### `a eq b: RngElt, RngElt -> BoolElt` Returns `true` if the elements $a$ and $b$ of $R$ are the same, otherwise `false`. ### `a ne b: RngElt, RngElt -> BoolElt` Returns `true` if the elements $a$ and $b$ of $R$ are distinct, otherwise `false`. ### `R eq S: Rng, Rng -> BoolElt` Returns `true` if the rings $R$ and $S$ are the same, otherwise `false`. ### `R ne S: Rng, Rng -> BoolElt` Returns `true` if the rings $R$ and $S$ are distinct, otherwise `false`. ### `a in R: RngElt, Rng -> BoolElt` Returns `true` if and only if $a$ is an element of $R$. ### `a notin R: RngElt, Rng -> BoolElt` Returns `true` if and only if $a$ is not an element of $R$. ## Predicates on Ring Elements ### `IsZero(a): RngElt -> BoolElt` Returns `true` if and only if the element $a$ of $R$ equals $0_R$. ### `IsOne(a): RngElt -> BoolElt` Returns `true` if and only if the element $a$ of $R$ equals $1_R$. ### `IsMinusOne(a): RngElt -> BoolElt` Returns `true` if and only if the element $a$ of $R$ equals the element $-1$ of $R$. ### `IsUnit(a): RngElt -> BoolElt` Returns `true` if $a$ is a unit in its parent $R$, `false` otherwise. ### `IsIdempotent(x): RngElt -> BoolElt` Returns `true` if and only if $x^2$ equals $x$. ### `IsNilpotent(x): RngElt -> BoolElt` Returns `true` if and only if some integer power $x^i$ of $x$ is zero. ### `IsZeroDivisor(x): RngElt -> BoolElt` Returns `true` if and only if $x$ is a zero-divisor, that is, there exists an element $y$ in the parent $R$ of $x$ such that $xy=0$. ### `IsIrreducible(x): RngElt -> BoolElt` Returns `true` if and only if the parent $R$ of the element $x$ is a domain and $x$ is irreducible in $R$, that is, $x$ is a non-unit of $R$ and whenever a product $ab$ of elements of $R$ divides $x$ then $a$ or $b$ is a unit of $R$. ### `IsPrime(x): RngElt -> BoolElt` Returns `true` if and only if the parent $R$ of the element $x$ is a domain and $x$ is a prime element of $R$, that is, $x$ is neither $0$ nor a unit and whenever $x$ divides the product $ab$ of two elements of $R$ it divides $a$ or $b$. ## Comparison of Ring Elements The comparison operations are only defined on types of ring that are ordered. ### `a gt b: RngElt, RngElt -> BoolElt` Returns `true` if the ring element $a$ is greater than the ring element $b$, otherwise `false`. ### `a ge b: RngElt, RngElt -> BoolElt` Returns `true` if the ring element $a$ is greater than or equal to the ring element $b$, otherwise `false`. ### `a lt b: RngElt, RngElt -> BoolElt` Returns `true` if the ring element $a$ is less than the ring element $b$, otherwise `false`. ### `a le b: RngElt, RngElt -> BoolElt` Returns `true` if the ring element $a$ is less than or equal to the ring element $b$, otherwise `false`. ### `Maximum(a, b): RngElt, RngElt -> RngElt` The maximum of the ring elements $a$ and $b$; if $a$ and $b$ do not belong to the same ring $R$, an attempt will be made to find a common overstructure in which the maximum can be taken. ### `Maximum(Q): [RngIntElt] -> RngElt` The maximum of the sequence $Q$ of ring elements. ### `Minimum(a, b): RngElt, RngElt -> RngElt` The minimum of the ring elements $a$ and $b$; if $a$ and $b$ do not belong to the same ring $R$, an attempt will be made to find a common overstructure in which the minimum can be taken. ### `Minimum(Q): [RngIntElt] -> RngElt` The minimum of the sequence $Q$ of ring elements.