9. Functions¶

Syntax

FunctionDeclaration ::=
    FunctionQualifierList fn Name GenericParameterList? ( FunctionParameterList? ) ReturnType? WhereClause? (FunctionBody | ;)

FunctionQualifierList ::=
    const? async? ItemSafety? AbiSpecification?

FunctionParameterList ::=
    (FunctionParameter (, FunctionParameter)* ,?)
  | (SelfParameter (, FunctionParameter)* ,?)

FunctionParameter ::=
    OuterAttributeOrDoc* (FunctionParameterCore | VariadicPart | TypeSpecification)

FunctionParameterCore ::=
    PatternWithoutAlternation (TypeAscription | (: VariadicPart))

ReturnType ::=
    -> TypeSpecification

FunctionBody ::=
    BlockExpression

SelfParameter ::=
    OuterAttributeOrDoc* (ShorthandSelf | TypedSelf)

ShorthandSelf ::=
    (& LifetimeIndication?)? mut? self

TypedSelf ::=
    mut? self TypeAscription

Legality Rules

9:1 A function is a value of a function type that models a behavior.

9:2 A function declares a unique function item type for itself.

9:3 A function qualifier is a construct that determines the role of a function.

9:4 A function shall not be subject to both keyword async and keyword const.

9:5 A function parameter is a construct that yields a set of bindings that bind matched input values to names at the site of a call expression or a method call expression.

9:6 A self parameter is a function parameter expressed by keyword self.

9:7 A function shall not specify a self parameter unless it is an associated function.

9:8 The type of a function parameter is determined as follows:

• 9:9 If the function parameter is a self parameter without a TypeSpecification:

  • 9:10 And the self parameter has token & and keyword mut, then the type is &mut Self.

  • 9:11 And the self parameter has token & and lacks keyword mut, then the type is &Self.

  • 9:12 And the self parameter lacks token & and keyword mut, then the type is Self.

• 9:13 Otherwise the type is the specified type.

9:14 The pattern of a function parameter shall be an irrefutable pattern.

9:15 The expected type of the pattern of a function parameter is the type of the function parameter.

9:16 The bindings of all patterns of all function parameters of a function shall not shadow another.

9:17 A return type is the type of the result a function, closure type or function pointer type returns.

9:18 The return type of a function is determined as follows:

• 9:19 If the FunctionDeclaration specifies a ReturnType, then the return type is the specified ReturnType.

• 9:20 Otherwise the return type is the unit type.

9:21 A function body is the block expression of a function.

9:22 A function shall have a function body unless it is an associated trait function or an external block function.

9:23 A function body denotes a control flow boundary.

9:24 A function body of an async function denotes an async control flow boundary.

9:25 A function signature is a unique identification of a function that encompasses of its function qualifiers, name, generic parameters, function parameters, return type, and where clause.

9:26 A constant function is a function subject to keyword const.

9:27 The function body of a constant function shall be a constant expression.

9:28 A constant function shall be callable from a constant context.

9:29 An async function is a function subject to keyword async. An async function of the form

async fn async_fn(param: &param_type) -> return_type {
    /* tail expression */
}

9:30 is equivalent to function

fn async_fn<'a>(param: &'a param_type) -> impl Future<Output = return_type> + 'a {
    async move {
        /* tail expression */
    }
}

9:31 An external function is a function subject to function qualifier extern.

9:32 An unsafe function is a function subject to an ItemSafety with keyword unsafe.

9:33 A function shall only be subject to an ItemSafety with keyword safe if it is an external block function in an unsafe external block.

9:34 The invocation of an unsafe function shall require unsafe context.

Examples

fn eucledian_distance(left: &Point, right: &Point) -> f64 {
    let x_delta_squared: f64 = (right.x - left.x).powi(2);
    let y_delta_squared: f64 = (right.y - left.y).powi(2);

    (x_delta_squared + y_delta_squared).sqrt()
}

fn main() {}

VariadicPart ::=
   ...

unsafe extern "C" fn f(mut ap: ...) -> f64 {
    unsafe { ap.next_arg::<f64>() }
}

unsafe extern "C" fn f(mut ap: ...) { }