The Cairo Programming Language

方法语法(Method Syntax)

Methods are similar to functions: we declare them with the fn keyword and a name, they can have parameters and a return value, and they contain some code that’s run when the method is called from somewhere else. Unlike functions, methods are defined within the context of a type and their first parameter is always self, which represents the instance of the type the method is being called on. For those familiar with Rust, Cairo's approach might be confusing, as methods cannot be defined directly on types. Instead, you must define a trait and an implementation associated with the type for which the method is intended.

定义方法

Let’s change the area function that has a Rectangle instance as a parameter and instead make an area method defined on the RectangleTrait trait, as shown in Listing 5-13.

文件名： src/lib.cairo

use debug::PrintTrait;
#[derive(Copy, Drop)]
struct Rectangle {
    width: u64,
    height: u64,
}

trait RectangleTrait {
    fn area(self: @Rectangle) -> u64;
}

impl RectangleImpl of RectangleTrait {
    fn area(self: @Rectangle) -> u64 {
        (*self.width) * (*self.height)
    }
}

fn main() {
    let rect1 = Rectangle { width: 30, height: 50, };

    rect1.area().print();
}

示例5-13：定义一个用在Rectangle 上的 area 方法

To define the function within the context of Rectangle, we start by defining a trait block with the signature of the method that we want to implement. Traits are not linked to a specific type; only the self parameter of the method defines which type it can be used with. Then, we define an impl (implementation) block for RectangleTrait, that defines the behavior of the methods implemented. Everything within this impl block will be associated with the type of the self parameter of the method called. While it is technically possible to define methods for multiple types within the same impl block, it is not a recommended practice, as it can lead to confusion. We recommend that the type of the self parameter stays consistent within the same impl block. Then we move the area function within the impl curly brackets and change the first (and in this case, only) parameter to be self in the signature and everywhere within the body. In main, where we called the area function and passed rect1 as an argument, we can instead use the method syntax to call the area method on our Rectangle instance. The method syntax goes after an instance: we add a dot followed by the method name, parentheses, and any arguments.

Methods must have a parameter named self of the type they will be applied to for their first parameter. Note that we used the @ snapshot operator in front of the Rectangle type in the function signature. By doing so, we indicate that this method takes an immutable snapshot of the Rectangle instance, which is automatically created by the compiler when passing the instance to the method. Methods can take ownership of self, use self with snapshots as we’ve done here, or use a mutable reference to self using the ref self: T syntax.

We chose self: @Rectangle here for the same reason we used @Rectangle in the function version: we don’t want to take ownership, and we just want to read the data in the struct, not write to it. If we wanted to change the instance that we’ve called the method on as part of what the method does, we’d use ref self: Rectangle as the first parameter. Having a method that takes ownership of the instance by using just self as the first parameter is rare; this technique is usually used when the method transforms self into something else and you want to prevent the caller from using the original instance after the transformation.

Observe the use of the desnap operator * within the area method when accessing the struct's members. This is necessary because the struct is passed as a snapshot, and all of its field values are of type @T, requiring them to be desnapped in order to manipulate them.

The main reason for using methods instead of functions is for organization and code clarity. We’ve put all the things we can do with an instance of a type in one combination of trait & impl blocks, rather than making future users of our code search for capabilities of Rectangle in various places in the library we provide. However, we can define multiple combinations of trait & impl blocks for the same type at different places, which can be useful for a more granular code organization. For example, you could implement the Add trait for your type in one impl block, and the Sub trait in another block.

请注意，我们可以选择将方法的名称与结构中的一个字段相同。例如，我们可以在 Rectangle 上定义一个方法，并命名为width：

文件名： src/lib.cairo

use debug::PrintTrait;
#[derive(Copy, Drop)]
struct Rectangle {
    width: u64,
    height: u64,
}

trait RectangleTrait {
    fn width(self: @Rectangle) -> bool;
}

impl RectangleImpl of RectangleTrait {
    fn width(self: @Rectangle) -> bool {
        (*self.width) > 0
    }
}

fn main() {
    let rect1 = Rectangle { width: 30, height: 50, };
    rect1.width().print();
}

在这里，我们选择让width方法在实例的width字段中的值大于0时返回true，在值为0时返回false ：我们可以在同名方法的字段内使用任何目的。在main中，当我们在rect1.width后面跟着括号时，Cairo知道我们意思是width方法。当我们不使用括号时，Cairo知道我们指的是width字段。

带有更多参数的方法

Let’s practice using methods by implementing a second method on the Rectangle struct. This time we want an instance of Rectangle to take another instance of Rectangle and return true if the second Rectangle can fit completely within self (the first Rectangle); otherwise, it should return false. That is, once we’ve defined the can_hold method, we want to be able to write the program shown in Listing 5-14.

文件名： src/lib.cairo

use debug::PrintTrait;
#[derive(Copy, Drop)]
struct Rectangle {
    width: u64,
    height: u64,
}

fn main() {
    let rect1 = Rectangle { width: 30, height: 50, };
    let rect2 = Rectangle { width: 10, height: 40, };
    let rect3 = Rectangle { width: 60, height: 45, };

    'Can rect1 hold rect2?'.print();
    rect1.can_hold(@rect2).print();

    'Can rect1 hold rect3?'.print();
    rect1.can_hold(@rect3).print();
}

示例5-14：使用尚未编写的can_hold方法

预期的输出结果如下，因为rect2的两个尺寸都小于rect1的尺寸。 但rect3的宽度大于rect1：

$ scarb cairo-run
[DEBUG]	Can rec1 hold rect2?           	(raw: 384675147322001379018464490539350216396261044799)

[DEBUG]	true                           	(raw: 1953658213)

[DEBUG]	Can rect1 hold rect3?          	(raw: 384675147322001384331925548502381811111693612095)

[DEBUG]	false                          	(raw: 439721161573)

We know we want to define a method, so it will be within the trait RectangleTrait and impl RectangleImpl of RectangleTrait blocks. The method name will be can_hold, and it will take a snapshot of another Rectangle as a parameter. We can tell what the type of the parameter will be by looking at the code that calls the method: rect1.can_hold(@rect2) passes in @rect2, which is a snapshot to rect2, an instance of Rectangle. This makes sense because we only need to read rect2 (rather than write, which would mean we’d need a mutable borrow), and we want main to retain ownership of rect2 so we can use it again after calling the can_hold method. The return value of can_hold will be a Boolean, and the implementation will check whether the width and height of self are greater than the width and height of the other Rectangle, respectively. Let’s add the new can_hold method to the trait and impl blocks from Listing 5-13, shown in Listing 5-15.

文件名： src/lib.cairo

#![allow(unused)]
fn main() {
trait RectangleTrait {
    fn area(self: @Rectangle) -> u64;
    fn can_hold(self: @Rectangle, other: @Rectangle) -> bool;
}

impl RectangleImpl of RectangleTrait {
    fn area(self: @Rectangle) -> u64 {
        *self.width * *self.height
    }

    fn can_hold(self: @Rectangle, other: @Rectangle) -> bool {
        *self.width > *other.width && *self.height > *other.height
    }
}
}

示例5-15: 在Rectangle上实现can_hold方法，该方法接收另一个Rectangle实例作为参数

当我们在示例 5-14中的main函数中运行这段代码时，我们将得到我们想要的输出。 方法可以接收多个参数，我们可以在self参数之后在函数签名中添加这些参数，这些参数与函数中的参数工作原理相同。

访问实现里的函数

All functions defined within a trait and impl block can be directly addressed using the :: operator on the implementation name. Functions in traits that aren’t methods are often used for constructors that will return a new instance of the struct. These are often called new, but new isn’t a special name and isn’t built into the language. For example, we could choose to provide an associated function named square that would have one dimension parameter and use that as both width and height, thus making it easier to create a square Rectangle rather than having to specify the same value twice:

文件名： src/lib.cairo

trait RectangleTrait {
    fn square(size: u64) -> Rectangle;
}

impl RectangleImpl of RectangleTrait {
    fn square(size: u64) -> Rectangle {
        Rectangle { width: size, height: size }
    }
}

To call this function, we use the :: syntax with the implementation name; let square = RectangleImpl::square(10); is an example. This function is namespaced by the implementation; the :: syntax is used for both trait functions and namespaces created by modules. We’ll discuss modules in [Chapter 8][modules].

Note: It is also possible to call this function using the trait name, with RectangleTrait::square(10).

多个impl块

Each struct is allowed to have multiple trait and impl blocks. For example, Listing 5-15 is equivalent to the code shown in Listing 5-16, which has each method in its own trait and impl blocks.

trait RectangleCalc {
    fn area(self: @Rectangle) -> u64;
}
impl RectangleCalcImpl of RectangleCalc {
    fn area(self: @Rectangle) -> u64 {
        (*self.width) * (*self.height)
    }
}

trait RectangleCmp {
    fn can_hold(self: @Rectangle, other: @Rectangle) -> bool;
}

impl RectangleCmpImpl of RectangleCmp {
    fn can_hold(self: @Rectangle, other: @Rectangle) -> bool {
        *self.width > *other.width && *self.height > *other.height
    }
}

示例5-16：使用多个impl重写示例5-15 块

There’s no reason to separate these methods into multiple trait and impl blocks here, but this is valid syntax. We’ll see a case in which multiple blocks are useful in Chapter 8, where we discuss generic types and traits.

总结

Structs let you create custom types that are meaningful for your domain. By using structs, you can keep associated pieces of data connected to each other and name each piece to make your code clear. In trait and impl blocks, you can define methods, which are functions associated to a type and let you specify the behavior that instances of your type have.

但结构体并不是创建自定义类型的唯一方法：让我们转向 Cairo 的枚举功能，为你的工具箱再添一个工具。