Naming Conventions

This section outlines the naming convention used for methods relating to the structure system.

These naming convention are not settled and as such may not be used consistently. Nonetheless, this is the set of naming convention we should move towards using. We are open to suggestions on how the naming conventions could be better.

Use of Arc

Structure types are generally wrapped in Arcs and their methods use an Arc receiver.

Constructing a Structure Type

When constructing a structure type where not inputs allowed by Rust’s type system are valid, structure types should implement a constructor of the form new(..) -> Result<Arc<Self>, String> which returns Ok on valid inputs and a String explaining the invalidity on invalid inputs.

Structure types may also implement a constructor new_unchecked(..) -> Arc<Self> which must panic on all invalid inputs when compiled with debug_assertions enabled. new_unchecked may result in undefined behaviour if called with an invalid input with debug_assertions disabled.

A nice pattern for implementing new and new_unchecked is to provide private methods check(self: &Arc<self>) -> Result<(), String> and a new_impl(..) -> Result<Arc<Self>, String>. They should be such that calling new_impl followed by check results in no errors if and only if the inputs were valid. Then new calls new_impl followed by check while propagating any errors, and new_unchecked calls new_impl with .unwrap(), and panics if check() fails only when debug_assertions are enabled.

Obtaining a New Structure Type in General

<>_structure is used for methods on a structure type A which produce a new structure type B whenever A and B are structures on different things. It is also acceptable for methods of this type to not have the _structure suffix.

For example, .free_module(n) exists for any ring R and returns the free module of finite rank n.

Obtaining a New Structure Type with the Same Set

<>_restructure is used for methods on a structure type A which produce a new structure type B whenever A and B both implement SetSignature with the same Elem, meaning both use the same type for Elem and validate_element is Ok for A if and only if it is Ok for B on every instance of Elem.

For example, .abelian_group_restructure() exists for any order in an algebraic number field (a ring whose elements are represented by Vec<Integer>s of a fixed length n) and returns the underlying rank n free abelian group structure type whose elements are also represented by Vec<Integer>s of a fixed length n. The resulting structure type is the same as that returned by .free_module(n) on the ring of integers.

Constructing Inbound Morphisms

inbound_<> should be used for methods on a structure type A which produce a Morphism from B to A for some other structure type B.

For example, .inbound_principal_integer_map() exists for any ring R and returns the unique ring homomorphism from the integers to R.

Constructing Outbound Morphisms

outbound_<> should be used for methods on a structure type A which produce a Morphism from A to B for some other structure type B.