Last update January 24, 2008

Standard Library / Draft Helmut /
Canonical Function

Definition: a canonical function describes its parameters and semantics completely in its name.

Example (split by regular expression):

overloaded function: String [] split(String s,String ssplit);
canonical function: String [] StringSplitString(String s,String ssplit);
object method: String[] (this_string_object.)split(String ssplit);

Example (read a file / "slurp"):

overloaded function: char [] read(String filename);
canonical function: String [] FileReturnString(String filename);
object method: none (no implementation object makes sense)

The canonical in D has a number of advantages

no-one will be forces to use them (except in cases where no other interface seems designable)
they are unique, so you can speak about them without explanations

you can say "StringSplitChar"
instead of "the overloaded split function that takes one string and one character parameter"

they may serve as readable pseudocode
they can can create truly readable code, that even speaks to a newcomer.
they work even when overloading is at its end (consider a split(String s,String regex).
they even continue to work for OO thinking even when object are at their end

consider a SystemSetTime(time) where System is something like a virtual object
consider a CustumerDelete("Bill Smith") where the customer is an object in a database that has a symbolic reference but not an implementation object

they allow to freely talk, create and implement them and later think about positioning they final interface in the library hierarchy.
they serve as a "complexity filter" because it's - almost - impossible to name functions that take many parameters or ride more than one horse.
they end the problem of "speechlessness" where the reuse of concepts isn't possible because of naming problems or because the cost of a separate object is too high.