9. 函数、方法和闭包：function/method/closure

// 无参数、无返回值的函数, 无返回值等效于返回 ()
fn greet_world() {
    println!("Hello, world!");
}

// 函数只能有一个返回值类型
fn function_name(parameter1: Type1, parameter2: Type2) -> ReturnType {
    // ...
}

// 接受一个参数、无返回值的函数
fn greet(name: &str) {
    println!("Hello, {}!", name);
}

// 接受两个参数、有返回值的函数
fn add(a: i32, b: i32) -> i32 {
    // 表达式的值作为函数的返回值
    a + b
}

fn main() {
    // 先使用，再定义
    fizzbuzz_to(100);
}

fn is_divisible_by(lhs: u32, rhs: u32) -> bool {
    if rhs == 0 {
        return false;
    }
    // 返回表达式值
    lhs % rhs == 0
}

// 没有指定返回值的函数返回 ()
fn fizzbuzz_to(n: u32) {
    for n in 1..=n {
        fizzbuzz(n);
    }
}

fn fizzbuzz(n: u32) -> () {
    if is_divisible_by(n, 15) {
        println!("fizzbuzz");
    } else if is_divisible_by(n, 3) {
        println!("fizz");
    } else if is_divisible_by(n, 5) {
        println!("buzz");
    } else {
        println!("{}", n);
    }
}

fn main() {
    test();

    fn test() {
        println!("just fortest");
    }
}

/*
FunctionParam :
   OuterAttribute* ( FunctionParamPattern | ... | Type)

FunctionParamPattern :
  PatternNoTopAlt : ( Type | ... )
 */

fn first((value, _): (i32, i32)) -> i32 { value }

fn variadic_fn(input: int32, input2: ...) -> i32 { value }

let my_key_fn: fn(&City) -> i64 = if xxx {my_func_1} else {my_func_2};

cities.sort_by_key(my_key_fn);

fn count_selected_cities(cities: &Vec<City>, test_fn: fn(&City) -> bool) -> usize {}

fn len(
    #[cfg(windows)] slice: &[u16],
    #[cfg(not(windows))] slice: &[u8],
) -> usize {
    slice.len()
}

Function :
   FunctionQualifiers fn IDENTIFIER GenericParams? ( FunctionParameters? ) FunctionReturnType? WhereClause? ( BlockExpression | ; )

FunctionQualifiers :
   const? async? unsafe? (extern Abi?)?

Abi :
   STRING_LITERAL | RAW_STRING_LITERAL

FunctionParameters :
      SelfParam ,? | (SelfParam ,)? FunctionParam (, FunctionParam)* ,?

SelfParam :
   OuterAttribute* ( ShorthandSelf | TypedSelf )

ShorthandSelf :
   (& | & Lifetime)? mut? self

TypedSelf :
   mut? self : Type

FunctionParam :
   OuterAttribute* ( FunctionParamPattern | ... | Type2 )

FunctionParamPattern :
   PatternNoTopAlt : ( Type | ... )

FunctionReturnType :
   -> Type

GenericParams :
   < >
   | < (GenericParam ,)* GenericParam ,? >

GenericParam :
   OuterAttribute* ( LifetimeParam | TypeParam | ConstParam )

LifetimeParam :
   LIFETIME_OR_LABEL ( : LifetimeBounds )?

TypeParam :
   IDENTIFIER( : TypeParamBounds? )? ( = Type )?

ConstParam:
   const IDENTIFIER : Type ( = Block | IDENTIFIER | -?LITERAL )?

TypeParamBounds :
   TypeParamBound ( + TypeParamBound )* +?

TypeParamBound :
      Lifetime | TraitBound

TraitBound :
      ?? ForLifetimes? TypePath // ?? 表示可选的 ？，表示该 trait boud 是可选
   | ( ?? ForLifetimes? TypePath )  // 这里的括号为字面量, 不用于分组

LifetimeBounds :
   ( Lifetime + )* Lifetime?

Lifetime :
      LIFETIME_OR_LABEL
   | 'static
   | '_

ForLifetimes :
   for GenericParams

TypePath :
   ::? TypePathSegment (:: TypePathSegment)* // 支持 ::std::vec::Vec

TypePathSegment :
   PathIdentSegment (::? (GenericArgs | TypePathFn))?

TypePathFn :
( TypePathFnInputs? ) (-> Type)?

TypePathFnInputs :
   Type (, Type)* ,?

// 其中的 GenericArgs 定义
GenericArgs :
      < >
   | < ( GenericArg , )* GenericArg ,? >

GenericArg :
   Lifetime | Type | GenericArgsConst | GenericArgsBinding | GenericArgsBounds

GenericArgsConst :
      BlockExpression
   | LiteralExpression
   | - LiteralExpression
   | SimplePathSegment

GenericArgsBinding :
   IDENTIFIER GenericArgs? = Type

GenericArgsBounds :
   IDENTIFIER GenericArgs? : TypeParamBounds

fn call_on_ref_zero<F>(f: F) where for<'a> F: Fn(&'a i32) {
    let zero = 0;
    f(&zero);
}

fn call_on_ref_zero<F>(f: F) where F: for<'a> Fn(&'a i32) {
    let zero = 0;
    f(&zero);
}

fn foo() {}
// 等效于
extern "Rust" fn foo() {}

extern fn new_i32() -> i32 { 0 }
let fptr: extern fn() -> i32 = new_i32;
// 等效于
extern "C" fn new_i32() -> i32 { 0 }
let fptr: extern "C" fn() -> i32 = new_i32;

// 声明函数使用 C ABI，这样可以导出给 C 程序调用
#[no_mangle]
extern "C" fn new_i32() -> i32 { 0 }

// extern block 声明
extern "C" {
  fn foo(); // 没有函数体，一般是 FFI 调用外部库的实现
}
unsafe { foo() }

pub fn into_vec<A>(self: Box<[T], A>) -> Vec<T, A> where A: Allocator

let s: Box<[i32]> = Box::new([10, 40, 30]);
let x = s.into_vec();
// s 已经被 move，不能再访问。

// 'middle is used in both a co- and contravariant position.
fn takes_fn_ptr<'short, 'middle: 'short>(f: fn(&'middle ()) -> &'middle (), ) {

    // As the variance at these positions is computed separately, we can
    // freely shrink 'middle in
    // the covariant position and extend it in the contravariant position.

    // 函数输入参数是逆变，返回结果是协变。
    let _: fn(&'static ()) -> &'short () = f;
}

let array: Rc<Box<[T; 3]>> = ...;
// val[i] 自动解引用 index() 方法的返回值，等效为 *array.index(0)
let first_entry = array[0];

// fn 函数：必须指定输入、输出参数类型
fn  add_one_v1  (x: u32) -> u32 { x + 1 }

// 闭包：输入、输出参数类型可以自动推导。
let add_one_v2 = |x: u32| -> u32 { x + 1 };
let add_one_v3 = |x|             { x + 1 };
let add_one_v4 = |x|               x + 1  ;

// 闭包：返回值类型自动推导为 i32
let one = || 1;

// block 中 return 或最后一个表达式值作为返回
let closure_annotated = |i: i32| -> i32 { i + outer_var };

// error：指定返回值类型时必须使用大括号
let is_even = |x: u64| -> bool x % 2 == 0;
// ok
let is_even = |x: u64| -> bool { x % 2 == 0 };

// 单行表达式的结果作为值返回
let closure_inferred  = |i | i + outer_var;

// 使用 move，闭包可以捕获上下文对象的所有权
let color = String::from("green");
let print = move || println!("`color`: {}", color);

// 闭包的输入、输出值类型一旦被推导出来后，就不能再变化。
//
// 两次函数调用的推导类型不一致，编译失败。
let example_closure = |x| x;
let s = example_closure(String::from("hello"));
let n = example_closure(5);

// 如果闭包不使用传入的参数，可以将其设置为 _。
// 传给闭包的参数列表也是 pattern 赋值语法。
fn main() {
    foobar(32, 64, |_, _| panic!("Comparing is futile!"));
}

let s = String::from("coolshell");

// s 作为闭包返回值，所以是 Move 语义。
// 在定义闭包时，s 已经被 move 捕获到闭包中，外部不能再访问。
let take_str = || s;
// s 已经被 move 进闭包，不能再访问。
//println!("{}", s);
println!("{}",  take_str()); // OK

// 在定义闭包时捕获环境中对象，但如果闭包后续不再使用，则捕获失效，原对象可以继续访问。
let mut count = 0;
let mut inc = || {
    count += 1;  // &mut 捕获 count 对象
    println!("`count`: {}", count);
};
// 错误：count 已经被闭包 &mut 捕获，所以不能再访问和修改。
// count += 2;
inc();
// OK：闭包后续不再使用，故还可以继续访问 count。
assert_eq!(count, 1);

let color = String::from("green");
// print 有效时（后续还有调用）会保有 color 的共享引用
let print = || println!("`color`: {}", color);
print();
// 由于闭包是共享引用，所以原对象还可以有其它共享引用
let _reborrow = &color;
print();
// print 后续不再使用，所以可以 move color
let _color_moved = color;

let movable = Box::new(3);
let consume = || {
    println!("`movable`: {:?}", movable);
    // drop() 方法需要拥有对象所有权，所以 movable 对象被转移到闭包中
    std::mem::drop(movable);
};
consume(); // 该闭包只能调用一次
// consume(); // 报错

fn f<F: FnOnce() -> String> (g: F) {
    println!("{}", g());
}
let mut s = String::from("foo");
let t = String::from("bar");
f(|| { s += &t; s});
// Prints "foobar".

// 自动为匿名闭包生成的类型大概如下：
struct Closure<'a> {
    s : String, // 捕获
    t : &'a String, // 借用
}

// 由于闭包返回 s 即转移了捕获对象的所有权，所以闭包只能调用一次，自动实现 FnOnce trait
impl<'a> FnOnce<()> for Closure<'a> {
    type Output = String;
    fn call_once(self) -> String {
        self.s += &*self.t;
        self.s
    }
}
// f() 函数调用的效果如下
f(Closure{s: s, t: &t});

// 闭包前加 move，无条件转移所引用的对象所有权到闭包中
use std::thread;
fn main() {
    let list = vec![1, 2, 3];
    println!("Before defining closure: {:?}", list);
    // list 所有权被转移到闭包
    thread::spawn(move ||
        println!("From thread: {:?}", list)
    ).join().unwrap();
}

let color = String::from("green");
let print = move || println!("`color`: {}", color);
print();
// 报错：color 已被转移到闭包，不能再访问。
// let _reborrow = &color;
// println!("{}", _reborrow);

// Error
fn main() {
    let movable = Box::new(3);

    // consume 只能调用一次，因为它内部将 movable 变量 move 走了。
    let consume = || {
        println!("`movable`: {:?}", movable);
        take(movable);
    };
    consume();

    // 错误：闭包捕获的 movable 所有权被转移到 take() 函数，所以闭包只能调用一次。
    // consume();
}
fn take<T>(_v: T) {}

fn main() {
    let mut a = 123;
    let ar = &a;
    // a = 456; // Error：cannot assign to `a` because it is borrowed
    println!("{ar}")
}

fn main() {
    let mut x = 4;
    // x 被共享借用
    let add_to_x = |y| y + x;

    let result = add_to_x(3);
    // 输出：The result is 7
    println!("The result is {}", result);

    // 错误：在被共享借用的有效情况下(后续会调用执行该闭包), 不能修改其值
    // x = x + 3;

    let result2 = add_to_x(3);
    println!("The result2 is {}", result2);
}

// F 是 FnOnce, 所以可以也可以传入满足前面的 Fn/FnMut 闭包
fn foobar<F>(f: F)
    where F: FnOnce() -> String
{
    println!("{}", f());
    println!("{}", f()); // 错误：error: use of moved value: `f`
}

// std::ops::FnOnce
pub trait FnOnce<Args> where Args: Tuple,
 {
     type Output;
     // Required method
     // 传入 self
     extern "rust-call" fn call_once(self, args: Args) -> Self::Output;
 }

// std::ops::FnMut，FnMut 是 FnOnce 子类型
pub trait FnMut<Args>: FnOnce<Args> where Args: Tuple,
 {
     // Required method
     // 传入 &mut self
     extern "rust-call" fn call_mut( &mut self, args: Args ) -> Self::Output;
 }

// std::ops::Fn, Fn 是 FnMut 子类型
pub trait Fn<Args>: FnMut<Args> where Args: Tuple,
  {
      // Required method
      // 传入 &self
      extern "rust-call" fn call(&self, args: Args) -> Self::Output;
  }


// F 是 Fn() 类型闭包
fn apply<F>(f: F) where F: Fn() {
    f();
}

fn main() {
    let x = 7;
    let print = || println!("{}", x);
    apply(print);
}

impl<T> [T] {
    pub fn sort_by_key<K, F>(&mut self, mut f: F)
    where
        F: FnMut(&T) -> K, // F 是 FnMutt 类型，且输入是 &T
        K: Ord,
    {
        stable_sort(self, |a, b| f(a).lt(&f(b)));
    }
}

#[derive(Debug)]
struct Rectangle {
    width: u32,
    height: u32,
}
fn main() {
    let mut list = [
        Rectangle { width: 10, height: 1 },
        Rectangle { width: 3, height: 5 },
        Rectangle { width: 7, height: 12 },
    ];
    // OK：编译器推断该闭包符合 FnMut 要求，虽然它没有捕获外围任何对象
    list.sort_by_key(|r| r.width);
    println!("{:#?}", list);
}

#[derive(Debug)]
struct Rectangle {
    width: u32,
    height: u32,
}
fn main() {
    let mut list = [
        Rectangle { width: 10, height: 1 },
        Rectangle { width: 3, height: 5 },
        Rectangle { width: 7, height: 12 },
    ];
    let mut sort_operations = vec![];
    let value = String::from("by key called");
    // 错误：编译器推断该闭包为 FnOnce 类型，不符合 sort_by_key() 的要求 FnMut
    list.sort_by_key(|r| {
        // 转移了捕获对象 value 的所有权，所以该闭包实现的是 FnOnce
        sort_operations.push(value);
        r.width
    });
    println!("{:#?}", list);
}

let add = |x, y| x + y;
let mut x = add(5,7);

type Binop = fn(i32, i32) -> i32;
let bo: Binop = add;
x = bo(5,7);

// 错误：Fn(i32) -> i32：是 trait 类型，是 unsize 大小，所以不能直接返回
// fn returns_closure() -> Fn(i32) -> i32 {
//     |x| x + 1
// }

// 正确：使用 Box 封装的 trait object
fn returns_closure() -> Box<dyn Fn(i32) -> i32> {
    Box::new(|x| x + 1)
}

// 正确：使用 impl Trait 对象
fn create_fn() -> impl Fn() {
    let text = "Fn".to_owned(q);
    move || println!("This is a: {}", text)
}

fn create_fnmut() -> impl FnMut() {
    let text = "FnMut".to_owned();
    move || println!("This is a: {}", text)
}

fn create_fnonce() -> impl FnOnce() {
    let text = "FnOnce".to_owned();
    move || println!("This is a: {}", text)
}

// 问题：C 只能保存一种固定的闭包类型
struct BasicRouter<C> where C: Fn(&Request) -> Response {
    routers: HashMap<String, C>;
}

// 解决办法：使用 trait object
type BoxedCallback = Box<dyn Fn(&Request) -> Response>;
struct BasicRouter{
    routers: HashMap<String, BoxedCallback>;
}

// C 必须加 'static, 否则后续调用 Box::new() 报错。
impl BasicRouter {
    fn add_route<C>(&mut self, url: &str, callback: C)
        where C: Fn(&Request) -> Response + 'static
      {
          self.routers.insert(url.to_string(), Box::new(callback));
      }
}

fn fn_elision(x: &i32) -> &i32 { x } // 函数 OK

let closure_elision = |x: &i32| -> &i32 { x };
// |     let closure = |x: &i32| -> &i32 { x };
// |                       -        -      ^ returning this value requires that `'1` must outlive `'2`
// |                       |        |
// |                       |        let's call the lifetime of this reference `'2`
// |                       let's call the lifetime of this reference `'1`

// 解决办法 1 :
fn main() {
    // error: lifetime may not live long enough
    // let clouse_test = |input: &String| input;

    // error: lifetime may not live long enough
    // let clouse_test = |input: &String| -> &String {input};

    // 闭包不支持定义 'lifetime
    // error[E0261]: use of undeclared lifetime name `'a`
    // let clouse_test = |input: &'a String| ->&'a String {input};

    // 使用 nightly toolchain 和开启 #![feature(closure_lifetime_binder)] 后可以使用 for 定义 'lifetime.
    let clouse_test = for <'a> |input: &'a String| ->&'a String {input};
}

// 解决办法 2 : 闭包使用外围 helper 函数定义的 lifetime
fn testStr<'a> (input: &'a String) -> &'a String {
    let closure_test = |input: &'a String | -> &'a String {input};
    return closure_test(input);
}

// 解决办法 3: 将闭包转换为 fn 函数指针，函数指针支持使用 for<'a> 来定义高阶函数，
// 而且编译期间大小是已知的。但是不能使用 Fn/FnMut/FnOnce 等 trait 类型。
let test_fn: for<'a> fn(&'a _) -> &'a _ = |p: &String| p;
println!("Results:{}", test_fn(&"asdfab".to_string()));

// 其它例子：https://github.com/rust-lang/rust/pull/56746/files
// 下面这些例子，闭包的输入参数 _x 没有使用，所以即使为它指定 'lifetime 也没有影响
fn willy_no_annot<'w>(p: &'w str, q: &str) -> &'w str {
    let free_dumb = |_x| { p }; // no type annotation at all

    let hello = format!("Hello");
    free_dumb(&hello)
}

fn willy_ret_type_annot<'w>(p: &'w str, q: &str) -> &'w str {
    // type annotation on the return type
    let free_dumb = |_x| -> &str { p };

    let hello = format!("Hello");
    free_dumb(&hello)
}

fn willy_ret_region_annot<'w>(p: &'w str, q: &str) -> &'w str {
    // type+region annotation on return type
    let free_dumb = |_x| -> &'w str { p };

    let hello = format!("Hello");
    free_dumb(&hello)
}

fn willy_arg_type_ret_type_annot<'w>(p: &'w str, q: &str) -> &'w str {
    // 如果闭包返回的是 _x, 则会报错。
    // type annotation on arg and return types
    let free_dumb = |_x: &str| -> &str { p };

    let hello = format!("Hello");
    free_dumb(&hello)
}

fn willy_arg_type_ret_region_annot<'w>(p: &'w str, q: &str) -> &'w str {
    // 如果闭包返回的是 _x, 则会报错。
    let free_dumb = |_x: &str| -> &'w str { p }; // fully annotated

    let hello = format!("Hello");
    free_dumb(&hello)
}

// https://rust-unofficial.github.io/patterns/idioms/pass-var-to-closure.html
use std::rc::Rc;
let num1 = Rc::new(1);
let num2 = Rc::new(2);
let num3 = Rc::new(3);
let closure = {
    // 建议使用下面的 rebingding 方式
    let num2 = num2.clone();  // `num2` is cloned
    let num3 = num3.as_ref();  // `num3` is borrowed
    move || {
        // `num1` is moved
        *num1 + *num2 + *num3;
    }
};

// 而非下面的形式，因为下面的 num2_cloned/num3_borrowed 的作用域在闭包之外还有效，但是它们已经 move 到闭包了，不能再使用。
use std::rc::Rc;
let num1 = Rc::new(1);
let num2 = Rc::new(2);
let num3 = Rc::new(3);
let num2_cloned = num2.clone();
let num3_borrowed = num3.as_ref();
let closure = move || {
    *num1 + *num2_cloned + *num3_borrowed;
};

  fn foo() -> ! {
      panic!("This call never returns.");
  }

  fn loop_forever() -> ! {
      loop {
          println!("I will loop forever!");
      }
  }

#![feature(never_type)]
fn main() {
    let x: ! = panic!("This call never returns.");
    println!("You will never see this line!");
}

fn some_fn() {
    // 未指定返回值,等效为返回 ();
    ()
}