Cangjie Programming Language White Paper

Author: Cangjie Language Team, Compilers & Programming Languages Lab, Huawei Technologies Co., Ltd.

With the advent of the Internet of Everything (IoE) and intelligent era, the form of software will change greatly. On the one hand, mobile applications and mobile Internet are still driving innovations in human-machine interaction, device collaboration, intelligence, and security. On the other hand, AI is also driving software to evolve towards intelligence and device-edge-cloud synergy. The development of application software in new technologies and scenarios poses new requirements and challenges to programming languages.

The Cangjie programming language is a modern programming language oriented to all-scenario application development. It provides developers with friendly development experience and excellent program performance through integration of modern language features, comprehensive compilation optimization, runtime implementation, and out-of-the-box IDE toolchain support. The specific features are as follows:

• Efficient programming: For application development, the Cangjie language is easy to learn and use, which reduces the entry threshold and workload of developers during development and supports various common development paradigms and programming modes, so that developers can express various service logics in a simple and efficient manner. The Cangjie language is a multi-paradigm programming language that supports multiple paradigms such as functional paradigm, imperative paradigm, and object-oriented paradigm, and features such as value types, classes and interfaces, generics, algebraic data types, pattern matching, and higher-order functions. In addition, the Cangjie language supports type inference, which reduces the workload of type annotation for developers. The Cangjie language has a series of concise and efficient syntax, which reduces redundant writing and improves development efficiency. Various syntax sugar and macros built in the Cangjie language help developers quickly develop domain-specific languages (DSLs) to build domain abstractions.

• Secure and reliable: As a modern programming language, the Cangjie language pursues real-time coding security. The static type system and automatic memory management are used to ensure programs' type security and memory security such as null safety. In addition, the Cangjie language provides various runtime checks, including array index out-of-bounds check, type conversion check, value calculation overflow check, and character string encoding validity check, to detect errors during program running in a timely manner. In addition, code scanning tools, obfuscation tools, and sterilizers are used to further support cross-language interoperability security and code asset protection.

• Easy concurrency: Concurrent and asynchronous programming can effectively improve processor utilization and ensure program response speed in interactive applications, which is an indispensable capability in application development. The Cangjie language implements lightweight user-level threads and concurrent object libraries, making efficient concurrency easy. The Cangjie language uses the user-level thread model. Each Cangjie thread is an extremely lightweight execution entity and has an independent execution context but shared memory. For developers, the use of user-level threads is the same as that of traditional system threads, and no extra workload is brought. From the perspective of the runtime state, thread management is completed by the runtime and does not depend on thread management of the operating system. Therefore, operations such as threads' creation, scheduling, and destruction are more efficient, and resource usage of user-level threads is less than that of system threads. To avoid data competition, the Cangjie language provides a concurrent object library. The methods of concurrent objects are thread-safe. Therefore, calling these methods in multiple threads is the same as serial programming. Developers for application logic do not need to pay attention to concurrency management. For some core libraries, the Cangjie language also provides lock-free or fine-grained lock algorithm implementations to further reduce thread blocking and improve concurrency.

• Excellent performance: The Cangjie compiler and runtime optimize the compilation of the full stack, including the high-level compilation optimization (such as semantic-aware loop optimization and semantic-aware back-end collaboration optimization) based on the Cangjie HighLevel IR (CHIR) for the compiler front-end, compilation optimization (such as SLP vectorization, Intrinsic optimization, InlineCache, interprocedural pointer optimization, and Barrier optimization) for the compiler back-end, and runtime optimization (such as lightweight lock, distributed marking, and concurrent Tracing optimization). The series of optimizations enable the Cangjie language to fully utilize the processor capability and provide excellent performance support for applications. In addition, the Cangjie language implements native lightweight design for the runtime. By modular and layered design of the runtime, the Cangjie common object models and the common basic components of the runtime are defined. Based on the common object models, basic capabilities such as memory management, stack return, exception handling, and cross-language calling during runtime are implemented, the redundant object design between multiple capabilities is greatly reduced, and the volume during runtime is reduced. In addition, the technology of loading packages by demands is used to reduce the memory overhead of redundant packages for starting Cangjie applications. Therefore, for resource-sensitive devices, less resources are occupied and the support is more user-friendly.

In addition, the Cangjie language supports a series of tool chains for application development, including language services (highlighting and association), debugging (cross-language debugging and thread-level visualized debugging), static checks, performance analysis, package management, document generation, mock tools, test frameworks, coverage tools, fuzz tools, and intelligent auxiliary programming tools, further improving software development experience and efficiency. The following describes the main features of the Cangjie language from the preceding aspects, helping readers quickly understand the positioning and main technical features of the Cangjie language.

Efficient Programming

The Cangjie language supports multiple programming paradigms, including object-oriented, functional, and imperative programming paradigms. It not only supports the modularization and flexibility of object-oriented programming, but also the simplicity and high-abstract level expression of functional programming, allowing developers to select the most appropriate paradigm based on their requirements so that they can develop code in a simple and efficient manner.

In addition, the Cangjie language has learned from many excellent language features in modern languages, including various declarative syntaxes and syntax sugars. In addition to making programming in common scenarios simpler, the Cangjie language can also quickly design a domain-specific language (DSL) for specific scenarios to improve domain usability.

Multi-Paradigm

The Cangjie language is a typical multi-paradigm programming language. It provides support for procedural programming, object-oriented programming, and functional programming, covering value types, classes and interfaces, generics, algebraic data types, and pattern matching, and for features such as treating functions as first-class citizens.

Classes and Interfaces

Cangjie supports object-oriented paradigm programming using traditional classes and interfaces. The Cangjie language supports only single inheritance. Each class has only one parent class, but can implement multiple interfaces. Each class is a subclass (direct subclass or indirect subclass) of Object. In addition, all Cangjie types (including Object) implicitly implement the Any interface.

Cangjie provides the open modifier to control whether a class can be inherited or whether an object member function can be overridden by a subclass.

In the following example, class B inherits class A and implements interfaces I1 and I2. The declaration of class A must be modified by open so that class A can be inherited. Function f in class A is also modified by open and can be overridden in class B. For a call of function f, the version to be executed is determined based on the object type, which is called dynamic dispatch.

open class A {
    let x: Int = 1
    var y: Int = 2

    open func f(){
        println("function f in A")
    }

    func g(){
        println("function g in A")
    }
}


interface I1 {
    func h1()
}

interface I2 {
    func h2()
}

class B <: A & I1 & I2 {
    override func f(){
        println("function f in B")
    }

    func h1(){
        println("function h1 in B")
    }

    func h2(){
        println("function h2 in B")
    }
}

main() {
    let o1: I1 = B()
    let o2: A = A()
    let o3: A = B()

    o1.h1() // "function h1 in B"
    o2.f()  // "function f in A"
    o3.f () // Dynamic dispatch, "function f in B"
    o3.g()  // "function g in A"
}

Cangjie interfaces can inherit each other and are not restricted by single inheritance. That is, one interface can inherit multiple parent interfaces. In the following example, I3 can inherit both I1 and I2. Therefore, implementations of functions f, g, and h must be provided to implement I3.

interface I1 {
    func f(x: Int): Unit
}

interface I2 {
    func g(x: Int): Int
}

interface I3 <: I1 & I2 {
    func h(): Unit
}

Treating Functions as First-Class Citizens

In Cangjie, a function can be used as a common expression, passed as a parameter, used as a function return value, stored in other data structures, or used to assign a value to a variable.

func f(x: Int) {
    return x
}

let a = f

let square = {x: Int = > x * x} // Lambda expression

// Defines nested functions and uses these functions as return values.
func g(x: Int): () -> Int {
    func h(){
        return f(square(x))
    }
    return h
}

func h(f: ()->Int) {
    f()
}

let b = h(g(100))

In addition to the global functions in the preceding example, member functions of data types such as object or struct can also be used as first-class citizens. In the following example, the member function resetX of object o, as a common expression, is assigned to variable f. The call of f changes the value of member variable x in object o.

class C{
    var x = 100
    func resetX(n: Int){
        x = n
        return x
    }
}

main(){
    let o = C()
    let f = o.resetX // Treats the member function as a first-class citizen.
    f(200)
    print(o.x) // 200
}

Algebraic Data Types and Pattern Matching

An algebraic data type is a composite type that consists of other data types. Two common algebraic types are product type (such as struct and tuple) and sum type (such as tagged union). The following focuses on the sum type enum in Cangjie and the corresponding pattern matching capability.

In the following example, BinaryTree of the enum type has two constructors: Node and Empty. Empty does not have any parameter, and corresponds to a binary tree with only one empty node. Node requires three parameters to construct a binary tree with one value and left and right subtrees.

enum BinaryTree {
    | Node(Int, BinaryTree, BinaryTree)
    | Empty
}

Before being accessed, the values of these enum instances must be parsed using pattern matching. Pattern matching is a method for testing whether an expression has a specific feature. Cangjie provides the match expression to implement this method. For a given expression of the enum type, the match expression is used to determine which constructor is used to construct the given expression and to extract the parameters of the corresponding constructor. In the following example, the recursive function sumBinaryTree is used to sum the integers stored in the binary tree node.

func sumBinaryTree(bt: BinaryTree): Int {
    match (bt) {
        case Node(v, l, r) =>
            v + sumBinaryTree(l) + sumBinaryTree(r)
        case Empty => 0
    }
}

In addition to the enum mode, Cangjie provides the constant mode, binding mode, type mode, and nested use of various modes. The following example describes the use of the modes provided by Cangjie.

• Constant mode: Use multiple literal values, such as integers and strings, for equality check.
• Binding mode: Bind a member at a specified location to a new variable. This mode is mainly used to deconstruct instances of the enum or tuple type. In the preceding example of sumBinaryTree, the binding mode is used to bind the actual parameters in the Node node to the three newly declared variables v, l, and r.
• Type mode: Check the subtype relationship between the variable type and target type. This mode is mainly used to convert a type to its subtype.
• Tuple mode: Compare or deconstruct instances of the tuple type.
• Wildcard mode: Match any value.

Cangjie plans to introduce more modes in the future, such as sequence mode and record mode.

// Constant mode: string literal
func f1(x: String) {
    match (x) {
        case "abc" => ()
        case "def" => ()
        case _ => () // Wildcard mode
    }
}

// tuple mode
func f2(x: (Int, Int)) {
    match (x) {
        case (_, 0) => 0 // Wildcard mode and constant mode
        case (i, j) => i / j // Binding mode, in which the element of **x** is bound to variables **i** and **j**
    }
}

// Type mode
func f3(x: ParentClass) {
    match (x) {
        case y: ChildClass1 => ...
        case y: ChildClass2 => ...
        case _ => ...
    }
}

Generics

In modern software development, generic programming has become a key technology to improve code quality, reusability, and flexibility. As a parameterized and polymorphic technology, generics allows developers to use types as parameters when defining types or functions to create common code structures that apply to different data types. The benefits of generics include:

• Code reuse: Common algorithms and data structures used to perform operations on different types can be defined to reduce code redundancy.
• Type security: More type checks during compilation are supported to prevent type errors during running, thereby enhancing program stability.
• Performance improvement: Program execution efficiency can be improved by avoiding unnecessary type conversion.

Cangjie supports generic programming. Generic variables can be introduced to functions, structs, classes, interfaces, and extends to implement function generalization. The array type is typical generic type application in Cangjie. Its syntax is Array<T>, where T indicates the element type and can be instantiated as any specific type, for example, Array<Int> or Array<String>, or even a nested array Array<Array<Int>>, so that arrays of different element types can be easily constructed.

In addition to types, generic functions can also be defined. For example, a generic function can be used to implement the concat operation on any two arrays of the same type. As shown in the following code, a generic function concat is defined which supports any two array parameters of the Array<T> type. After processing, and a new array is returned. In this way, the concat function can be applied to arrays of any type besides Array<Int>, Array<String>, and Array<Array<Int>>.

func concat<T>(lhs: Array<T>, rhs: Array<T>): Array<T> {
    let defaultValue = if (lhs.size > 0) {
        lhs[0]
    } else if (rhs.size > 0) {
        rhs[0]
    } else {
        return []
    }
    let newArr = Array<T>(lhs.size + rhs.size, item: defaultValue)
    // Copies the entire segment of continuous memory pointed to by the right expression to the entire segment of continuous memory pointed to by the left array slice.
    newArr[0..lhs.size] = lhs
    newArr[lhs.size..lhs.size+rhs.size] = rhs
    return newArr
}

The combination of generics, interfaces, and subtypes enables specific constraints on type variables in generics, thereby limiting the types that can be filled in the type variables. In the following example, the element element needs to be searched for in the array arr. Although the specific types of the array and its elements are not considered, the element type T must support operations such as equality check to check whether any element in the array is equal to the given element. Therefore, in the where clause of the lookup function, T <: Equatable<T>, that is, the type T, must implement the Equatable<T> interface.

func lookup<T>(element: T, arr: Array<T>): Bool where T <: Equatable<T> {
    for (e in arr){
        if (element == e){
            return true
        }
    }
    return false
}

The generic type of Cangjie does not support covariance. For example, arrays containing different types of elements are completely different and do not support value assignment to each other or parent-child relationships between element types. This prevents the type insecurity problem caused by array covariance. In the following example, Apple is a subclass of Fruit, but value assignment is not supported between variables a and b, and there is no parent-child relationship between Array<Fruit> and Array<Apple>.

open class Fruit {}
class Apple <: Fruit {}

main() {
    var a: Array<Fruit> = []
    var b: Array<Apple> = []
    a = b // Reports a compilation error.
    b = a // Reports a compilation error.
}

Type Extension

Cangjie supports type extensions, which allow users to add member functions to a type without changing the original type definition code. Specifically, Cangjie can extend a type by:

• Adding a function
• Adding an attribute
• Adding an overloaded operator
• Implementing an interface

In the following example, the printSize member function is added to the String type. Therefore, the printSize function can be called in the same way as calling other predefined member functions.

extend String {
    func printSize() {
        print(this.size)
    }
}

"123".printSize() // 3

When extensions and interfaces are used together, the language expression capability can be greatly improved. We can even add a new inheritance system to a type.

In the following example, a new interface Integer is defined, and then extend is used to implement the Integer interface for the existing integer types. In this way, the existing integer types become the subtypes of Integer. The sealed modifier indicates that the interface can be implemented (or extended) only in the current package.

sealed interface Integer {}

extend Int8 <: Integer {}
extend Int16 <: Integer {}
extend Int32 <: Integer {}
extend Int64 <: Integer {}

let a: Integer = 123 // ok

Type Inference

Type inference means that the compiler automatically infers the type of a variable or an expression based on the program context, so that a developer does not need to explicitly write the type. As a modern programming language, Cangjie also supports type inference.

In Cangjie, the type of a variable can be inferred based on the type of the initialization expression. In addition to the inference of variable type, Cangjie also supports the inference of the return value type of a function. In Cangjie, the last expression of a function body is regarded as the return value of the function. When the return type is omitted in the function definition, it is inferred based on the return value.

var foo = 123 // foo is 'Int64'.
var bar = 'hello' // bar is 'String'.

func add(a: Int, b: Int) { // add returns Int.
  a + b
}

Cangjie also supports the inference of type parameters in a generic function call, including the inference of generic parameters in the Currying function. The following is an example.

func map<T, R>(f: (T)->R): (Array<T>)->Array<R> {
    ...
}

map({ i => i.toString() })([1, 2, 3]) // Supports the inference of generic parameters in the Currying function.
// The inference result is map<Int, String>({ i => i.toString() })([1, 2, 3]).

Note that the parameter type (T) and return value type (R) of the lambda expression (the first parameter of map) can be inferred, and the inference of the parameter type (T) depends on the inference of the type (Array<T>) of the second parameter of map.

Other Modern Features and Syntactic Sugar

Function Overloading

In the Cangjie language, functions with the same name are supported in the same scope. The compiler determines the function to be executed based on the number and types of parameters. For example, the following absolute value functions provide implementations different numeric types. These implementations have the same function name abs, making function calls easier.

func abs(x: Int64): Int64 { ... }
func abs(x: Int32): Int32 { ... }
func abs(x: Int16): Int16 { ... }
...

Named Parameters

When a function with named parameters is called, in addition to the actual parameter expression, names of the corresponding formal parameters must be provided. Named parameters help improve program readability, reduce the sequence dependency of parameters, and simplify program expansion and maintenance.

In the Cangjie language, developers can define a named parameter by adding ! after the formal parameter name. After a formal parameter is defined as a named parameter, the parameter name must be specified before the actual parameter value when the function is called.

func dateOf(year!: Int, month!: Int, dayOfMonth!: Int) {...}

dateOf(year: 2024, month: 6, dayOfMonth: 21)

Default Value

For functions in Cangjie, default values can be provided for specific formal parameters. When a function is called, if the default value of a parameter is used as the actual parameter, the parameter can be omitted. This feature reduces the need for function overloading or the builder pattern, thereby reducing code complexity.

func dateOf(year!: Int64, month!: Int64, dayOfMonth!: Int64, timeZone!: TimeZone = TimeZone.Local) {
    ...
}

dateOf(year: 2024, month: 6, dayOfMonth: 21) // ok
dateOf(year: 2024, month: 6, dayOfMonth: 21, timeZone: TimeZone.UTC) // ok

Trailing Lambda

Cangjie supports trailing lambdas, which make it easier to implement specific syntax in DSL. Specifically, many languages provide the following classic built-in conditional judgment or loop code blocks:

if (x > 0) {
    x = -x
}

while (x > 0) {
    x--
}

Trailing lambda allows DSL developers to customize code block syntax similar to those built in the host language. The following is an example of a function call by using trailing lambda in the Cangjie language:

func unless(condition: Bool, f: ()->Unit) {
    if(!condition) {
        f()
    }
}

let a = f(...)
unless(a > 0) {
    print("no greater than 0")
}

The call of the unless function seems to be a special if expression. This syntax effect is implemented by using the trailing lambda syntax. If the last formal parameter of a function is of the function type, when the function is called, a lambda expression can be provided as the actual parameter and written outside the function call parentheses. Especially when the lambda expression is a function without parameters, the double arrows (=>) in the lambda expression can be omitted and represented as code blocks to further reduce the syntactic noise in the corresponding DSL. Therefore, in the preceding example, the second actual parameter in the unless function call becomes the following lambda expression:

{ print("no greater than 0") }

If the function has only one formal parameter which is of the function type, the function call parentheses can be omitted when trailing lambda is used to call the function, making the code simpler and more natural.

func runLater(fn:()->Unit) {
    sleep(5 * Duration.Second)
    fn()
}

runLater() { // OK
    println("I am later")
}

runLater { // The parentheses can be omitted.
    println("I am later")
}

Pipeline Operators

Cangjie introduces pipeline operators to simplify the syntax of calling nested functions and to express data flows more intuitively. The following example shows nested function calls and the equivalent expression based on the pipe operator |>. The latter reflects the data flow more intuitively. The value of the expression on the left of |> is transferred as a parameter to the function on the right.

func double(a: Int) {
    a * 2
}

func increment(a: Int) {
    a + 1
}

double(increment(double(double(5)))) // 42

5 |> double |> double |> increment |> double // 42

Operator Overloading

Cangjie defines a series of operators represented by special characters. Most of the operators can be overloaded and used on types defined by developers, providing simple and intuitive syntax expressions for operations of user-defined types.

In Cangjie, developers only need to define operator overloading functions to implement operator overloading. In the following example, a type Point is defined to represent a point in a two-dimensional plane and the + operator is overloaded to define the addition of the two points.

struct Point {
    let x: Int
    let y: Int

    init(x: Int, y: Int) {...}

    operator func +(rhs: Point): Point {
        return Point(
            this.x + rhs.x,
            this.y + rhs.y
        )
    }
}

let a: Point = ...
let b: Point = ...
let c = a + b

Property

In the object-oriented paradigm, member variables are usually declared as private, and accesses to member variables are encapsulated into two public methods: getter and setter. In this way, data access details can be hidden, making it easier to implement service policies such as access control, data monitoring, tracing and debugging, and data binding.

Properties, a special kind of syntax, are provided in Cangjie. Like a member variable, a property can be accessed and supports value assignment. In addition, getter and setter methods are provided for various data operations. The access and assignment of values to properties are translated by the compiler into calls of the corresponding getter and setter member functions. Specifically, prop is used to declare a read-only property. A read-only property only supports a getter, and therefore the get implementation must be provided. mut prop is used to declare a mutable property. Mutable properties have a getter and a setter. Therefore, the get and set implementations must be provided.

As shown in the following example, if a developer wants to record accesses to each data member of the Point type, the developer can declare member variables modified by private in the Point type, allow external accesses by declaring the corresponding properties, and use the log system Logger to record access information. For users, using properties of object p is the same as accessing its member variables but with the recording function implemented internally. In the example, x and y are read-only and therefore only the get implementation is provided. color is declared with mut prop and is variable, therefore both get and set implementations are provided.

class Point {
    private let _x: Int
    private let _y: Int
    private var _color: String

    init(x: Int, y: Int, color: String) {...}

    prop x: Int {
        get() {
            Logger.log(level: Debug, "access x")
            return _x
        }
    }

    prop y: Int {
        get() {
            Logger.log(level: Debug, "access y")
            return _y
        }
    }

    mut prop color: String {
        get() {
            Logger.log(level: Debug, "access color")
            return _color
        }

        set(c) {
            Logger.log(level: Debug, "reset color to ${c}")
            _color = c
        }
    }
}

main() {
    let p = Point(0, 0, "red")
    let x = p.x // "access x"
    let y = p.y // "access y"
    p.color = "green" // "reset color to green"
}

Security and Reliability

The design and implementation of programming languages and the corresponding tools have an important impact on program quality and security. Cangjie uses a static type system, dynamic and static checks, automatic memory management, and tool chain functions to improve program security.

Static Type and Garbage Collection

Cangjie is a statically typed language. The types of all variables and expressions in a program are determined during compilation and do not change during program running. Compared with dynamic type systems, static type systems have more constraints on developers, but they can detect errors in programs as early as possible during compilation, improving program security. In addition, static type systems make behaviors of programs easier to predict, enabling more compilation optimization and improving program performance.

Garbage collection (GC) is an automatic memory management mechanism. It can automatically identify and reclaim objects that are no longer needed, freeing developers from manually releasing memory. This not only improves development efficiency, but also effectively avoids common memory errors, improving program security. Common garbage collection technologies include tracing and reference counting (RC). The Cangjie language uses tracing GC technology to trace reference relationships between objects during run-time to identify active objects and junk objects.

Null Reference Safety

A null reference is a reference with no referent. Null references in code can cause various potential risks. Tony Hoare, a Turing Award winner, calls null references a "billion-dollar mistake".

Null references are one of the most common sources of errors in programming languages. If the language or type system does not guarantee that references are not null, programs may access members of a reference type without ensuring that the reference type is not null, causing errors or exceptions.

Null reference safety aims to eliminate the risk of null references in code.

Cangjie provides null reference safety. In Cangjie, no null value is provided. In other words, the reference types of Cangjie are always non-null. In this way, null references are prevented.

However, the representation of a null value is very useful semantically. In Cangjie, any type T may have a corresponding optional type Option<T>. A variable of type Option<T> may have a null value (None) or correspond to an actual value v of type T (Some(v)).

The optional enum type (Option<T>) is a standard algebraic data type representing a value that may be present or absent.

enum Option<T> {
    Some(T) | None
}

var a: Option<Int> = Some(123)
a = None

Note that Option<T> and T are two different types, and values of the two types cannot be converted to each other. Given an expression e of type Option<T>, we can only obtain a value of type T by pattern matching on e and receiving a value v in the Some(v) case. Therefore, any meaningful processing of the expression e needs to be accompanied by pattern matching and a corresponding check for None, so that it is impossible to directly dereference the null value None, thereby avoiding null reference exceptions.

Based on the frequent use of optional types, Cangjie also provides rich syntactic sugar support for them. For example, we can replace Option<T> with ?T, use the optional chaining operator (?.) to simplify member access, and use the null merge operator (??) to merge valid values.

var a: ?Int = None
a?.toString() // None
a ?? 123 // 123
a = Some(321)
a?.toString() // Some("321")
a ?? 123 // 321

Value Type

A value type is a type whose terms are passed by copying. For a variable of value type, the data itself instead of the reference to the data is stored. Due to being passed by copying, value types have simpler semantics with respect to mutation than reference types, making the program more predictable and reliable.

Taking the most common concurrency security problem as an example: When a reference-type object is transferred to a different thread of a program, accessing a field of the object will cause an unpredictable data race. If instead the object has value semantics, it can be ensured that the object is completely copied during transfer, so that each thread accesses the value independently, thereby ensuring concurrency safety.

Cangjie supports value types. In addition to common numeric types, Cangjie also supports implementing user-defined value types via structs.

In the following example, Point is a value type. Therefore, after values are assigned, a and b are independent of each other. The modification of a does not affect b.

struct Point {
    var x: Int
    var y: Int
    init(x: Int, y: Int) { ... }
    ...
}

var a = Point(0, 0)
var b = a
a.x = 1
print(b.x) // 0

Immutability First

Immutability refers to data that, after being created or assigned, cannot be changed. That is, the data are read-only and unwritable. Therefore, immutable objects are inherently thread-safe, that is, they can be freely accessed on any thread if no special restrictions exist. In addition, unlike with access to mutable objects, access to immutable objects has no side effects. Therefore, in some scenarios, immutable objects make programs easier to understand and provide higher security.

Immutability applies to both variables and types. Immutable variables are variables whose value cannot be changed after being initialized. Immutable types are types whose underlying data cannot be changed after construction.

In Cangjie, variables defined via let are immutable variables, and types such as String and enum-types are immutable types. These are applications of immutable ideas in Cangjie. The use of immutable variables and types can make programs more secure and facilitate understanding and maintenance of programs.

Function Parameters are Immutable

In Cangjie, formal parameters of all functions are immutable, which means that no values can be assigned to formal parameters. Furthermore, if the formal parameter is of a value type, members of the formal parameter cannot be modified.

struct Point {
    var x: Int
    var y: Int
    init(x: Int, y: Int) { ... }
    ...
}

func f(a: Point) {  // **a** is immutable.
    a = Point(0, 0) // Error
    a.x = 2 // Error
}

New Variables Introduced by Pattern Matching are Immutable

In Cangjie, variables can be bound during pattern matching, but these bound variables are immutable. Furthermore, if the newly bound variable is of a value type, members of the newly bound variable cannot be modified.

func f(a: ?Point) {
    match (a) {
        case Some(b) => // **b** is immutable.
            b = Point(0, 0) // Error
            b.x = 2 // Error
        case None => ()
    }
}

Closures Capturing Mutable Variables Cannot Escape

In Cangjie, a closure is a self-contained function or lambda. A closure can capture variables from its static scope so that those variables can be accessed even when the function is called from a different scope.

In Cangjie, closures can capture mutable variables, but such closures cannot escape their scope. This restriction avoids unexpected behavior caused by modifications of mutable variables.

func f() {
    let a = 1
    var b = 2
    func g() {
        print(a) // ok
        print(b) // ok
    }
    return g // Error. **g** captures mutable variable **b**, so **g** cannot be used as an expression.
}

Closed by Default

Although Cangjie fully supports object-orientation and class inheritance, it discourages abuse of inheritance, and in particular does not allow inheritance and overriding by default. Allowing inheritance by default encourages users to use a lot of inheritance and overriding. The mixture of overridden and non-overridden methods results in significant indirection in method definitions, which can make it hard to work out where a particular method is actually defined and what effect changes in base class definitions will have. Ill-thought-out inheritance hierarchies can also impose a rigid taxonomy which is hard to maintain and adapt as requirements and designs change.

For the sake of engineering friendliness, Cangjie adopts a closed-by-default design. That is, one cannot inherit from a class, nor override methods, by default. Developers need to explicitly decide whether their class should be allowed to have subclasses. This constraint reduces the abuse of inheritance.

Class Inheritance not Allowed by Default

In Cangjie, one cannot inherit from classes defined by developers by default. If the developer wants a class to have a subclass, they must explicitly use one of the open, abstract, or sealed modifiers. (These modifiers have slightly different semantics from each other, but all enable inheritance from the modified class.)

class A {}

class B <: A {} // Error. **A** cannot be inherited.

open class C {}

class D <: C {} // OK

Member Method Overriding not Allowed by Default

In Cangjie, one cannot override member methods defined by developers by default. This means that even if a class has a subclass, the subclass cannot modify member methods of the parent class. If you want a member method to be overridable, you must explicitly use open.

open class A {
    func f() {}
    open func g() {}
}

class B <: A {
    override func f() {} // Error. **f** cannot be overridden.
    override func g() {} // OK
}

try-with-resources

Cangjie uses try-catch-finally expressions to handle exceptions, as do many common languages. However, Cangjie provides try-with-resources syntax to automatically release non-memory resources.

Unlike with ordinary try-expressions, try-with-resources expressions do not require catch- and finally-blocks. One or more variables can be listed between the try keyword and the subsequent block to make these resource objects be automatically managed in the try-with-resources expression. When a resource exception occurs or control leaves the try-with-resources expression, the resource objects are automatically released to ensure resource security.

In the following example, the input and output variables are automatically managed in the try-with-resources expression. As such, the developer never needs to pay attention to resource release.

try (input = MyResource(),
    output = MyResource()) {
    while (input.hasNextLine()) {
        let lineString = input.readLine()
        output.writeLine(lineString)
    }
}

The resource object type (MyResource in the preceding example) must implement the Resource interface, and specifically the isClosed and close functions required by the Resource interface. isClosed lets us check whether the resource has been released, and close implements the release of resource operations. When an exception occurs or the try-block ends normally, the compiler calls the corresponding function to automatically release resources.

Dynamic Security Check

In addition to security assurance provided by static types, Cangjie also attaches great importance to runtime security checks. For some scenarios where static types are not suitable, Cangjie provides security assurance via runtime checks.

Overflow Check

Unlike most common languages, Cangjie by default performs overflow checks on integer operations, rather than wrapping.

If contextual information is sufficient, integer overflows can be detected by static analysis during compilation, and the compiler will report an error. Otherwise, if there is not enough information for static analysis, an integer overflow check will be performed at runtime, and a runtime exception will be thrown if an overflow is detected.

With this mechanism, integer overflows can be detected in a timely manner in most cases, preventing business risks.

Runtime checks lead to extra computational overhead, but the computational overhead can be controlled at a relatively low level with optimizations by the Cangjie compiler.

In some sensitive scenarios, it can be better to accept numeric wrapping for the sake of performance. In such cases, an overflow policy can be manually specified to implement the wrapping behavior common to many other languages.

@OverflowWrapping
func test(x: Int8, y: Int8) { // If **x** is 127 and **y** is 3
    let z = x + y // **z** is -126
}

Array Out-of-Bounds Check

Similarly, for index accesses to Cangjie arrays, out-of-bounds checks are performed. If information of the context is sufficient, out-of-bounds index accesses can be detected by static analysis in the compiler, and a compilation error will be reported directly. If there is not enough information for static analysis, index access checks are performed at runtime, and a runtime exception is thrown if an overflow is detected.

func f(index: Int) {
    let a = [1, 2, 3]
    let b = a[-1] // An error is reported during compilation.
    let c = a[index] // A check is performed at runtime.
}

Obfuscation

Cangjie provides multiple obfuscation technologies to protect developers' software assets and make it more difficult for attackers to attack Cangjie software. Attackers often use reverse engineering techniques to attack programs and obtain symbol names, path information, line number information, feature strings, feature constants, and control flow information from programs. Cangjie's obfuscation technology can obfuscate and hide this information, making it difficult for attackers to use the information to understand the running logic of programs.

• Layout obfuscation: Layout obfuscation obfuscates the symbol names, path information, and line number information of Cangjie applications, and rearranges the functions in the Cangjie binary. Once layout obfuscation is used on a program, attackers cannot use the information to understand the running logic of program. Layout obfuscation causes function names and variable names to be replaced by random strings, path names to be replaced by the string "SOURCE", and line numbers to be changed to 0.

• Data obfuscation: The Cangjie compiler supports string obfuscation and constant obfuscation. String obfuscation identifies plaintext strings in code and encrypts and saves them. During program initialization, the strings are decrypted and then the program is executed according to the code logic. Therefore, external attackers cannot directly obtain plaintext strings from program files and can only view encrypted data. As a result, they cannot guess the code logic based on information from string literals. For known constants used in programs, the Cangjie compiler supports constant obfuscation, which converts code snippets that use these constants into equivalent code snippets that are more difficult to understand.

• Control flow obfuscation: The Cangjie compiler supports two control flow obfuscation mechanisms: false control flow and control flow flattening. Control flow obfuscation disrupts and rearranges the patterns of jumps between basic blocks without affecting the normal execution of programs, thereby increasing the difficulty of analyzing and understanding the control flow of the program. Meanwhile, false control flow randomly adds a large number of false conditional jump branches to a program, and the condition variables of these conditional jump branches are the results of opaque predicates. The main purpose of control flow flattening is to hide the jump relationship between basic blocks while ensuring that the execution sequence of the basic blocks during actual execution is consistent with that before obfuscation, so that the normal operation of the program is not affected and attackers cannot statically know the execution sequence relationship and jump relationship between the basic blocks based on the control flow information.

Easy Concurrency

The Cangjie language provides a simple and flexible way for concurrent programming. It uses a lightweight thread model and efficient and easy-to-use lock-free concurrent objects to make concurrent programming easy, making developers capable of efficient concurrent processing. This chapter describes the core ideas, designs, and advantages of the two key technologies of Cangjie concurrent programming, and reveals how the Cangjie language implements easy concurrency.

Lightweight Thread Model

The Cangjie language uses the user-level thread model. Each Cangjie thread is an extremely lightweight execution entity with an independent execution context, and all the threads share the same memory. This model not only simplifies concurrent programming, but also brings significant performance advantages.

• Development state: The user-level thread model makes concurrent programming as easy as common programming. Generally, this model may be implemented in two solutions: stackless and stackful. Although the stackless coroutine can reduce the memory usage to a very low level, a new syntax, such as the async or await keyword, is usually required to be used in the Cangjie language. However, the use of a new syntax significantly increases the concurrent programming complexity. Developers need to manually mark functions during programming (for example, mark an asynchronous function as async and its call site as await). Such operation is contagious (that is, all functions containing await must be marked as async) and results in colored functions. Each Cangjie thread has an independent execution context and can be freely switched. Therefore, developers do not need to mark functions during programming.
• Runtime state: Compared with traditional operating system threads, the lightweight thread model has obvious advantages in performance. The lightweight thread model is entirely implemented and managed in user space, fundamentally reducing the overheads of thread creation and destruction and simplifying the thread scheduling process. This design achieves more efficient resource utilization and faster program execution in the Cangjie language, especially in high-concurrency scenarios. On one x86 server, the average time required for creating a Cangjie thread is 700 ns, which is far less than the overhead of creating an operating system thread (generally hundreds of microseconds). Because one Cangjie thread occupies only 8 KB memory, developers can create hundreds of thousands of Cangjie threads in one program at the same time, which is much more than the number of threads that can be created in an operating system.

In general, the lightweight thread model not only reduces the system load, but also enables developers to easily implement thousands or even tens of thousands of concurrent tasks without increasing programming complexity. This model has the following key advantages:

• Simple concurrent programming. The model does not impose too many syntax restrictions on concurrent programming, so that developers can easily use Cangjie threads for service processing.
• Lightweight overhead. Compared with traditional kernel threads, the user-level thread model has much lower thread creation and switching overheads. Therefore, developers can quickly create and destroy a large number of user-level threads in the Cangjie language and easily develop high-concurrency applications.
• Higher concurrency. A large number of concurrent tasks can be executed at the same time, making this model especially suitable for I/O-intensive and high-concurrency network service scenarios.
• Lower context switching costs. Context is switched in the user space, avoiding high costs of frequent switching between the kernel mode and user mode during thread switching.

This design enables developers to easily and quickly execute high-concurrency tasks in the Cangjie language. They can use simple syntax to construct a large number of user-level threads without worrying about common performance bottlenecks in traditional concurrency models. For example, a developer can easily handle multiple network requests by executing the following code:

func fetch_data(url: String) {
    let response = http_get(url)
    process(response)
}

main() {
    let urls = ["https://example.com/data1", "https://example.com/data2", ...]
    let futures = ArrayList<Future<Unit>>()
    for (url in urls) {
        let fut = spawn {fetch_data(url)} // Creates Cangjie threads to send network requests.
        futures.append(fut)
    }
    for (fut in futures) { // Waits for all Cangjie threads to complete.
        fut.get()
    }
}

In the preceding example, the spawn keyword is used to create a new Cangjie thread. Each thread independently executes the fetch_data function. The runtime environment of the Cangjie language automatically schedules these threads. Therefore, developers can focus on the implementation of service logic. Finally, the developer calls the fut.get() function to wait for and obtain the execution result of the child threads, ensuring that the main thread can obtain the execution result of the child threads synchronously.

With its obvious performance advantages and lightweight design concept, the user-level thread model used by the Cangjie language provides developers with a new and attractive solution for concurrent programming. It makes high-concurrency application coding more direct and efficient. It is not only applicable to high-load network services, but also meets the requirements of various computing-intensive tasks. By using this new concurrency model, the Cangjie language achieves simple concurrent programming and makes full use of the powerful processing capabilities of modern multi-core processors.

Lock-Free Concurrent Object

In concurrency scenarios where multiple threads share the same memory, programmers must control the sequence in which different threads access the same memory unit to prevent data races. Generally, features such as mutex are provided in programming languages to enable multiple processes to access the same memory simultaneously.

However, it is complex for programmers to control the access of threads to the shared memory which may cause poor concurrency performance.

As shown in the preceding figure, a memory block M is shared by multiple threads whose concurrent accesses to the memory block M are synchronized by a mutex. As a result, the optimal development efficiency and running performance are not achieved.

Is it possible to divide the memory block M into multiple areas and lock it in a finer granularity for better performance and enable automatic protection of shared memory by using a mutex to make multithreaded programming as simple as single-threaded programming?

The following figure shows fine-grained concurrency control. The memory block M is divided into multiple areas, and different threads can concurrently access different areas. However, the fine-grained concurrency algorithm is complex. In actual scenarios, the memory block M may represent a data structure. It is not easy to perform fine-grained concurrency control on a complex data structure, and concurrency problems, such as data races or the lack of atomicity in concurrent programming, are likely to occur.

To solve those problems, Cangjie provides concurrent objects implemented based on the fine-grained concurrency algorithm. Users can call the APIs of the concurrent objects to control the concurrent access to the shared memory by multiple threads. In this way, the following functions are implemented:

• Lock-free programming. Users can call APIs to implement efficient concurrent access to the shared memory by multiple threads.
• Concurrency security assurance. The APIs provided by the Cangjie concurrent objects eliminate data races and ensure that the call and execution of all core APIs are completed without interruption.
• Better performance. The fine-grained concurrency algorithm is used to design the Cangjie concurrent objects.
• Atomicity of concurrent programming. The core APIs provided by the Cangjie concurrent objects are "atomic". That is, from users' perspective, the call and execution of these APIs are not interrupted by other threads.

The following table lists the types of concurrent objects shared by multiple threads provided by Cangjie to guarantee concurrency security and performance.

1. Concurrency security

In concurrency scenarios, data races do not occur when a user uses an atom type and calls a concurrent data structure API to operate objects shared by multiple threads. Atom types provide users with operations of AtomicInteger, AtomicBoolean, and AtomicReference in concurrency scenarios. The call and execution of the core APIs of a concurrent data structure are not interrupted by other threads, such as the put method for key-value pair insertion, the remove method for key-value pair deletion, and the replace method for key-value pair replacement in ConcurrentHashMap. In concurrency scenarios, the call and execution of these operations are not interrupted by other threads.

2. Better concurrency performance

Concurrent Hash Map and Concurrent Queue are implemented based on the fine-grained concurrency algorithm described above. The following figure shows the performance comparison between ConcurrentHashMap and the using of a mutex to control concurrent access to HashMap by multiple threads (that is, coarse-grained concurrency control). The horizontal coordinate indicates the number of threads and the vertical coordinate indicates the number of ConcurrentHashMap operations completed per millisecond. In the ConcurrentHashMap operations, the put, remove, and get methods account for 10%, 10%, and 80% respectively. The yellow line indicates the test data of the Cangjie ConcurrentHashMap, and the blue line indicates the test data of the coarse-grained concurrency control method. It can be seen that the performance of the Cangjie ConcurrentHashMap using the fine-grained concurrency algorithm is obviously better than that of the coarse-grained concurrency control method, and that the performance is improved as the number of threads increases.

The following figure shows the performance comparison between the Cangjie BlockingQueue and the using of a mutex to control concurrent access to a queue by multiple threads (that is, coarse-grained concurrency control) in the single-producer and single-consumer scenario. We performed the comparison with queue capacity of 128 and 4096, respectively. The vertical coordinate indicates the number of elements enqueued or dequeued per millisecond. The performance of the Cangjie BlockingQueue is obviously better than that of the coarse-grained concurrency control method.

Excellent Performance

The Benchmarks Game test results show that the Cangjie language, with the value type, multi-level static analysis optimization, and ultra-lightweight runtime functions, has obvious performance advantages over similar programming languages in the industry.

Static Compilation Optimization

Cangjie compilation uses modular compilation. IR is used as the carrier between compilation processes. Different compilation optimizations do not affect each other. The adaptation of compilation optimization and the adjustment of compilation processes are more flexible. The Cangjie language uses static compilation methods to compile Cangjie programs and core library code into machine code, accelerating program running.

GC Optimizations

In Cangjie static compilation, many runtime joint optimizations are added. For example, optimization for reading and writing objects on the heap, creating heap objects, and the heap memory management signal mechanism. Static analysis and runtime joint optimization accelerate the running speed of Cangjie programs in terms of object creation, read/write, and member function call.

When objects are read and written, the Cangjie static backend uses vectorized access to guarantee data read/write and computing rates, minimizing the impact of function calls on performance. Analysis of the active scope of heap objects also ensures that the static backend can determine allocation addresses of heap objects. No matter in the heap, stack, or constant area, the static backend can optimize allocation based on characteristics of objects.

The Cangjie language can accelerate GC information collection based on accurate recording of references on the stack. Accurate recording of stack objects reduces the number of garbage collection root sets, avoiding redundant address judgment of object pointers. In the scanning and fixing phases, accurate recording of stack objects guarantees effective running of GC programs. Based on GC functions, the Cangjie language optimizes fast paths ath for object creation, reading, and writing. As shown in the following figure, when a memory access operation is compiled, a fast path and an instruction for efficiently determining the fast path are generated to reduce performance overheads.

Escape Analysis

For global analysis and optimization, escape analysis of references is added in the Cangjie language. For a reference type, the Cangjie language analyzes the lifecycle of the reference. For a reference that does not escape from the function in which the reference is located, stack allocation optimization can be used. The following code contains some escape analysis results.

class B {}

class A {
    var a: Int64 = 0
    var b: B = B()
}

var ga: A = A()

func test1(a: A) {
    a.a = 10
}

func test2(a: A) {
    ga = a // escape to global
}

func test3(a: A, b: B) {
    a.b = b
}

main() {
    var instance: A = A() // alloca on stack, not escape out this func
    instance.a = 10
    var instance1: A = A() // alloca on stack, test1 not escape param a
    test1(instance1)
    var instance2: A = A() // gc malloc in heap, test2 escape param a
    test2(instance2)
    var instance3: B = B() // alloca on stack, instance3 store into instance1, but instance1 not escaped.
    test3(instance1, instance3)
    var instance4: B = B() // gc malloc in heap, instance4 store int instance2 and instance2 escaped to global.
    test3(instance2, instance4)
}

Stack allocation optimization can directly reduce the GC pressure of automatic memory management, reduce the frequency of memory allocations on the heap, and reduce the garbage collection frequency. The read/write barrier of the heap memory can also change to direct data storage and access due to allocation on the stack, accelerating memory access. After an object is allocated on the stack, optimization measures such as SROA and DSE can be taken for the stack memory to reduce the number of memory read/write times.

Type Analysis and Devirtualization

The Cangjie language supports static analysis of global types and type prediction based on Profile. The Cangjie language supports type inheritance, virtual function calls, and interface function calls. Compared with direct calls, calls of virtual functions and interface functions require extra search and access overheads. For global, local, and interprocedural references, the Cangjie language changes calls of some virtual functions into direct calls through static analysis to accelerate function calls and improve optimization opportunities such as function inlining. In PGO mode, the Cangjie language supports statistics on the types and number of virtual function calls. The hot type and hot call parts captured based on the Profile information accelerate function calls and program execution in a conservative devirtualization manner.

Value Type Optimization

Cangjie language introduces value-type objects. Local variables of a value type can be directly accessed without GC-related barriers during memory read/write without being affected by the change of reference information. Proper use of value-type semantics can effectively improve program running efficiency.

Using value types provides more data placement and access modes. Proper data structure design provides excellent spatial/temporal locality in terms of data access, and brings more advantages in operations such as computing and access. As shown in the following figure, for the array of class A, when the member variables of the array are accessed, the load operation needs to be performed twice. For the array of the value type, the load operation needs to be performed only once when the member variables of struct A are accessed.

The On Stack Replacement (OSR) optimization technique is applicable for value types. When the OSR is used properly, some value-type data can be directly distributed to registers, which brings more advantages to data access and calculation. In the following example, an SA object of the value type is split into a and b, both of which can be represented in a register without repeated load. Subsequently, a and b can be directly represented by constants through constant propagation.

struct A {
  var a : UInt64 = 10
  var b : UInt64 = 100
}

main() {
  var SA = A()
  var sum: UInt64 = 0
  for (i in 0..100) {
    sum += SA.a
  }
  return sum + SA.b
}

After OSR optimization, the preceding source code can be converted into the following form to reduce the operations of access to struct member variables.

main() {
  var a: UInt64 = 10
  var b: UInt64 = 100
  var sum: UInt64 = 0
  for (i in 0..100) {
    sum += a
  }
  return sum + b
}

Compared with a reference type, a value type is allocated more quickly and reclaimed efficiently and automatically with the rollback of the stack space.

If a reference type is used, deep copy occurs, which introduces extra memory access overhead. If a value type is used, indirect addressing and deep copy are avoided. This advantage is more obvious in the scenarios where basic types, such as numbers and Boolean values, are processed.

Fully-Concurrent Sorting GC

The Cangjie language provides the fully-concurrent memory mark sorting GC algorithm as the base of its automatic memory management technology. It features low latency, low memory fragmentation rate, and high memory utilization.

Reducing GC Suspension Time

In some latency-sensitive important scenarios, STW GC or approximate concurrent GC cannot meet technical specifications. For example, for the 120 Hz screen refresh rate (expected to be higher in the future) in mobile scenarios, the total time required for drawing a frame should be less than 8 ms. Millisecond-level GC suspension may become the main latency factor. In a high-concurrency scenario with thousands or even tens of thousands of concurrency, the approximate concurrency algorithm needs to scan thousands of call stacks in a single STW. This operation may prolong the STW time to more than 10 ms.

Compared with the existing STW GC and mostly concurrent GC (see the following figure), Cangjie's fully-concurrent GC abandons the STW as the GC synchronization mechanism and uses a lightweight synchronization mechanism with a shorter latency. The average time required for application threads to complete GC synchronization is less than 100 microseconds, and typically, GC synchronization can be completed within tens of microseconds.

The following two key elements are used to achieve efficient GC synchronization:

• Security Point

Concurrent GC needs to process the status synchronization relationship between GC threads and application threads. The security point mechanism is a technical means used by the GC thread to control the application thread to implement GC status synchronization. The security point mechanism consists of two parts. One is the security point check code inserted when the compiler is compiling the Cangjie code, which is usually inserted on an explicit path, such as the function header or tail and loop back edge. The other is the security point synchronization logic implemented in the GC algorithm. When the GC thread needs to synchronize the GC status to a specific application thread, the GC thread first activates the security point check of the application thread. When the security point check code is executed in the application thread, the security point of the application thread is in the active status, and the application thread responds to the GC synchronization request and changes the GC status to a specified status. With the security point mechanism, the GC thread can control the change of the GC status of the application thread and work with the memory barrier to ensure that the concurrent GC can be correctly executed. Different GC statuses require corresponding memory barriers.

• Memory Barrier

The fully-concurrent GC implemented by the Cangjie language also needs to correctly process three types of data competition relationships: (1) Data competition relationships between GC threads and application threads (2) Data competition relationships between GC threads (3) Data competition relationships imported by the GC between application threads. Because the application threads share some work of the GC. The memory barrier mechanism is used to resolve data competition between GC threads and Cangjie threads. In concurrent GC, the most common data competition is between GC threads and application threads. Example: the time when the GC thread wants to move a live object to a new address and the service thread wants to access the live object almost at the same time. The memory barrier mechanism is used to maintain coordination with a GC thread when an application thread accesses the memory.

Reducing Memory Fragments and Memory Peaks

The memory sorting technology used by the Cangjie GC is one of the most cutting-edge technologies for memory reclamation (certainly, the algorithm implementation complexity of the Cangjie GC is relatively increased). Compared with the existing Mark-Sweep algorithm, the memory sorting technology can be used to migrate scattered live objects to a more compact memory layout, greatly reducing memory fragments. Compared with the replication algorithm that copies all live objects in the from-space to the to-space before the memory of the from-space is released, the memory sorting technology can be used to migrate live objects and release the memory blocks that have been sorted at the same time, eliminating the memory peak caused by GC replication.

In the fully-concurrent GC of the Cangjie language, the Cangjie heap memory is divided into small continuous memory blocks, which are called region. The from-region is a region in the from-space, and the to-region is a region in the to-space. During heap memory sorting, live objects in the from-region are migrated to a proper to-region to form a more compact memory layout. After the migration is complete, the from-region can be released for allocation of new objects. When the memory pressure is high, the from-region and to-region can overlap in the memory space to further reduce the memory peak.

Fast Object Allocation Speed

Thanks to the object migration technology used by the Cangjie GC to reclaim memory, Cangjie runtime implements an object allocation mode based on the bumping-pointer technology, which is an existing advanced memory allocation technology. A memory allocation can be completed in about 10 clock cycles on average.

Optimizing GC Overhead

Cangjie's fully-concurrent memory sorting algorithm uses pointer mark to accelerate the identification of fast paths in memory access and storage operations. Pointer mark classifies statuses of reference members in Cangjie objects into three types: (1) Unmarked. (2) Marked: The reference member is marked in the current GC process. The pointer is called current pointer. (3) Marked: The reference member is marked in the last GC process. The pointer is called old pointer. The unmarked pointer is the real address of a Cangjie object. It can be directly used for memory access and storage, which is a fast path for memory access and storage. The old pointer comes from the last GC. The pointer that has not been repaired needs to be updated after the GC thread or memory barrier queries the forwarding table in the enum and trace phases. The current pointer is marked in the enum and trace phases of the current GC to indicate which objects may be moved. When the memory barrier accesses the marked old pointer, the forwarding table needs to be queried to obtain a new address. When the memory barrier accesses the marked current pointer, it needs to determine whether the object has been transferred based on the current GC status. If the object has been transferred, the forwarding table is queried to obtain a new address. Otherwise, the memory barrier needs to transfer the object to a corresponding to-region and update the marked pointer.

In the Cangjie's fully-concurrent memory sorting algorithm, marked pointers are updated in lazy mode. The marked pointers are updated only when they are accessed by a memory barrier. If the marked pointers are not accessed, they are retained and updated in the enum and trace phases of the next GC. This policy can significantly reduce the duration of the GC process.

Adapting Value Type

As described above, value types are introduced into the Cangjie language to provide developers with better memory and performance development choices, but also make the GC implementation more complex. For reference-only programming languages (such as Java, JavaScript, and Kotlin), all types except basic types are reference types. This mode is more friendly to the GC algorithm. Value types make the GC algorithm more complex in two aspects: (1) The data of a value type may be a member of other data, or may be an independent global or local variable. In the two cases, the data of the value type is in different memory areas. However, for member methods of the value type, a unified behavior definition must be provided in the above two cases. (2) The data of the value type belongs to other value types or reference types in the embedded form. The memory layout is changed with the embedded form. During the implementation of Cangjie GC that supports object migration, the complexity of the GC engineering is greatly increased due to features of value types. Considering that value types bring developers more powerful and convenient expression capabilities, better application performance, and better memory performance, the internal complexity increased in implementation of the Cangjie language is worthwhile.

Lightweight Runtime

The Cangjie language provides the ultra-lightweight runtime function, which not only features low distribution overhead, but also achieves application deployment and running at extremely low overheads.

Through software engineering optimization, redundant code in the Cangjie runtime library is deleted, dependency on the C++ runtime library is removed, and definitions of externally invisible symbols are reduced. As a result, the binary size of the Cangjie runtime library is as small as 1 MB. The size of the runtime library with customized optimization for embedded systems completed can be as small as about 500 KB.

The Cangjie lightweight runtime function allows user-level threads to be created, run, and scheduled at extremely low overheads. It takes only hundreds of nanoseconds to create a user-level thread. User code costs only several kilo bytes of stack memory during execution, and a single scheduling takes only hundreds of nanoseconds.

The Cangjie lightweight runtime function achieves calls between the Cangjie language and the C language at nearly zero cost. In terms of underlying implementation, the ABI definition of the Cangjie language is highly compatible with that of the C language. Types compatible with the C language (that is, types modified by the "@C" keyword) in the Cangjie language have the same memory layout as the C language. In typical scenarios, data can be shared between the Cangjie language and the C language without conversion.

The Cangjie lightweight runtime function provides flexible application tailoring technologies to help developers optimize the application package size. The reflection mechanism of the Cangjie language can be enabled on demand, and can be disabled when it is not required. For private methods in the Cangjie package, redundant code can be cleared through on-demand links at the function granularity.

The Cangjie lightweight runtime function helps reduce the deployment and startup overhead of Cangjie applications to an extremely low level. The application startup duration is at the 10 ms level. Memory of applications carrying no service load is at the 1 MB level. In embedded scenarios, memory when no service load is carried is less than 1 MB.

Agile Expansion

The domain-specific language (DSL) plays an important role in modern software development because it is close to domain problems and can reduce the complexity of software development and maintenance. From a perspective of DSL implementation, the embedded DSL (eDSL) uses an existing general programming language as the host language and uses the language features provided by the host language to extend domain-oriented syntax. Compared with the implementation mode of independently constructing the DSL (dedicated syntax parsing, compilation optimization, and auxiliary tools), the eDSL has the following advantages:

• The language features of the host language can be reused, and the expression capability is strong.
• The auxiliary facilities of the host language (such as the library ecosystem, compilation tools, and development environment) can be reused, and the construction threshold is low.
• Because the eDSL is seamlessly embedded into the host language project, data can be efficiently exchanged across domains.

Therefore, the eDSL is widely used in various domains, such as UI layout, database access, cloud infrastructure deployment, and script compilation. Accordingly, the Cangjie programming language provides rich language extension capabilities to support domain-oriented eDSL construction.

This section focuses on the language extension capabilities provided by the Cangjie language, including the extension capability based on the native syntax and the metaprogramming capability that allows developers to build new syntax. Finally, this section uses the declarative UI as an example to describe how to use the preceding capabilities and the effects.

Native Syntax Extension Capability

This section describes the application of some native Cangjie syntax features in eDSL construction. Codes written using these syntaxes constitute not only eDSL programs complying with domain habits and having domain-specific meanings, but also legal Cangjie programs. Most of these syntaxes are described in the Efficient Programming section. Here, we focus on their functions in constructing eDSLs.

Type Extension and Attribute

Type extension allows you to add new functions to the original type without intrusive modification, especially for native types of languages and types defined by external libraries. Such extension improves the usability of types. The attribute mechanism provides getter and setter support for field access and hides data access details. However, getter and setter can be implicitly called using the syntax similar to that for directly accessing fields. With these two features, you can write some programs that can naturally express domain-specific meanings. For example, in the scenario where a book is borrowed from a library, we want to construct an expression similar to the natural language indicating that the book return time is two weeks later. The expected expression is as follows:

var bookReturnDate: DateTime = 2.weeks.later

You can use attributes to extend Int64:

extend Int64 {
    prop weeks: Int64 {
        get() {
            this * 7
        }
    }

    prop later: DateTime {
        get() {
            DateTime.now() + Duration.day * this
        }
    }
}

Named Parameters and Default Values

During eDSL construction, parameters need to be configured for some objects. The following may occur:

• There are many parameters, of which the configuration sequence may be incorrect.
• You do not want to set all parameters each time, and need to use the default values in most cases.

In these scenarios, you can solve the problems based on the features of named parameters and default values. For example, to set the size of a rectangular zone on a plane, you need to determine the top, bottom, left, and right positions of the rectangular zone. Generally, the top and left coordinates are 0 by default. The implementation is as follows:

class Rect {
    static func zone(top!: Int64 = 0, left!: Int64 = 0, bottom!: Int64, right!: Int64): Rect {
        //
    }
}

In this way, the rectangular zone can be configured more clearly. For example, the following call modes are allowed:

Rect.zone(bottom: 10, right: 10) // Uses the default values for **top** and **left**.
Rect.zone(top: 5, bottom: 10, right: 10) // Uses the default value for **left**.
Rect.zone(right: 10, bottom: 10) // You do not need to remember the parameter sequence.

Operator Overloading

Operator overloading enables objects of non-numeric types to implement the syntax of arithmetic operators. For example, in the library example, you can write:

DateTime.now() + Duration.day * this

In the Cangjie standard library, the add (+) operation of DateTime and the multiply (*) operation of Duration are reloaded. For example:

//DateTime
public operator func +(r: Duration): DateTime

//Duration
public operator func *(r: Int64): Duration

Trailing Lambda

The concept of trailing lambda is introduced in preceding sections, and its use is described from the perspective of constructing DSL. Here is an example of declarative UI. You can use trailing lambda to express the hierarchical relationship between components and construct an HTML-like expression paradigm.

Column {
    Image()
    Row {
        Text()
        Text()
    }
}

Column is a call to the Column function, and the braces are the lambda expression of Cangjie, which is the parameter of the Column function call provided in the trailing lambda mode. The same syntax is used for Row.

Keyword Omission

eDSL syntax noise refers to syntaxes introduced by the host language but irrelevant to actual service abstraction in the domain. The syntax noise affects the readability of the eDSL. Cangjie allows omission of the following: new during object construction, ";" at the end of a line, and return in function returns. This further simplifies the eDSL expression and reduces the syntax noise.

Macros

Macros can be seen as a kind of "code abbreviation" or a way to extend language syntax. During compilation or program running, the abbreviation is replaced with the actual code, and this replacement process is called macro expansion. Functions that can be expressed in unified and simple code can be achieved by using macros. Cangjie provides procedural macros for macro expansion in the syntax analysis phase. In the future, more easy-to-use and expressive macro definition modes will be provided, including late-stage macros and template macros.

Procedural Macros

A Cangjie procedural macro processes and transforms an input token sequence and outputs another token sequence. The input token sequence is generated by the lexical analyzer and must comply with the lexical rules of Cangjie. The output token sequence must meet the syntax and semantics of Cangjie and be a valid Cangjie program. The following example shows the working principle of the procedural macros. In this example, we are calling a DebugLog macro with expensiveComputation() as its parameter. This macro will find out (at compile time) whether the program is configured to run in development mode or in production mode. In the development mode, expensiveComputation() is run and the debugging output is printed to help detect and locate problems. In the production mode, not only do we not want to see the debug output, we also do not want to pay the performance cost of running the expensive computation.

@DebugLog( expensiveComputation() )

The macro DebugLog can be implemented like this:

public macro DebugLog(input: Tokens) {
    if (globalConfig.mode == Mode.development) {
        return quote( println( ${input} ) )
    }
    else {
        return quote()
    }
}

The macro definition syntax of Cangjie is similar to the function definition syntax. The parameter can only be a token sequence (that is, the Tokens type), and the return value is a token sequence obtained after conversion. The return value is the code generated by macro call (that is, macro expansion). In the preceding example, in the development mode, the return value is outside the input token sequence and the println function is called. Therefore, the execution result is printed in addition to the input part. If the development mode is not used, an empty sequence is returned. That is, the input part is ignored and no code is generated.

Late-stage Macros and Template Macros

The following describes two types of macros under development, that is, late-stage macros and template macros, which will be released in later versions of Cangjie.

The input token sequence of the preceding procedural macro does not contain the semantic information of the program. In some cases, users may need to perform corresponding processing according to the variable type or the class and interface declaration information in the macro definition. This capability cannot be implemented through the procedural macros. The following program is used as an example:

@FindType
var x1: Employee = Employee("Fred Johnson")
// getting the type info of `x1`: easy, it is right there

@FindType
var x2 = Employee("Bob Houston")
// getting the type info of `x2`: hard, requires type inference

Assume that the macro FindType is used to obtain the types of the variables x1 and x2 and print or add the types to the log. The type of x1, that is, Employee, is shown in the syntax and can be extracted from the input token sequence. However, the type of x2 is not shown in the declaration and therefore cannot be directly obtained from the input token sequence. The type of x2 needs to be obtained through type inference. However, macro expansion occurs in the syntax analysis phase when type inference has not been performed. Therefore, the type of x2 is unavailable. The late-stage macros can be used to obtain and utilize various semantic information of the program, including the type information, through type inference followed by macro expansion.

The late-stage macros can be used to generate code based on type information and non-local definitions in the code. It is a powerful function that extends the processing capability of macros. Any fundamental change to a piece of code of a known type is impossible. Therefore, the late-stage macros have more limited expression capability.

If a macro can be thought of as a structured rewriting from some source code to some target code, then the template macros are a better choice than the ordinary procedural macros:

public template macro unless {
    template (cond: Expr, block: Block) {
        @unless (cond) block
            =>
        if (! cond) block
    }
}

The preceding template macro definition can be used to write the following program:

@unless (x > 0) {
    print("x not greater than 0")
}

During the macro expansion, the system matches the preceding template according to the template macro definition, extracts cond and block, and converts them into the following:

if (! x > 0) {
    print("x not greater than 0")
}

The strength of template macros comes from the fact that they describe the intended source code and target code directly, putting the focus on the central transformation. A procedural macro could do the same thing, but it would require tedious and perhaps error-prone code to describe the same transformation that a template macro describes directly.

Agile Extension Case: Declarative UI

Declarative UI is a development paradigm oriented to UI programming. It allows developers to describe only the layout relationship between UI components and the binding relationship between UI components and statuses (data required for rendering), without considering the implementation details of UI rendering and refreshing. Therefore, development efficiency of the developer is improved. In recent years, the eDSL mode is used to build declarative UIs in the UI framework in the industry. In this section, the declarative UI is used as an example to describe how to use the domain extension capability of the Cangjie language to build the UI eDSL.

UI Component Layout

The UI eDSL must have the capacities of describing the layout details of various components on the two-dimensional plane, and clearly expressing the configuration information such as the length and width of components and the hierarchical relationship between components. In addition, it is expected that the UI eDSL can make code structures have some similarities with UIs to achieve the effect of "what you see is what you get.". In addition, the UI eDSL should be very concise to minimize the "noise" beyond UI descriptions. Assume that the following UI needs to be implemented. The UI consists of a segment of text and a button. The text and button need to be vertically centered. In addition, the click event processing logic needs to be set for the button.

With the UI eDSL defined by Cangjie, the following code describes the expected UI. The Text component displays a segment of text, and the Button component implements the button function. To arrange the two components vertically, the two components are embedded in a Column layout component.

class CustomView {
    ...
    func build() {
        Column {
            Text("${count} times")
                .align( Center )
                .margin(top: 50.vp, bottom: 50.vp)
            Button("Click")
                .align( Center )
                .onClick { evt =>
                    count++
                }
        }.width(100.percent)
        .height(100.percent)
    }
    ...
}

For comparison, if the Cangjie language does not provide the corresponding extension capability, developers may need to write the following code. In terms of readability, the former code is clearer and simpler. In terms of character statistics, the latter code requires developers to write nearly 70% more code than the former code, which is a considerable overhead on more complex pages.

class CustomView {
    ...
    func build() {
        new Column ({ =>
            new Text("${count} times")
                .align(Alignment.Center)
                .margin(Length(50, Unit.vp), Length(0, Unit.vp), Length(50, Unit.vp), Length(0, Unit.vp))
            new Button("Click")
                .align(Alignment.Center)
                .onClick ({ evt =>
                    count++
                })
        }).width(Length(100, Unit.percent))
        .height(Length(100, Unit.percent))
    }
    ...
}

When the Cangjie language is used to define the preceding eDSL, the following features are used:

• The trailing Lambda is used to describe the hierarchical relationship between components. For example, the Column component is used as the parent component of the Text and Button components, which determines the arrangement mode of the Text and Button components. In addition, "()" can be omitted by using the trailing Lambda to make the syntax simpler.

• Named parameters and default parameter values are used to make parameter pass clearer and simpler. For example, during the margin setting process, only the values of top and bottom need to be set. For parameters that are not set, the default values are used. In addition, the named parameters enable developers to clearly know which parameters are set, without recording the parameter sequence. This improves code readability and reduces errors.

• With the type extension capability, the expression capability of carrying a length unit for the integer type is extended. For example, 100.percent is equivalent to 100%, and 50.vp is equivalent to 50 vp. Compared with using only integers, the expression capability provides type verification assurance. Compared with using the Length class, the syntax is simpler and more readable.

• The Cangjie language supports omitting the keyword "new" during class instantiation. Enumeration prefix omittance is implemented through type inference (for example, use Center instead of Alignment.Center), which further enhances the expression simplicity.

Binding Relationship Between UI Components and States

States are a group of data associated with a UI. In a declarative UI, view = f(state) is usually used to express a relationship between a UI (view) and a state (state), where f is used as a link between view and state, is implemented by the framework, and is hidden from UI developers. Generally, f is implemented as a responsive mechanism, that is:

• Establish the binding relationship between state and the component in the view.
• Capture state changes and trigger the updates of the corresponding components.

A counter is implemented below by the modification of the top example. An @State count is added for the component, and click event processing is added for the button. Each time the button is clicked, the value of count is incremented by 1. In addition, the Text component displays the current number of clicks, that is, the value of count.

class CustomView {
    @State var count: Int64 = 0
    ...
    func build() {
        Column {
            Text("${count} times")
                .align( Center )
                .margin(top: 50.vp, bottom: 50.vp)
            Button("Click")
                .align( Center )
                .onClick { evt =>
                    count++
                }
        }.width(100.percent)
        .height(100.percent)
    }
    ...
}

The @State macro is added to the count variable so that the count variable has the responsive capability, that is, the change in the click event can be captured and the refresh of the Text component can be triggered. The above implementation mechanism is hidden in the macro implementation of @State. The following is a schematic macro expansion code logic example (actually, as described above, macro expansion occurs in the compilation phase, and the code exists in the AST form based on the expansion logic):

class CustomView {
    private var count_ = State<Int64>(0)

    mut prop count: Int64 {
        get(): Int64 {
            count_.bindToComponent()
            count_.get()
        }
        set(newValue: Int64) {
            count_.set(newVaue)
            count_.notifyComponentChanges()
        }
    }
    ...
    func build() {
        Column {
            Text("${count} times")
                .align( Center )
                .margin(top: 50.vp, bottom: 50.vp)
            Button("Click")
                .align( Center )
                .onClick { evt =>
                    count++
                }
        }.width(100.percent)
        .height(100.percent)
    }
    ...
}

To achieve the preceding effect, the following features are used:

• The @State macro for state management is defined. The macro is expanded to generate the corresponding state processing code, which reduces the workload of writing template-based and repetitive code and simplifies state declaration and management.
• The attribute mechanism is used to implement the proxy of the actual status data. The form of count reading and writing retains unchanged externally. In the internal implementation, the get method is used to capture the read operation and establish the binding relationship between the state and the component. The set method is used to capture the write operation and instruct the bound component to update.

The preceding declarative UI case demonstrates that the flexible use of Cangjie's extension capabilities can improve the readability, simplicity, and correctness of code, simplify the workload of developers, lower the threshold for using frameworks or libraries, and facilitate ecosystem promotion.

Tool Support

The Cangjie developer tool is developer-oriented and provides common development tools such as the package manager, debugger, native test framework, and IDE based on the development processes such as compilation and build, debugging, performance analysis, and LLT verification, helping developers improve development and fault locating efficiency. The developer tool improves the development efficiency and reduces the development workload by providing the following tools:

• Package manager: supports automatic dependency management and user-defined build, and provides one-stop compilation and build capabilities.
• Debugger: supports cross-language debugging and multi-thread debugging, improving debugging efficiency.
• Cangjie testing infrastructure: includes the unit test framework, the mocking framework and the benchmarking framework.
• IDE: A developer can install the Cangjie plug-in on the VSCode and Huawei DevEco Studio to use this tool out of the box.

Package Manager

Cangjie Package Manager (CJPM) provides project-level compilation and building capabilities, and automatic dependency management implements analysis and combination of multi-version third-party dependencies. Developers do not need to worry about dependency conflicts between different versions, greatly reducing their workload. It also provides a custom building mechanism based on the native Cangjie language, allowing developers to add pre-processing and post-processing steps in different phases of building. In this way, the building process can be flexibly customized to meet building requirements in different service scenarios.

Automatic Dependency Management

For multi-version dependent modules introduced in a project, CJPM performs dependency analysis and calculates the final dependency to implement automatic dependency management. Developers do not need to manually manage dependency conflicts in the project. After automatic dependency management is implemented, during compilation and building, CJPM scans all dependencies of the project and performs similar item combination for different versions of the same module dependency. In this way, compilation and building errors due to the import of dependencies of multiple versions are prevented. Developers only need to run the cjpm build command to implement project-level building, greatly reducing their workload.

As shown in the preceding figure, the project directly depends on modules A and B. Module A depends on version 1.3 of module C, and module B depends on version 1.4 of module C. If dependency analysis and management are not performed, dependency conflicts occur due to multi-version dependencies during compilation, causing a compilation error. Through dependency management, CJPM performs dependency analysis on module C and performs version dependency combination.

Custom Building

When building a Cangjie project, the developer may have other custom behavior requirements related to the compilation of Cangjie code, such as environment variable configuration, external dependency library copy, and pre-operations for compiling C language files before cffi source code dependency, for example, the Rust language uses Cargo to provide pre-building developer-defined configurations.

CJPM allows developers to add custom pre- and post-building behaviors in any phase of building, helping them solve complex project building problems without using other build tools, thereby achieving one-stop building management of the project.

As shown in the preceding figure, the developer has customized the stagePreBuild task for compiling the cffi module and the stagePostBuild task for deleting the cffi source code. When the build command is executed, CJPM executes the stagePreBuild task first. After execution of the build command is complete, CJPM executes the stagePostBuild task.

Debugger

The debugger cjdb provides source code–level debugging capabilities and supports Cangjie cross-language debugging. For example, you can enter or exit cross-language function code in single-step mode, view the complete call stack in cross-language mode, and use a single debugger to complete debugging of multiple languages. In addition, debugging of Cangjie threads is supported, further improving user debugging experience.

Cross-Language Debugging

The debugger identifies the cross-language interoperation glue code layer in the single-step process, automatically calculates addresses of target functions, and filters out glue code that users do not care about. In this way, single-step entries and exits in cross-language function calls are the same as in common function calls, and call stacks of multiple languages can be automatically combined and displayed, improving developer debugging experience. The following figures show cross-language debugging of C functions called using the Cangjie language in the IDE.

Figure 1: Cangjie -> C cross-language call

Figure 2: Cangjie -> C cross-language single-step access

Figure 3: Cangjie -> C cross-language call stack and single-step debugging in FFI-C functions

Cangjie Thread Debugging

Cangjie supports concurrent programming based on multiple Cangjie threads. When a Cangjie program is executed, Cangjie and system threads are in an M:N relationship, and the number of Cangjie threads is usually very large. Calls among Cangjie threads are asynchronous. As a result, if an exception occurs, the exception cannot be captured and processed as in a common program. The Cangjie debugger supports setting breakpoints for Cangjie threads to view call stacks.

Cangjie Testing Infrastructure

Cangjie standard library offers state-of-the-art testing experience for its users, allowing for both conventional and simple testing techniques and more advanced techniques for more advanced testing scenarios. Cangjie testing infrastructure includes three main components: the unit test framework, the mocking framework and the benchmarking framework.

Cangjie Unit Test Framework

Cangjie unit test framework, as the name suggests, allows users to create unit tests in their Cangjie projects. In addition to simple unit tests that are as simple to write as a single Cangjie function, it provides a variety of more advanced techniques:

• Parameterized test: used to run the test code on multiple inputs.
• Data-driven test: used to read multiple groups of test data from a file and use the data as inputs to test the code.
• Randomized property-based test: used to test the code on structurally-constructed random data. Compared with other programming languages in the industry that can generate only random values of the basic type and character array type for tests, Cangjie can generate various types of random values for randomized property-based test.
• Generic type–parameterized test: Generic library developers can, based on the same test code, test the implementation of a generic function on different data types by passing different types of parameters.
• Death test: Underlying library developers can use the death testing capability to capture unwanted signals, segmentation faults, and other failures that may happen in underlying libraries.

To improve user experience even more, the unit test framework introduces built-in support for power assertions and difference assertions, providing exhaustive insight into the testing data and reasoning behind failures.

All these features are highly configurable and may be used together. For example, when testing a generic function, create randomly-generated generic data types, test the algorithm implementation on the data, and use power assertions and difference assertions to obtain detailed information.

Cangjie Mocking Framework

Cangjie mocking framework allows users to change the behaviour of Cangjie classes used in tests using so-called mocks and spies: objects that can capture and modify the behaviour of particular objects to test how the rest of the program interacts with these objects. Mocking is an advanced technique mainly used for testing bigger applications that are formed from a big number of interacting components.

Users of mocking framework from other languages may find our mocking DSL very similar to what they are used in their previous experience. The DSL allows you to specify, verify and modify the behavior of objects passed to the test code and generate readable error messages. Unlike other mocking frameworks, Cangjie mocking framework is implemented based on a unique instrumentation-based compiler technique, allowing users to mock not only interfaces and open types, but final classes as well.

Cangjie mocking framework is fully integrated with the unit test framework, and any of the features of either can be used together to make the testing capability even more powerful.

Cangjie Benchmarking Framework

Cangjie testing infrastructure provides a state-of-the-art benchmarking experience, including linear regression–based statistical value calculation, warm-up, and precise measurement. Most of the features provided by the unit test framework are also available to the benchmarking framework, allowing the use of benchmark with parameters, random value generation, and generic types.

In addition, the benchmarking framework comes with its own set of features, such as calculations based on a given baseline, getting access to the raw benchmarking data (to make users' own calculations if needed), and accurate error estimation both for micro-benchmarking and macro-benchmarking scenarios.

IDE Plug-in

The Cangjie language supports code development on the VSCode and Huawei DevEco Studio bases. After the Cangjie plug-in is installed on the VSCode and Huawei DevEco Studio bases, the following features are supported:

• Project management: Cangjie projects can be created and opened (Cangjie HarmonyOS projects can be created and opened in the DevEco Studio).
• Coding assistance: Includes code highlighting, code supplementation, syntax diagnosis, floating prompt, definition redirection, reference search, formatting, metaprogramming-related coding assistance, and the like.
• Compilation and building: The HarmonyOS DevEco Studio base supports the capability of pushing Cangjie HAP packages to mobile phones for running.
• Code debugging: Includes breakpoint setting, single-step debugging, and debugging information viewing. The Huawei DevEco Studio base supports the capability of debugging Cangjie apps on mobile phones.

Future Work Plan

The Cangjie language always adheres to the design concepts of efficient programming, high security and reliability, easy concurrency, and excellent performance, bringing friendly programming experience and high-performance running experience to developers. In addition, the forms of AI for PL and PL for AI in the wave of large models are in considering. The following describes some of the exciting language abilities that are already under our planning.

AI Native Application Development

Although AI technologies have been widely used, developers generally need to have deep expertise in AI native application development and face certain challenges, such as steep learning curve and complex integration.

Common AI enablement is implemented by providing an AI application framework. However, if simpler syntax expressions can be provided in languages to lower the threshold for developers to write AI native applications, the development will become simpler and more efficient. Therefore, the Cangjie language is committed to build a declarative paradigm similar to that in the AI domain through DSL capabilities by referring to the development of web and mobile technologies.

Agent DSL is a native AI capability that is in consideration and development in the Cangjie language. It is a domain-specific language designed for AI agent development and multi-agent collaboration and is embedded in the Cangjie language. So the Agent DSL is an eDSL. Developers do not need to learn complex libraries and frameworks and can use AI functions in a simple and intuitive manner through the Agent DSL.

// Definition of the Agent
@agent class Planner {
  @prompt[pattern=APE] (
    action: "Help users make a travel route.",
    purpose: "Allow users to visit scenic spots within a planned time and get adequate rest.",
    expectation: "Generate a reasonable travel route, including time, scenic spot, commute, and other information."
    )
}

// Usage of the Agent
let agent = Planner()
let result = agent.chat("I want to go to Shanghai.")

Based on the above code snippet, it is clear that declaration and usage syntaxes of the Agent in the Cangjie language is the same as that of Cangjie syntax. In this way, use of the Agent can provide the static check capability of the Cangjie language without bringing extra learning burden to developers, fully utilizing the advantages of efficient programming, security, and reliability of the Cangjie language.

The Agent DSL not only improves the efficiency of AI application development, but also allows the code to accurately correspond to the operations and decision-making processes of the AI Agent. The overall design of the Agent DSL aims to achieve the following effects:

• Advanced abstraction: As a built-in language abstraction in the DSL, the definition and description of the Agent are more natural and intuitive, and are easy to understand and maintain.
• Simplified multi-agent collaboration programming: Different agent collaboration modes are abstracted through streaming symbols, and developers can easily utilize multi-agent collaboration to develop applications with higher intelligence.
• Intelligent development tool chain: On the basis of the Agent DSL, the tool chain provides developers with all-round intelligent support from application development to performance commissioning and optimization.

In addition to the Agent DSL, an AI native application framework is also being built. Through the cooperation between native languages and frameworks, developers can enjoy new application programming experience in the all-scenario intelligent era.

DSL Kit

It is well known that the threshold for compiling macro features is relatively high. DSL can be considered as a larger macro, which requires more attention to details and is more complex.

As the complexity increases, developers need to invest more energy, some of which is necessary (in blue) and some of which is extra (in yellow). Capabilities of the expert compiler master level are not expected to be a must for DSL development.

Therefore, DSL Kit extracts some commonalities created of DSL creation and provides a toolkit to eliminate the extra unnecessary efforts (in yellow).

In the first phase, it is expected to provide an easy declarative BNF syntax and automatically generate a syntax parser for the DSL, eliminating the complexity of manually writing parsers.

In the second phase, it is expected to provide more detailed check, analysis, and optimization capabilities. For example, semantics are added to the declarative syntax by referring to the attribute syntax, and the static check capability is provided with the compiler to help guarantee correctness of the DSL context for developers during compilation.

Actor and Distributed Programming

Concurrent programming and distributed programming are becoming increasingly important in multi-core and many-core hardware environments. Support for these capabilities has been considered since the early stage of Cangjie language design, and the design and prototype jobs have been preliminarily completed. These capabilities will be available in the near future.

With the built-in Actor feature and support for the type system in the Cangjie language, a secure and intuitive concurrent and distributed model can be provided for developers.

Actor is an abstract program concept used for concurrent operations. It is essentially used to create an operation instance and respond to a received message. For example, a newly created Actor sends a message to another Actor, and specifies the behavior to be generated when the next message is received. In this way, communication in concurrent threads is based on policies in these messages, thereby avoiding data race.

In the following simple example, the actor keyword is used to define Account as the Actor type, an instance function performWithdraw, and a receiver function withdraw. The receiver function can receive and process messages, and the instance function can access the internal status of the Actor.

actor Account {
    instance var balance: Int64
    init(x: Int64) {
        this.balance = x
    }
    instance func performWithdraw(amount: Int64): Unit {
        balance -= amount
    }
    receiver func withdraw(amount: Int64): Bool {
        if (this.balance < amount) {
            return false
        } else {
            this.performWithdraw(amount)
            return true
        }
    }
}

It is worth mentioning that Cangjie's Actor is designed to support concurrent programming and distributed programming with a unified language feature. This enables developers to write concurrent or distributed programs using methods they are familiar with, and then easily move the programs to a distributed (for example, cluster) environment.

IDE AI Enablement

In mainstream IDE environments such as IntelliJ IDEA and VS Code, auxiliary development capabilities are provided. During the development by using the Cangjie language, AI-assisted programming capabilities are deployed. In the future, the main exploration will focus on code generation and knowledge Q&A. Currently, the preliminary code generation capability has been pre-researched, as shown in the following:

• Single-line code generation

When "(a:" is entered, code generation of the current line is triggered and the code of the current line can be supplemented by pressing tab.

• Code snippet generation

During the development by using the Cangjie language, if Enter is pressed, the generative model generates subsequent code snippets in the current position based on the preceding content and displays the subsequent code snippets in grayscale. The subsequent code snippets can be added by pressing Tab and canceled by pressing Esc.

In addition, the capabilities of generating code based on the subsequent content and supplementing character-level/token-level code are provided. The Cangjie language is committed to fully release the productivity of each developer and build an immersive coding experience with accurate intent recognition, excellent results, and good interaction.

Visualized Concurrent and Parallel Program Tuning

Cangjie provides excellent concurrent and parallel models. However, when using a concurrent and parallel model for development, a developer often encounters problems such as pseudo-parallelism, parallel failure, and parallel scheduling and spends a lot of time locating problems, resulting in low efficiency. In this case, a visualized concurrent and parallel tuning tool is required to help us quickly locate problems to master parallel scheduling information and find the performance bottleneck of parallel scheduling.

In the future, we will provide a visualized concurrent and parallel tuning tool to display the entire task scheduling period, including task statistics in different concurrency modes and the running status of a single task.

• In the measure lane, you can select different concurrency modes and view the change trend and number of tasks in different states. For example, if you want to know the number of running tasks in a period of time, you can move the pointer to the corresponding lane and view the exact number of tasks at a specified time.

• You can select different concurrency modes in the tasks lane to view the lifecycle information of related tasks and the running status of multiple tasks, helping you quickly detect concurrent and parallel problems.

Lexical Structure

This chapter describes the lexical structure of the Cangjie programming language. For the complete BNF of the lexicon and syntax, see"Cangjie Syntax."

Note: To improve the readability of the document, the syntax definition in the text body is slightly different from that in the appendix. In the text body, symbols and keywords are replaced with their literal representations (rather than names in the lexical structure).

Identifiers and Keywords

Identifiers are classified into common identifiers and raw identifiers. A common identifier starts with an underscore (ASCII code _) or an XID_Start character, followed by XID_Continue characters of any length, and the keyword Cangjie is removed. XID_Start and XID_Continue are properties defined in the Unicode Standard, as detailed in [Unicode Standard Annex #31] (https://www.unicode.org/reports/tr31/tr31-37.html). The current version used by Cangjie is 15.0.0. A raw identifier is a common identifier enclosed by a pair of backquotes (``). Keywords can also be used in within the backquotes.

Identifier
    : Ident
    | RawIdent
    ;

fragment RawIdent
    : '`' Ident '`'
    ;

fragment Ident
    : XID_Start XID_Continue*
    | '_' XID_Continue+
    ;

In Cangjie, all identifiers are identified in the form of Normalization Form C (NFC). If two identifiers are equal after normalization to NFC, they are considered to be the same. For the definition of NFC, see Unicode tr15.

For example, the following are some valid Cangjie identifiers:

foo
_bar
Cangjie
`if`

Keywords are special character strings that cannot be used as identifiers. The following table lists the Cangjie keywords.

Contextual keywords are special strings that can be used as identifiers. They exist as keywords in some syntaxes, but can also be used as common identifiers.

Semicolons and Newline Characters

There are two symbols that can indicate the end of an expression or declaration: a semicolon (;) and a newline character. The meaning of ; is fixed. It indicates the end of an expression or declaration regardless of its position, and multiple expressions or declarations can be written on the same line, separated by ;. However, the meaning of a newline character is not fixed. Depending on its position, it can be used as a separator between two tokens like a space character, or indicates the end of an expression or declaration like a ;.

A newline character can be used between any two tokens. Generally, the "longest match" principle (using as many tokens as possible to form a valid expression or declaration) is followed to determine whether to treat the newline character as the separator between tokens or the terminator of the expression or declaration. The newline character encountered before the "longest match" ends is treated as the separator between tokens, and that encountered after the "longest match" ends is treated as the terminator of the expression or declaration. The following shows examples:

let width1: Int32 = 32 // The newline character is treated as a terminator.
let length1: Int32 = 1024 // The newline character is treated as a terminator.
let width2: Int32 = 32; let length2: Int32 = 1024 // The newline character is treated as a terminator.
var x = 100 + // The newline character is treated as a separator.
200 * 300 - // The newline character is treated as a separator.
50 // The newline character is treated as a terminator.

However, the "longest match" principle does not apply to scenarios where a newline character cannot be used as the separator between two tokens, string literals, and multi-line comments. A newline character cannot be used as the separator between two tokens in the following scenarios:

• Do not use a newline character as the separator between unary operator and operand.

• In the calling expression, do not use a newline character as the separator between ( and its previous token.

• In an index access expression, do not use a newline character as the separator between [ and its previous token.

• In constant pattern, do not use a newline character as the separator between $ and the identifier following it.

Note: In the preceding scenarios, the newline character cannot be used as the separator between two tokens. It does not mean that the newline character cannot be used in these scenarios. (If a newline character is used, it will be directly treated as the terminator of the expression or declaration.)

The "longest match" principle does not apply to string literals and multi-line comments.

• For a single-line string, when a non-escape double quotation mark is encountered for the first time, the matching ends.

• For a multi-line string, when three non-escaped double quotation marks are encountered for the first time, the matching ends.

• For a multi-line raw string, when the non-escape double quotation marks and the same number of comment tags (#) at the beginning are encountered for the first time, the matching ends.

• For a multi-line comment, when the first */ is encountered, the matching ends.

Literals

A literal is an expression that represents a value that cannot be modified.

Literals also have types. In Cangjie, the types of literals include integer, floating-point, Rune, Boolean, and string. The syntax of literals is as follows:

literalConstant
    : IntegerLiteral
    | FloatLiteral
    | RuneLiteral
    | booleanLiteral
    | stringLiteral
    ;
    
stringLiteral
    : lineStringLiteral
    | multiLineStringLiteral
    | MultiLineRawStringLiteral
    ;

Literals of the Integer Type

An integer literal can be expressed using four number notations: binary (using the 0b or 0B prefix), octal (using the 0o or 0O prefix), decimal (without a prefix), and hexadecimal (using the 0x or 0X prefix). In addition, you can add an optional suffix to specify the specific type of the integer literal.

The syntax of the literal of the integer type is defined as follows:

IntegerLiteralSuffix
   : 'i8' |'i16' |'i32' |'i64' |'u8' |'u16' |'u32' | 'u64'
   ; 
 
IntegerLiteral
   : BinaryLiteral IntegerLiteralSuffix?
   | OctalLiteral IntegerLiteralSuffix?
   | DecimalLiteral '_'* IntegerLiteralSuffix?
   | HexadecimalLiteral IntegerLiteralSuffix?
   ;

BinaryLiteral
	: '0' [bB] BinDigit (BinDigit | '_')*
	;

BinDigit
	: [01]
	;

OctalLiteral
	: '0' [oO] OctalDigit (OctalDigit | '_')*
	;

OctalDigit
	: [0-7]
	;

DecimalLiteral
	: ([1-9] (DecimalDigit | '_')*) | DecimalDigit
	;

DecimalDigit
	: [0-9]
	;

HexadecimalLiteral
	: '0' [xX] HexadecimalDigits
	;
HexadecimalDigits
   	: HexadecimalDigit (HexadecimalDigit | '_')*
   	;
    
HexadecimalDigit
   	: [0-9a-fA-F]
   	;

The mappings between suffixes and types for IntegerLiteralSuffix are as follows:

Literals of the Floating-Point Type

A floating-point literal can be expressed in two formats: decimal (without a prefix) and hexadecimal (with a 0x or 0X prefix). In a decimal floating-point number, either the integer part or the fractional part (including the decimal point), or both, must be contained. If there is no decimal part, the exponent part (with an e or E prefix) is required. In a decimal floating-point number, the integer part, the fractional part (including the decimal point), or both, must be contained, and the exponent part (with a p or P prefix) is required. In addition, you can add an optional suffix to specify the specific type of the floating-point literal.

The syntax of the literal of the floating-point type is defined as follows:

FloatLiteralSuffix
    : 'f16' | 'f32' | 'f64'
    ;
 
FloatLiteral
    : (DecimalLiteral DecimalExponent | DecimalFraction DecimalExponent? | (DecimalLiteral DecimalFraction) DecimalExponent?)  FloatLiteralSuffix? 
    | (Hexadecimalprefix (HexadecimalDigits | HexadecimalFraction | (HexadecimalDigits HexadecimalFraction)) HexadecimalExponent) 

DecimalFraction 
    : '.' DecimalFragment
    ;

DecimalFragment
    : DecimalDigit (DecimalDigit | '_')*
    ;
    
DecimalExponent 
    : FloatE Sign? DecimalFragment
    ;
    
HexadecimalFraction 
    : '.' HexadecimalDigits
    ;

HexadecimalExponent 
    : FloatP Sign? DecimalFragment
    ;
    
FloatE 
    : [eE]
    ;

FloatP 
    : [pP]
    ;

Sign 
    : [-]
    ;

Hexadecimalprefix 
    : '0' [xX]
    ;

The mappings between suffixes and types for FloatLiteralSuffix are as follows:

Literals of the Boolean Type

There are only two boolean type literals: true and false.

booleanLiteral
    : 'true'
    | 'false'
    ;

Literals of the String Type

String literals are classified into three types: single-line string literals, multi-line string literals, and multi-line raw string literals.

Single-line string literals are defined using a pair of single or double quotation marks. The content in the quotation marks can be any number of characters. To include a quotation mark or a backslash (\) as part of the string, add a backslash (\) before it. A single-line string literal cannot span multiple lines by including newline characters.

The syntax of single-line string literals is defined as follows:

lineStringLiteral
    : '"' (lineStringExpression | lineStringContent)* '"'
    ;
    
lineStringExpression
    : '${' SEMI* (expressionOrDeclaration (SEMI+ expressionOrDeclaration?)*) SEMI* '}'
    ;
    
lineStringContent
    : LineStrText
    ;
    
LineStrText
    : ~["\\\r\n]
    | EscapeSeq
    ;

A multi-line string literal must start and end with three double quotation marks (""") or three single quotation marks ('''). The content in the quotation marks can be any number of characters. To include the three quotation marks (" or ') used to enclose the string or backslashes (\) as part of the string, you must add backslashes (\) before them. If there is no newline character after the three double quotation marks at the beginning, or no non-escape double quotation marks are encountered before the end of the current file, a compilation error is reported. Unlike single-line string literals, multi-line string literals can span multiple lines.

The syntax of multi-line string literals is defined as follows:

multiLineStringLiteral
    : '"""' NL (multiLineStringExpression | multiLineStringContent)* '"""'
    ;
    
multiLineStringExpression
    : '${' end* (expressionOrDeclaration (end+ expressionOrDeclaration?)*) end* '}'
    ;
    
multiLineStringContent
    : MultiLineStrText
    ;

MultiLineStrText
    : ~('\\')
    | EscapeSeq
    ;

A multi-line raw string literal starts and ends with one or more comment tags (#) and one single quotation mark (') or double quotation mark ("). Both the number of comment tags and the quotation marks at the end are the same as those at the beginning. The literal content can be any number of valid characters. Before the current file ends, if no matching quotation mark and the same number of comment tags are encountered, a compilation error is reported. Like multi-line string literals, a multi-line raw string literal can span multiple lines. The difference is that escape rules do not apply to multi-line raw string literals. The content in the literals remains unchanged (escape characters are not escaped).

The syntax of multi-line raw string literals is defined as follows:

MultiLineRawStringLiteral
    : MultiLineRawStringContent
    ;

fragment MultiLineRawStringContent
    : '#' MultiLineRawStringContent '#' 
    | '#' '"' .*? '"' '#'
    ;

Literals of the Rune Type

A Rune literal starts with the character r, followed by a single-line string literal (with single or double quotation marks). The string literal must contain exactly one character. The syntax is as follows:

RuneLiteral
    : 'r' '\'' (SingleChar | EscapeSeq) '\''
    : 'r' '"' (SingleChar | EscapeSeq) '"'
    ;

fragment SingleChar
	:	~['\\\r\n]
	;

EscapeSeq
    : UniCharacterLiteral
    | EscapedIdentifier
    ;

fragment UniCharacterLiteral
    : '\\' 'u' '{' HexadecimalDigit '}'
    | '\\' 'u' '{' HexadecimalDigit HexadecimalDigit '}'
    | '\\' 'u' '{' HexadecimalDigit HexadecimalDigit HexadecimalDigit '}'
    | '\\' 'u' '{' HexadecimalDigit HexadecimalDigit HexadecimalDigit HexadecimalDigit '}'
    | '\\' 'u' '{' HexadecimalDigit HexadecimalDigit HexadecimalDigit HexadecimalDigit HexadecimalDigit '}'
    | '\\' 'u' '{' HexadecimalDigit HexadecimalDigit HexadecimalDigit HexadecimalDigit HexadecimalDigit HexadecimalDigit '}'
    | '\\' 'u' '{' HexadecimalDigit HexadecimalDigit HexadecimalDigit HexadecimalDigit HexadecimalDigit HexadecimalDigit HexadecimalDigit '}'
    | '\\' 'u' '{' HexadecimalDigit HexadecimalDigit HexadecimalDigit HexadecimalDigit HexadecimalDigit HexadecimalDigit HexadecimalDigit HexadecimalDigit '}'
    ;

fragment EscapedIdentifier
    : '\\' ('t' | 'b' | 'r' | 'n' | '\'' | '"' | '\\' | 'f' | 'v' | '0' | '$')
    ;

Operators

The following table lists all operators supported by Cangjie, with higher priority operators appearing at the top. For details about each operator, see [Expressions].

Comments

Cangjie supports the following comment formats:

A single-line comment starts with //. The syntax is as follows:

LineComment
    : '//' ~[\n\r]*
    ;

A multi-line comment is enclosed with /* and */ and supports nesting. The syntax is as follows:

DelimitedComment
    : '/*' ( DelimitedComment | . )*? '*/'
    ;

Types

The Cangjie programming language is a statically-typed language. Most type checks that ensure program security occur during compilation. In addition, the Cangjie programming language is a strongly-typed language. Each expression has a type, and the type of an expression determines its value space and supported operations. Statically-typed and strongly-typed mechanisms can help programmers locate a large number of program errors caused by types during compilation.

Types in Cangjie may be classified into the immutable types and mutable types. Immutable types include the numeric (which can be an integer or a floating-point number, see [Numeric]), Rune, Bool, Unit, Nothing, String, Tuple, Range, Function, and enum. Mutable types include Array, VArray, struct, class, and interface.

The difference between the immutable type and the mutable type is that the data value of the immutable type does not change after initialization, and the data value of the mutable type can be changed after initialization.

The following describes each type, values of types, and operations supported by types.

Immutable Types

The following sequentially describes immutable types in the Cangjie programming language.

Numeric

Numeric types include integer and floating-point number types, which are respectively used to represent integers and floating-point numbers. Integer types include signed integer and unsigned integer types. Signed integer types include Int8, Int16, Int32, Int64, and IntNative, indicating signed integers whose encoding length are 8 bits, 16 bits, 32 bits, 64 bits, and platform-dependent sizes, respectively. Unsigned integer types include UInt8, UInt16, UInt32, UInt64, and UIntNative, indicating unsigned integers whose encoding length are 8 bits, 16 bits, 32 bits, 64 bits, and platform-related sizes, respectively. Floating-point number types include Float16, Float32, and Float64, indicating floating-point numbers whose encoding lengths are 16 bits, 32 bits, and 64 bits, respectively.

The lengths of IntNative and UIntNative are the same as the bit width of the current system.

The following table lists all numeric types and their ranges.

For ease of use, the Cangjie programming language specifically provides some type aliases (for details about the type aliases, refer to the type alias section below):

1. Byte is used as the type alias of UInt8. The Byte type is equivalent to the UInt8 type.
2. Int and UInt are used as the aliases of the Int64 and UInt64 types, respectively. The Int type is equivalent to the Int64 type, and the UInt type is equivalent to the UInt64 type.

let a: UInt8 = 128
let b: Byte = a // ok

let c: Int64 = 9223372036854775807
let d: Int = c // ok

let e: UInt64 = 18446744073709551615
let f: UInt = e // ok

The following describes numeric literals and operations supported by the numeric type.

Numeric Literals

Values such as 5, 24, 2.9, and 3.14 are numeric literals. Literals can only be called by their values, and cannot be changed.

The following describes integer literals and floating-point literals:

Integer literals can be expressed in four forms: binary, octal, decimal, and hexadecimal. The binary value starts with 0b (or 0B), the octal value starts with 0o (or 0O), the hexadecimal value starts with 0x (or 0X), and the decimal value has no prefix. For example, the decimal value 24 may be defined as any one of the following four forms, where the underlined _ is used as a separator to facilitate identification of a quantity of digits of the value.

0b0001_1000     // Binary.
0o30            // Octal.
24              // Decimal.
0x18            // Hexadecimal.

For the syntax definition of integer literals, see [Integer Literals].

Floating-point types comply with the IEEE 754 format. Float16 uses the half-precision format (binary16) of IEEE 754, Float32 uses the single-precision format (binary32) of IEEE 754, and Float64 uses the double-precision format (binary64) of IEEE 754. Generally, a floating-point number contains the integer part, decimal part (including the decimal point), and exponent part. It can be notated in decimal or hexadecimal format. In the decimal format, a floating-point number must contain an integer or a decimal. If there is no decimal, the floating-point literal must contain the exponent part (with e or E as the prefix and 10 as the base number). In the hexadecimal format, a floating-point number must contain an integer or a decimal (with 0x as the prefix) and the exponent part (with p or P as the prefix and 2 as the base number). Pay attention to the following special values in floating-point parameters: positive infinity (POSITIVE_INFINITY), negative infinity (NEGATIVE_INFINITY), Not a Number (NaN), positive 0 (+0.0), and negative 0 (-0.0). Infinity indicates that an operation result exceeds a representation range. For example, when two large floating-point numbers are multiplied, or a non-zero floating-point number is divided by a floating-point zero, the result is infinity, and a sign of infinity is determined by a sign of an operand, complying with the following rule: A positive and a negative make a negative, and two negatives make a positive. NaN indicates that the value is neither a real number nor an infinity. For example, the result of multiplying positive infinity by 0 is NaN. The following is an example of a floating-point literal:

3.14 		// decimal Float64 3.14.
2.4e-1 		// decimal Float64 0.24.
2e3 		// decimal Float64 2000.0.
.8 			// decimal Float64 0.8.
.123e2 		// decimal Float64 12.3.
0x1.1p0 	// hexadecimal Float64 1.0625 (decimal value).
0x1p2 		// hexadecimal Float64 4 (decimal value).
0x.2p4 		// hexadecimal Float64 2 (decimal value).

For the syntax definition of floating-point literals, see [Floating-Point Literals].

A minimum positive value of a floating-point decimal type in the Cangjie programming language is a subnormal floating-point number.

For the Float32 type, the minimum positive floating-point number is $2^{-149}$, which is about 1.4e-45. The maximum positive floating-point number is $(2 - 2^{-23}) \times 2^{127}$, which is about 3.40282e38.

For the Float64 type, the minimum positive floating-point number is $2^{-1074}$, which is about 4.9e-324. The maximum positive floating-point number is $(2 - 2^{-52}) \times 2^{1023}$, which is about 1.79769e308.

If the face value of a floating-point decimal other than $0$ is rounded to $0$ or infinity because it is too small or too large, the compiler generates an alarm.

Operators Supported by Numeric Types

Numeric types support the following operators: arithmetic operators, bitwise operators, relational operators, increment and decrement operators, unary minus operators, and (compound) assignment operators. The integer type supports all the preceding operators, and the floating-point type supports all operators except bitwise operators. Therefore, the following briefly describes these operators of the integer type. For details, see [Expressions].

Arithmetic operators include addition (+), subtraction (-), multiplication (*), division (/), modulo (%), and power (**). By default, if arithmetic operators are not overloaded (see [Operator Overloading] for details about how to overload operators), the two operands of arithmetic operators must be of the same type. To operate two operands of different types, forcibly convert the type first. For details about the priority and binding of arithmetic operators, see [Arithmetic Expressions]. The following example describes an arithmetic operation on an integer type:

2 + 3                        // add result: 5
3 - 1                        // sub result: 2
3 * 9                        // mul result: 27
24 / 8                       // div result: 3
7 % 3                        // mod result: 1
2 ** 3                       // power result: 8
5 + 15 - 2 * 10 / 4          // result: 15
5 + 10 - 3 * 4 ** 2 / 3 % 5  // result: 14

Bitwise operators include bitwise NOT (!), left shift (<<), right shift (>>), bitwise AND (&), bitwise XOR (^), and bitwise OR (|). For details about bitwise operators, see [Bitwise Operation Expressions]. The following example describes a bit operation on an integer type:

!10         // bitwise logical NOT operator: -11
10 << 1     // left shift operator: 10*2=20
10 >> 1     // right shift operator: 10/2=5
10 & 15     // bitwise logical AND operator: 10
10 ^ 15     // bitwise XOR operator: 5
10 | 15     // bitwise logical OR operator: 15
0b1010 & 0b1110 ^ 0b1111 | 0b0101   // result: 0b0101

Relational operators include less than (<), greater than (>), less than or equal to (<=), greater than or equal to (>=), equal to (==), and not equal to (!=). The result of a relational expression is a value of the Bool type (true or false). For details about relational operators, see [Relational Expressions]. The following example describes a relational operation on an integer type:

2 == 3  	// result: false
2 != 3  	// result: true
8 < 10  	// result: true
9 <= 9  	// result: true
24 > 28  	// result: false
24 >= 23  	// result: true

Increment and decrement operators include increment (++) and decrement (--), which can be considered as special assignment operators (see below) to increase or decrease the value of a variable by 1. Increment and decrement operators can be used only as a suffix operator and can be used only for mutable variables of the integer type, because the values of immutable variables and integer literals cannot be modified. For details about the increment and decrement operators, see [Increment and Decrement Expressions]. The following example describes an increment or decrement operation on an integer type:

main() {
    var i: Int32 = 5
    var j: Int32 = 6
    i++ // i=6
    j-- // j=5   
    return 0
}

A unary minus operator is represented by -, and the result is the negative of its operand. For details about -, see the description of [Arithmetic Expressions]. The following example describes a unary minus operation on an integer type:

var i: Int32 = 5
var j: Int64 = 100 
var k: Int32 = -i   // k = -5
var l: Int64 = -j   // l = -100 

(Compound) assignment operators include assignment (=) and compound assignment (op=). op can be any binary operator among arithmetic operators, logical operators, and bitwise operators. The (compound) assignment operation can assign a value of an expression of the numeric type to a variable of the numeric type. For details about (compound) assignment operators, see [Assignment Expressions]. The following example describes a (compound) assignment on an integer type:

main() {
    var x: Int64 = 5
    var y: Int64 = 10
    x = y 	// assignment: x = 10
    x += y 	// compound assignment: x = 20
    x -= y 	// x = 10
    x *= y 	// x = 100
    x /= y 	// x = 10
    x %= y 	// x = 0
    x = 5 	// x = 5
    x **= 2 // x = 25
    x <<= 1 // x = 50
    x >>= 2 // x = 12
    x &= y 	// x = 8
    x ^= y 	// x = 2
    x |= y 	// x = 10
    return 0
}

Operators Supported by Floating-Point Numbers

Floating-point types support the following operations (except bit operations): arithmetic operations, relational operations, increment and decrement operations, unary positive (negative) operations, conditional operations, and (composite) assignment operations. The calculation of floating-point numbers may use operations with different precisions from their own types. Note the following special cases in floating-point operations: In a relational expression, if the value of an operand is NaN, the result of the expression is false, except that the results of NaN != x and x != NaN are true (x can be any floating-point number including NaN).

let x = NaN
var y = 3.14
var z = x < y  // z = false
var v = x != x // v = true
var w = (x < y) == !(x >= y) // w = false

In arithmetic expressions, values containing NaN or infinite expressions comply with the IEEE 754 standard.

Rune

The Cangjie programming language uses the Rune type to represent Unicode code point. These values can be classified into printable characters, non-printable characters (characters that cannot be displayed, such as control characters), and special characters (such as single quotation marks and backslashes).

• Rune literals

  For the syntax definition of Rune literals, see [Rune Literals].

A Rune literal consists of a pair of single quotation marks and characters, for example:

    'S'
    '5'
    ' ' // blank

Non-printable and special character literals are defined using escape characters (\):

• Operations supported by the Rune type

  The Rune type supports only relational operators (compared based on the Unicode code point).

  main() {
      'A'=='A' 	// result: true
      'A'!='A' 	// result: false
      'A'<'a' 	// result: true
      'A'<='A' 	// result: true
      'A'>'a' 	// result: false
      'A'>='A' 	// result: true
      return 0
  }
  

Boolean

The Cangjie programming language uses Bool to indicate the Boolean type.

• Bool literal

  The Bool type has only two literals: true and false.

  let bool1: Bool = true
  let bool2: Bool = false
  

• Operations supported by the Bool type

  The Cangjie programming language does not support type conversion between the numeric type and Bool. Non-Bool values cannot be used as Bool values. Otherwise, a compilation error is reported. The Bool type supports the following operations: assignment, partial compound assignment (&&= and ||=), partial relation (== and !=), and all logical operations (!, &&, and ||). The following is an example:

  main() {
      let bool1: Bool = true
      var bool2: Bool = false
      bool2 = true    // assignment
      bool2 &&= bool1 // bool2=true
      bool2 ||= bool1 // bool2=true
      true == false   // return false
      true != false   // return true
      !false          // logical NOT, return true
      true && false   // logical AND, return false
      false || false  // logical OR, return false
      return 0
  }
  

Unit

The Unit type has only one value: ().

Nothing

Nothing is a special type that does not contain any value, and Nothing is a subtype of all types. Nothing indicates dead code. For example, if a variable is of the Nothing type, it will never be used, and no memory needs to be created for it. If a parameter of a function call is of the Nothing type, the subsequent parameters will not be evaluated, and the function call itself will not be executed. If an expression in a block is of the Nothing type, all expressions and declarations following the expression will not be executed. The Cangjie compiler generates a compilation alarm for the detected dead code.

For details about which expressions have the Nothing type, see [Control Transfer Expressions].

String

The Cangjie programming language uses String to indicate the string type, which is used to express text data and consists of a string of Unicode characters.

String Literals

String literals are classified into three types: single-line string literals, multi-line string literals, and multi-line original string literals.

For details about the syntax definition of string literals, see [String Type Literals].

Single-line string literals are defined using a pair of double quotation marks (for example, "singleLineStringLiteral"). The content in the double quotation marks can be any number of characters (except non-escaped double quotation marks and a separate \). A single-line string literal can be written in only one line.

let s1 = "" 	// empty string
let s2: String = "Hello Cangjie Lang" 		// define string s2 
var s3 = "\"Hello Cangjie Lang\"" 			// define string s3 containing character "
var s4: String = "Hello Cangjie Lang\n"	// define string s4 containing character \n
// illegal string with character \
let s5 = "hello\"
// illegal string with character "
let s6 = "Hello "Cangjie Lang"

A multi-line string literal starts and ends with three double quotation marks ("""). A new line is required after the double quotation marks at the beginning. Otherwise, an error is reported. The literal starts from the first line after the double quotation marks at the beginning and ends with the first three non-escaped double quotation marks. The content between the literals can be any number of valid characters (except the three non-escaped double quotation marks """ and the separate \). Before the current file ends, if the three non-escaped double quotation marks are not encountered, a compilation error is reported. Unlike single-line string literals, multi-line string literals can span multiple lines.

// empty multi-line string
let s1 = """
"""

// Error: there must be a line terminator after the beginning double quotations. 
let errorStr = """abc
""" 

/*
The result of s2 is:
This
    is a multi-line string
*/
let s2 = """
This
    is a multi-line string"""
    
/*
The result of s3 is:
    This
  is a multi-line string
*/
let s3 = """
    This
  is a multi-line string"""
  
/*
The result of s4 is:
This
  is a 
multi-line string
*/
let s4 = """
This
    is a 
multi-line string
"""

/*
The result of s5 is:
This is a 

    multi-line string
*/
let s5 = """
This is a\n
    multi-line string
"""

Multi-line original string literal starts with one or more comment tags (#) and a double quotation mark ("), and ends with a double quotation mark (") and the number of comment tags (#) at the beginning. Note that the matching ends when the string literal value encounters the first matched double quotation mark (") and the number of comment tags (#) at the beginning. The content between the start and end double quotation marks (") can be any number of valid characters (except a double quotation mark and the same number of comment tags (#) at the beginning). Before the current file ends, if no matching quotation mark and the same number of comment tags are encountered, a compilation error is reported. Unlike (common) multi-line string literals, the content in the original multi-line string literal remains unchanged (escape characters are not escaped).

// empty multi-line raw string
let empty1 = #""#
// empty multi-line raw string
let empty2 = ##""##
 
/*
The result of s2 is:

    This
  is a multi-line string
*/
let s2 = ##"
    This
  is a multi-line raw string"##

/*
The result of s3 is:
This is a\n 
    multi-line string
*/
let s3 = #"This is a\n
    multi-line string"#

/*
The result of s4 is:
 This is a "#
*/ 
let s4 = ##" This is a "#
"##

// Error: the beginning and ending numbers of `#` are not matched.
let errorStr1 = ##" error string "#

// Error: the beginning and ending numbers of `#` are not matched.
let errorStr2 = ##" error string "###

// Error: the string literal is terminated when meeting the first matched `"##`.
let errorStr3 = ##" error string "## error "##

The String type can be determined to equality using == (inequality using !=). Two character strings are the same only when their corresponding code point sequences are the same.

Interpolated String

An interpolated string is a string literal that contains one or more interpolation expressions (not applicable to multi-line raw string literals). When an interpolation string is parsed into a result string, the position of each interpolation expression is replaced with the result of the corresponding expression.

Each interpolation expression must be enclosed in {} parentheses and prefixed with $. The expression and declaration sequence in braces can be the same as that in [Block], but cannot be empty. Interpolation expressions in multi-line strings support line breaks.

let obj = "apples"
let count = 10
let interps1 = "There are ${count * count} ${obj}."
// The result of "interps1" is: There are 100 apples.
let error = "Empty sequence is not allowed ${}" // Error

If the $ symbol in the character string is not followed by the { symbol, the character string is processed as a common $ symbol. If the escape character \ is added before $, no matter whether $ is followed by {, $ is not processed as an interpolation expression.

let d1 = "The $ sign."
// The result of "d1" is: The $ sign.
let d2 = "The \${v}."
// The result of "d2" is: The ${v}.

Interpolation expressions also support user-defined types as long as the types meet the ToString interface restrictions. The preceding types meet the ToString interface requirement.

Tuple

In the Cangjie programming language, a Tuple type is an immutable type formed by combining a plurality of different types, and is represented by (Type1, Type2, ..., TypeN), where N indicates a dimension of the tuple. The tuple types are described as follows:

1. Type1 to TypeN can be of any type (N must be greater than or equal to 2, that is, Tuple must be at least binary).

2. For each dimension of a tuple, for example, the Kth dimension, an instance of any TypeK subtype may be stored.

3. When Type1 to TypeN in (Type1, Type2, ..., TypeN) use == for value equality (!= for value inequality), the Tuple type supports == for value equality (!= is used for value inequality). Otherwise, the Tuple type does not support == and !=. In this case, if == and != are used, an error is reported during compilation. Two Tuple instances of the same type are equal only when all elements in the same position (index) are equal (indicating that their lengths are equal).

The syntax of the Tuple type is defined as follows:

tupleType
    : '(' type (',' type)+ ')'
    ;

Tuple Literals

A tuple literal is expressed in the format of (expr1, expr2, ..., exprN). Multiple expressions are separated by commas (,), and each expression can have a different type. The syntax of the Tuple literal is defined as follows:

tupleLiteral
    : '(' expression (',' expression)+ ')'
    ;

Example of tuple literals:

(3.14, "PIE") 
(2.4, 3.5) 		
(2, 3, 4) 		
((2, 3), 4)

Deconstructing a Tuple

A tuple can also be used to deconstruct another tuple value. Elements at different positions in a tuple are bound to different variables. The following example shows how to deconstruct the return value of a multi-return-value function:

func multiValues(a: Int32, b: Int32): (Int32, Int32) { 
    return (a + b, a - b) // The type of the return value of the function multiValues is (Int32, Int32).
}

main() {
    var (x, y) = multiValues(8,24) // Define an anonymous tuple who has two elements, i.e., x and y.
    print("${x}") // output: 32
    print("${y}") // output: -16
    return 0
}

Access Through a Tuple Index

A tuple allows you to access an element in a specific position using tupleName[index]. (index starts from 0 and can only be a literal of the Int64 type.)

main() {
    var z = multiValues(8, 24) // the type of z is inferred to be (Int32, Int32)
    print("${z[0]}") // output: 32
    print("${z[1]}") // output: -16
    return 0
}

Defining a Variable of the Tuple Type

When defining a variable of the tuple type, you can omit the type annotation. The compiler infers the specific type based on the program context.

let tuplePIE = (3.14, "PIE")     // The type of tuplePIE is inferred to be (Float64, String).
var pointOne = (2.4, 3.5) 		// The type of pointOne is inferred to be (Float64, Float64).
var pointTwo = (2, 3, 4) 		// The type of pointTwo is inferred to be (Int64, Int64, Int64).
var pointThree = ((2, 3), 4) 	// The type of pointThree is inferred to be ((Int64, Int64), Int64).

Range

The Cangjie programming language uses Range<T> to indicate the Range type, and requires that T can be instantiated only to implement the Comparable interface and Countable interface types. The Range type is used to represent a sequence with a fixed step and is an immutable type.

Each Range<T> instance contains the following values: start, end, and step. start and end indicate a start value and an end value of the sequence, respectively. step indicates a difference between two adjacent elements in the sequence.

The Range type can be determined to equality using == (inequality using !=). Two Range instances of the same type are the same only when they are both left-closed and right-open or left-closed and right-closed, the values of start, end, and step are the same.

Creating a Range Instance

There are two Range operators: .. and ..=, which are used to create left-closed and right-open Range instances and left-closed and right-closed Range instances, respectively. They are used in start..end:step and start..=end:step, in which start, end, and step are expressions. The two expressions are described as follows:

1. The types of start and end must be the same, and the type of step must be Int64.

2. In the expression start..end:step, when step > 0 and start >= end or step < 0 and start <= end, start..end:step returns an empty Range instance (an empty sequence that does not contain any element). If the result of start..end:step is a non-empty Range instance, the number of elements in the Range instance is equal to the round-up value of (end-start)/step (that is, greater than or equal to the minimum integer of (end-start)/step).

3. In the expression start..=end:step, when step > 0 and start > end or step < 0 and start < end, start..=end:step returns an empty Range instance. If the result of start..=end:step is a non-empty Range instance, the number of elements in the Range instance is equal to the round-down value of ((end-start)/step)+1 (that is, less than or equal to the maximum integer of ((end-start)/step)+1).

let range1 = 0..10:1 	// Define a half-open range [0,10) (with step = 1) which contains 0, 1, 2, 3, 4, 5, 6, 7, 8 and 9.
let range2 = 0..=10:2 	// Define a closed range [0,10] (with step = 2) which contains 0, 2, 4, 6, 8 and 10.
let range3 = 10..0:-2 	// Define a half-open range [10,0) (with step = -2) which contains 10, 8, 6, 4 and 2.
let range4 = 10..=0:-1 	// Define a closed range [10,0] (with step = -1) which contains 10, 9, 8, 7, 6, 5, 4, 3, 2, 1 and 0.
let range5 = 10..0:1 	// Define an empty range.
let range6 = 0..0:1 	// Define an empty range.
let range7 = 0..=0:1    // Define a closed range [0,0] (with step = 1) which only contains 0.
let range8 = 0..=10:-1 	// Define an empty range.

4. In the start..end:step and start..=end:step expressions, the value of step cannot be 0.

let range9 = 0..10: 0 				// error: the value of the step should not be zero.
let range10 = 0..=10: 0 			// error: the value of the step should not be zero.

5. When the Range<Int64> instance is used in the index operator [], start or end can be omitted. In other scenarios, start and end are required, and only step is optional (step=1 is used by default).

let range11 = 1..10 		 // Define a half-open range [1, 10) with step = 1.
let range12 = 1..=10 		 // Define a closed range [1, 10] with step = 1.	
let range13 = ..10 		     // error: the start value is required.
let range14 = 1.. 		     // error: the end value is required.
let range15 = .. 		     // error: the start and end value are required.

Using a Range Type

Expressions of the Range type are mainly used in for-in expressions (see [Loop Expressions]) and are used as indexes to truncate segments. Note that:

• When an instance of the Range<Int64> type is used in the index operator [], both start and end are optional. Their values are determined by the context. If the index operator [] is overloaded on a custom type and the parameter type is Range<Int64>, the value of start is 0 when start is omitted, and the value of end is equal to the maximum value of Int64 when end is omitted.

Defining a Variable of the Range Type

When defining a variable of the Range<T> type, you can explicitly add a type annotation or omit the type annotation (in this case, the compiler infers the type annotation based on the program context).

let range16: Range<Int64> = 0..10 		// Define a half-open range [0,10) with step = 1
let range17: Range<Int64> = -10..10:2 	// Define a half-open range [-10,10) with step = 2
let range18 = 0..=10 		            // Define a closed range [0,10] with step = 1
let range19 = -10..=10:2 	            // Define a closed range [-10,10] with step = 2

Function

A function type represents a type of a specific function, and is immutable. The syntax of the function type is defined as follows:

arrowType 
    : parameterTypes '->' type
    ;
parameterTypes
    : '(' (type (',' type)*)? ')'
    ;

parameterTypes (parameter type list) and type (return type) are connected using ->. A pair of () in the parameter type list is required. () can contain zero or more types (multiple types are separated by ,).

() -> Int32 	// A function type has an empty parameter type list, and its return value type is 'Int32'.
() -> Unit 		// A function type has an empty parameter type list, and its return value type is 'Unit'.
(Float32) -> Int32 	// A function type has one parameter whose type is 'Float32', and its return value type is 'Int32'
(Int32, Int32, Float32) -> Int32 // A function type has three parameters, and its return value type is 'Int32'
(Int32, Int32, Float32) -> (Int32, Int32) // A function type has three parameters, and its return value type is '(Int32, Int32)'	
(Int32, Int32, Float32) -> Unit // A function type has three parameters, and its return value type is 'Unit'.		

In the Cangjie programming language, a function is a first-class citizen, which indicates that the function can be used as a parameter of another function, can be used as a return value of another function, or can be directly assigned to a variable.

The function type does not support == or != for equality or inequality, respectively. For more information about functions, see [Functions].

Enum

The enum type is an immutable type used to organize a set of related values (which are called constructor). A value of the enum type can be obtained only from a constructor defined in the enum type at any time.

Defining the Enum Type

The syntax for defining the enum type is as follows:

enumDefinition
    : enumModifier? 'enum' identifier typeParameters? ('<:' superInterfaces)? genericConstraints? '{' enumBody '}'
    ;
    
enumBody
    : '|'? caseBody ('|' caseBody)* (functionDefinition | operatorFunctionDefinition | propertyDefinition | macroExpression)*
    ;
    
caseBody
    : identifier ('(' type (',' type)* ')')?
    ;

enumModifier is the modifier (that is, public) of the enum type, enum is the keyword, identifier is the name of the enum type, and typeParameters and genericConstraints are the type variable list and type variable constraints, respectively. For details, see [Generics]. Multiple values of caseBody (constructors) can be defined in enumBody. Each constructor can have no parameter or a group of parameters of different types. Multiple constructors are separated by |. Before the first constructor, | can exist, which is optional. You can define other members of the enum after caseBody, including member functions, operator overloading functions, and member attributes.

The following is an example of the enum type:

/*
Define an enum type 'TimeUnit1' who has four constructors: 'Year', 'Month', 'Day' and 'Hour'.
*/
enum TimeUnit1 {
    Year | Month | Day | Hour
}

/* 
'TimeUnit2' has four constructors: 'Year(Int32)', 'Month(Int32, Float32)', 'Day(Int32, Float32, Float32)' and 'Hour(Int32, Float32, Float32, Float32)'.
*/
enum TimeUnit2 { 
    | Year(Float32)
    | Month(Float32, Float32)
    | Day(Float32, Float32, Float32)
    | Hour(Float32, Float32, Float32, Float32) 
}

/* 
Define a generic enum type 'TimeUnit3<T1, T2>' who has four constructors: 'Year(T1)', 'Month(T1, T2)', 'Day(T1, T2, T2)' and 'Hour(T1, T2, T2, T2)'.
*/
enum TimeUnit3<T1, T2> { 
    | Year(T1)
    | Month(T1, T2)
    | Day(T1, T2, T2)
    | Hour(T1, T2, T2, T2) 
}

Pay attention to the following points about the enum type:

1. The enum type can be defined only in top-level.

2. The constructor definition without parentheses or parameters is not supported. The type of the constructor without parameters is the defined enum type and is not considered as the function type. A constructor with parameters has a function type, but cannot be used as a first-class citizen. For example:

enum E {
    | mkE // OK. The type of mkE is E but not () -> E.
    | mkE() // Syntax error.
}

enum E1 {
    | A
}
let a = A // ok, a: E1

enum E2 {
    | B(Bool)
}
let b = B // error

enum E3 {
    | C
    | C(Bool)
}
let c = C // ok, c: E3

3. As a user-defined type, the enum type does not support == for equality or != for inequality by default. You can overload the == or != operator (see [Operator Overloading]) to enable the custom enum type to support == or !=.

4. The same enum supports constructor overloading, but only the number of parameters is involved in overloading. That is, multiple constructors with the same name can be defined in the same enum, but the number of parameters must be different. (A constructor without parameters can be overloaded with other constructors although it is not a function type.) For example:

enum TimeUnit4 { 
    | Year
    | Year(Int32) 		                     // ok
    | Year(Float32) 	                     // error: redeclaration of 'Year'
    | Month(Int32, Float32)                  // ok
    | Month(Int32, Int32) 	                 // error: redeclaration of 'Month'
    | Month(Int32) 			                 // ok
    | Day(Int32, Float32, Float32)           // ok
    | Day(Float32, Float32, Float32) 	     // error: redeclaration of 'Day'
    | Day(Float32, Float32) 			     // ok
    | Hour(Int32, Float32, Float32, Float32) // ok
    | Hour(Int32, Int32, Int32, Int32) 	     // error: redeclaration of 'Hour'
    | Hour(Int32, Int32, Int32) 		     // ok
}

5. The enum type supports recursion and mutual recursion. For example:

// recursive enum
enum TimeUnit5 { 
    | Year(Int32)
    | Month(Int32, Float32)
    | Day(Int32, Float32, Float32)
    | Hour(Int32, Float32, Float32, Float32)
    | Twounit(TimeUnit5, TimeUnit5) 
}

// mutually recursive enums
enum E1 {
    A | B(E2)
}
enum E2 {
    C(E1) | D(E1)
}

6. The enum type cannot be inherited.

7. The enum type can implement interfaces. For details about the interfaces, see [Classes and Interfaces].

Accessing the Enum Value

The first method is to add the enum name to the constructor name. For example:

let time1 = TimeUnit1.Year
let time2 = TimeUnit2.Month(1.0, 2.0)
let time3 = TimeUnit3<Int64, Float64>.Day(1, 2.0, 3.0)

The second method is to omit the enum name. For example:

let time4 = Year                             // syntax sugar of 'TimeUnit1.Year'
let time5 = Month(1.0, 2.0)                  // syntax sugar of 'TimeUnit2.Month(1.0, 2.0)'
let time6 = Day<Int64, Float64>(1, 2.0, 3.0) // syntax sugar of 'TimeUnit3<Int64, Float64>.Day(1, 2.0, 3.0)'

Note: The Cangjie language supports type derivation of generic parameters. Therefore, the generic parameter <T> can be omitted when the preceding method 1 and method 2 are used for access.

The second method must meet the following rules:

If there is no conflict with other variable names, function names, type names, or package names, you can omit the type prefix. Otherwise, the variable name, function name, type name, or package name is preferred.

package p
}

func g() {
    let a = A // ok, find p.A
    let b = E.A // ok
    let c = p.A // ok
    F(1) // ok, find p.F
    E.F(1) // ok
    p.F(1) // ok
    let x: C // ok, find p.C
    let y: p.C // ok
}

When the enum constructor is used without the type prefix, the generic parameters of the enum type can be declared after the constructor name.

enum E<T> {
    | A(T)
    | B(T)
}

func f() {
    let a = A(1)        // ok, a: E<Int64>
    let b = A<Int32>(2) // ok, b: E<Int32>
}

Deconstructing Enums

The match expression and enum pattern can be used to deconstruct the enum type. For details, see [Patterns].

The following is an example of deconstructing the TimeUnit1 and TimeUnit2 defined in the preceding section:

let time12 = TimeUnit1.Year
let howManyHours = match (time12) {
    case Year => 365 * 24 // matched
    case Month => 30 * 24
    case Day => 24
    case Hour => 1
}

let time13 = TimeUnit2.Month(1.0, 1.5)
let howManyHours = match (time13) {
    case Year(y) => y * 365.0 * 24.0
    case Month(y, m) => y * 365.0 * 24.0 + m * 30.0 * 24.0 // matched
    case Day(y, m, d) => y * 365.0 * 24.0 + m * 30.0 * 24.0 + d * 24.0
    case Hour(y, m, d, h) => y * 365.0 * 24.0 + m * 30.0 * 24.0 + d * 24.0 + h
}

Other Members of Enum

You can define member functions, operator functions, and member attributes in the enum type.

• For details about how to define a common member function, see [Function Definition].
• For details about the syntax for defining an operator function, see [Operator Overloading].
• For details about the syntax for defining member attributes, see [Attribute Definition].

The following are some simple examples of enum definitions:

enum Foo {
    A | B | C
    func f1() {
        f2(this)
    }
    static func f2(v: Foo) {
        match (v) {
            case A => 0
            case B => 1
            case C => 2
        }
    }
    prop item: Int64 {
        get() {
            f1()
        }
    }
}

main() {
    let a = Foo.A
    a.f1()
    Foo.f2(a)
    a.item
}

A constructor in the enum type, a static member function, and an instance member function cannot be overloaded. Therefore, the names of constructors in the enum type, static member functions, instance member functions, and member attributes must be unique.

Option

Option type is a generic enum type.

enum Option<T> { Some(T) | None }

Some and None are two constructors. Some(T) indicates a state with a value, and None indicates a state without a value. The type variable T is instantiated into different types, and different Option types, for example, Option<Int32> and Option<String>, are obtained.

Another method of writing the Option type is to add ? before the type name. That is, for any Type, ?Type is equivalent to Option<Type>. For example, ?Int32 is equivalent to Option<Int32>, ?String is equivalent to Option<String>, and so on.

Pay attention to the following points about the Option type:

1. Although T and Option<T> are of different types, you can directly specify a value of the T type when a value of the Option<T> type is required at a certain position. The compiler encapsulates the value of the T type into Some constructor of the Option<T> type. For example, the following definition is valid:

let v1: ?Int64 = 100
let v2: ??Int64 = 100

2. For two unequal types T1 and T2, even if there is a subtype relationship between them, there is no subtype relationship between Option<T1> and Option<T2>.

The Option type complies with the usage rules of the generic enum type. For example, you can define a series of variables of different Option types.

let opInt32_1 = Some(100)           // The type of 'opInt32_1' is 'Option<Int32>'
let opInt32_2 = Option<Int32>.None  // The type of 'opInt32_2' is 'Option<Int32>'
let opChar = Some('m')              // The type of 'opChar' is 'Option<Rune>'
let opBool = Option<Bool>.None      // The type of 'opBool' is 'Option<Bool>'
let opEnum = Some(TimeUnit1.Year)   // The type of 'opEnum' is 'Option<TimeUnit1>'

Deconstructing Option Values

Several methods are provided to facilitate the deconstruction of option values: pattern matching, getOrThrow function, coalescing operator (??), and question mark operator (?).

1. The Option type is an enum type. Therefore, the enum pattern in the pattern matching expression can be used to deconstruct the Option value. For details, see [Enum Pattern].

let number1 = match (opInt32_1) {
    case Some(num) => num // matched
    case None => 0
}

let number2 = match (opInt32_2) {
    case Some(num) => num 
    case None => 0        // matched
}

let enumValue = match (opEnum) {
    case Some(tu) => match (tu) {
                          case Year => "Year"   // matched
                          case Month => "Month"
                          case Day => "Day"
                          case Hour => "Hour"
                      }
    case None => "None"
}

2. For the expression e of the Option<T> type, the getOrThrow() or getOrThrow(exception: ()->Exception) function is called to deconstruct e. If the value of e is equal to that of Option<T>.Some(v), the value of e.getOrThrow() or e.getOrThrow(lambdaArg) is equal to that of v. If the value of e is equal to that of Option<T>.None, e.getOrThrow() throws a NoneValueException exception during running (e.getOrThrow(lambdaArg) throws an exception specified in lambdaArg during running).

let number1 = opInt32_1.getOrThrow()                 // number1 = 100
let number2 = opInt32_2.getOrThrow()                 // throw NoneValueException
let number3 = opInt32_2.getOrThrow{ MyException("Get None value") } // throw MyException

3. For the e1 expression of the Option<T> type and the e2 expression of the T type, the type of the e1 ?? e2 expression is T. When the value of e1 is equal to that of Option<T>.Some(v), the value of e1 ?? e2 is equal to that of v. When the value of e1 is equal to that of Option<T>.None, the value of e1 ?? e2 is equal to that of e2. About ?? For details about operators, see [coalescing Expressions].

let number1 = opInt32_1 ?? 0  // number1 = 100
let number2 = opInt32_2 ?? 0  // number2 = 0

4. The question mark operator (?) is a unary suffix operator.? It must be used together with the suffix operators ., (), {}, or [] so that Option<T> supports these suffix operators. For an expression e of the Option type, e?.b indicates that Option<T>.Some(b) is obtained when e is Some; otherwise, Option<T>.None is obtained (T is of the b type). The same rule applies to other operators. About ? For details about operators, see [Question Mark Operators].

class C {
    var item = 100
}
let c = C()
let c1 = Some(c)
let c2 = Option<C>.None
let r1 = c1?.item   // r1 = Option<Int64>.Some(100)
let r2 = c2?.item   // r2 = Option<Int64>.None

Mutable Types

The following sequentially describes mutable types in the Cangjie programming language.

Array

The Cangjie programming language uses the generic type Array<T> to represent the Array type. The Array type is used to store a series of elements of the same type (or having a common parent class). The description of Array<T> is as follows:

1. The elements in Array<T> are ordered and can be accessed by index (starting from 0).

2. The length of the Array type is fixed. That is, once an Array instance is created, the length cannot be changed.

3. Array is a reference type and is defined as a variable of the reference type. The variable name stores the reference pointing to the data value. Therefore, when a value is assigned or a function specifies parameters, the Array type copies the reference.

4. When the type variable T is instantiated into different types, different Array types are obtained. For example, Array<Int32> and Array<Float64> indicate Array of the Int32 type and Array of the Float64 type, respectively.

5. When Type in Array<T> supports == for equality and != for inequality, Array<T> supports == and !=. Otherwise, Array<T> does not support == and !=. If == and != are used, an error is reported during compilation. Two instance values for Array<T> of the same type are equal only when all elements in the same position (index) are equal (indicating that their lengths are equal).

6. A multidimensional Array is defined as an Array of an Array and is represented by Array<Array<...>>. For example, Array<Array<Int32>> indicates a two-dimensional Array of the Int32 type.

7. When ElementType has subtypes, Array<ElementType> can store instances of any ElementType subtype. For example, Array<Object> can store instances of any Object subtype.

Creating an Array Instance

You can create an Array instance in either of the following ways.

Constructors

// Array<T>()
let emptyArr1 = Array<Int64>()  // create an empty array whose type is Array<Int64>
let emptyArr2 = Array<String>() // create an empty array whose type is Array<String>

// Array<T>(size: Int64, initElement: (Int64)->T)
let array3 = Array<Int64>(3) { i => i * 2 } // 'array3' has 3 elements: 0, 2, 4
let array4 = Array<String>(2) { i => "$i" } // 'array4' has 2 elements: "0", "1" 

Array Literals

Array literals are in the format of [element1, element2, ..., elementN]. Multiple elements are separated by commas (,). Each element can be a common expression expressionElement. The syntax of an array literal is defined as follows:

arrayLiteral : '[' (elements)? ']' ;
elements    : element (',' element)* ;
element     : expression ;

Each element of the Array literal is an expression.

let emptyArray: Array<Int64> = []    // empty Array<Int64>
let array0 = [1, 2, 3, 3, 2, 1]      // array0 = [1, 2, 3, 3, 2, 1]
let array1 = [1 + 3, 2 + 3, 3 + 3]   // array1 = [4, 5, 6]

• When the context does not have specific type requirements, if the minimum common parent type of all elements is T, the type of the Array literal is Array<T>.
• If the context has specific type requirements, all element types must be subtypes of the element type required by the context.

Accessing Elements in an Array

For the arr instance of the Array type, elements in arr can be accessed in the following ways:

Element accessing at a specific position: Access an element at a specific position using arr[index1]...[indexN] (index1, ..., indexN are index expressions of the Int64 type). For example:

let array5 = [0, 1]
let element0 = array5[0]      // element0 = 0
array5[1] = 10                // change the value of the second element of 'array5' through index

let array6 = [[0.1, 0.2], [0.3, 0.4]]
let element01 = array6[0][1]  // element01 = 0.2
array6[1][1] = 4.0            // change the value of the last element of 'array6' through index

Iterative accessing: Iteratively access elements in arr using the for-in expression (see [for-in Expressions]). For example:

func access() {
    let array8 = [1, 8, 0, 1, 0]
    for (num in array8) {
        print("${num}")   // output: 18010
    }
}

Size of the Accessed Array

The number of elements in arr can be returned in arr.size mode.

let array9 = [0, 1, 2, 3, 4, 5]
let array10 = [[0, 1, 2], [3, 4, 5]]
let size1 = array9.size  // size1 = 6
let size2 = array10.size // size2 = 2

Slice of an Array

When a value of the Range<Int64> type is used as the Array index, a segment (called slicing) of the Array is truncated. Note that:

• The value of step must be 1. Otherwise, an exception will be thrown.
• The type returned by slicing is the same as that of Array and is the reference of the original Array. Modifications on elements in a slice affect the original array.
• When start..end is used as the index of Array, if start is omitted, the value of start is set to 0. If end is omitted, the value of end is set to the length of Array.
• When start..=end is used as the index of Array, if start is omitted, the value of start is set to 0. end in the start..=end format cannot be omitted.
• If the index is an empty range, an empty Array is returned.

let array7 = [0, 1, 2, 3, 4, 5]

func slicingTest() {
    array7[0..5]      // [0, 1, 2, 3, 4]
    array7[0..5:1]    // [0, 1, 2, 3, 4]
    array7[0..5:2]    // runtime exception
    array7[5..0:-1]   // runtime exception
    array7[5..0:-2]   // runtime exception
    array7[0..=5]     // [0, 1, 2, 3, 4, 5]
    array7[0..=5:1]   // [0, 1, 2, 3, 4, 5]
    array7[0..=5:2]   // runtime exception
    array7[5..=0:-1]  // runtime exception
    array7[5..=0:-2]  // runtime exception
    array7[..4]       // [0, 1, 2, 3]
    array7[2..]       // [2, 3, 4, 5]
    array7[..]        // [0, 1, 2, 3, 4, 5]
    array7[..4:2]     // error: the 'range step' is not allowed here.
    array7[2..:-2]    // error: the 'range step' is not allowed here.
    array7[..:-1]     // error: the 'range step' is not allowed here.

    array7[..=4]      // [0, 1, 2, 3, 4]
    array7[..=4:2]    // error: the 'range step' is not allowed here.

    array7[0..5:-1]   // runtime exception 
    array7[5..=0]     // [] 
    array7[..0]       // [] 
    array7[..=-1]     // []
    let temp: Array<Int64> = array7[..]
    temp[0] = 6 // temp == array7 == [6, 1, 2, 3, 4, 5]
}

When slicing is used to assign values, the following usages are supported:

• If the expression on the right of = is of the array element type, the value of the expression is used as the element that covers the slice range.
• If the type of the expression on the right of = is the same as that of the array, the array will be copied to overwrite the current slice range. In this case, the size of the expression on the right must be the same as that of the slice range. Otherwise, an exception will be thrown during running.

let arr = [1, 2, 3, 4, 5]
arr[..] = 0
// arr = [0, 0, 0, 0, 0]
arr[0..2] = 1
// arr = [1, 1, 0, 0, 0]
arr[0..2] = [2, 2]
// arr = [2, 2, 0, 0, 0]
arr[0..2] = [3, 3, 3] // runtime exception
arr[0..2] = [4] // runtime exception

let arr2 = [1, 2, 3, 4, 5]
arr[0..2] = arr2[0..2] // ok
// arr = [1, 2, 0, 0, 0]
arr[0..2] = arr2 // runtime exception
arr[..] = arr2

VArray

The Cangjie programming language uses the generic type VArray<T, $N> to represent the VArray type. The VArray type is used to store a series of elements of the same type (or having a common parent class). The description of VArray<T, $N> is as follows:

1. The elements in VArray<T, $N> are ordered and can be accessed by index (starting from 0). If the provided index is greater than or equal to its length and the index can be deduced during compilation, a compilation error is reported. Otherwise, an exception is thrown during running.

2. The length of the VArray<T, $N> type is a part of the type. N indicates the length of VArray. It must be an integer literal and is marked by the fixed syntax $ plus a number. If the provided integer literal is a negative number, an error is reported during compilation.

3. VArray is a variable of the value type. The variable name stores the data value. Therefore, when a value is assigned or a function specifies parameters, the value is copied for the VArray type.

4. When the type variable T is instantiated into different types or the length of the $N annotation is different, different VArray types are obtained. For example, VArray<Int32, $5> and VArray<Float64, $5> are different types of VArray. VArray<Int32, $2> and VArray<Int32, $3> are different types of VArray.

5. When the generic variable T of VArray is of the VArray type, it indicates a multi-dimensional VArray type.

Creating a VArray Instance

VArray can also use the Array literal to create an instance. This method can be used only when the literal is of the VArray type in the context. Otherwise, the literal is of the Array type.

The length of VArray must be the literal type of Int64 and must be the same as the length of the provided literal array. Otherwise, a compilation error is reported.

let arr1: VArray<Int64, $5> = [1,2,3,4,5] 
let arr2: VArray<Int16, $0> = []
let arr3: VArray<Int16, $0> = [1] // error
let arr4: VArray<Int16, $-1> = [] // error

In addition, VArray can be used to create instances in the form of constructors.

// VArray<T, $N>(initElement: (Int64)->T)
let arr5: VArray<Int64, $5> = VArray<Int64, $5> { i => i } // [0, 1, 2, 3, 4]
// VArray<T, $N>(item!: T)
let arr6: VArray<Int64, $5> = VArray<Int64, $5>(item: 0) // [0, 0, 0, 0, 0]

VArray does not allow the default type parameter <T, $N>.

Accessing Elements in a VArray

For the arr instance of the VArray type, elements in arr can be accessed in the following ways:

Access an element at a specific position using arr[index1]...[indexN] (index1,...,indexN are index expressions of the Int64 type). For example:

Note that the index operation of VArray returns the copy of the specified element. It indicates that if the element is of the value type, the index value will get a new instance that cannot be modified. For multi-dimensional VArray types, the inner VArray cannot be modified by arr[n][m] = e because the inner VArray obtained by arr[n] is a new VArray instance that has been copied.

var arr7: VArray<Int64, $2> = [0, 1]
let element0 = arr7[0]      // element0 = 0
arr7[1] = 10                // change the value of the second element of 'arr7' through index

// Get and Set of multi-dimensional VArrays.
var arr8: VArray<VArray<Int64, $2>, $2> = [[1, 2], [3, 4]]
let arr9: VArray<Int64, $2> = [0, 1]
let element1 = arr8[1][0]   // element1 = 3
arr8[1][1] = 5              // error: function call returns immutable value
arr8[1] = arr9              // arr8 = [[1, 2], [0, 1]]

Obtaining the VArray Lengths

The number of elements in arr can be returned in arr.size mode.

let arr9: VArray<Int64, $6> = [0, 1, 2, 3, 4, 5]
let size = arr9.size  // size = 6

VArray in the Function Signature

When VArray is used as a parameter or return value of a function, the length of VArray must be specified.

func mergeVArray(a: VArray<Int64,$2>, b: VArray<Int64, $3>): VArray<Int64, $5> {
    var ret = VArray<Int64, $5>(item: 0)
    for(i in 0..2) {
        ret[i] = a[i]
    }
    for (i in 0..3) {
        ret[a.size + i] = b[i]
    }
    return ret
}

Struct

The struct type is a mutable type. A series of member variables and member functions can be defined in the struct type. The syntax for defining the struct type is as follows:

structDefinition
    : structModifier? 'struct' identifier typeParameters? ('<:' superInterfaces)? genericConstraints? structBody
    ;

structBody
    : '{'
        structMemberDeclaration*
        structPrimaryInit? 
        structMemberDeclaration*
      '}'
    ; 

structMemberDeclaration
    : structInit
    | staticInit
    | variableDeclaration
    | functionDefinition
    | operatorFunctionDefinition
    | macroExpression
    | propertyDefinition
    ;    

structModifier is the modifier of the struct type, struct is the keyword, identifier is the name of the struct type, and typeParameters and genericConstraints are the type variable list and type variable constraints, respectively. For details, see [Generics].In structBody, you can define member variables (variableDeclaration), member attributes (propertyDefinition), main constructors (structPrimaryInit), constructors (structInit), and member functions (including common member functions and operator functions).

Pay attention to the following points about the struct type:

1. struct is a variable of the value type. The variable name stores the data value. Therefore, when a value is assigned or a function specifies parameters, the value is copied for the struct type.

2. The struct type can be defined only in top-level.

3. As a user-defined type, the struct type does not support == for equality or != for inequality by default. You can overload the == or != operator (see [Operator Overloading]) to enable the custom struct type to support == or !=.

4. The struct type cannot be inherited.

5. The struct type can implement the [Interface].

6. If the type of one or more non-static member variables of a struct type references the struct itself, the struct type is called a recursive struct type. For multiple struct types, if the types of their non-static member variables form a circular reference, the struct types form a recursion. The struct type defined by recursion (or mutual recursion) is invalid unless at least one T_i is encapsulated in the class, interface, enum, or function type on each T_1, T_2, ..., T_N of the recursion chain. That is, the class, interface, enum, or function type can be used to implement recursion (or mutual recursion). The struct definition is legalized.

The following is an example of the struct type:

struct Rectangle1 { 
    let width1: Int32
    let length1: Int32
    let perimeter1: () -> Int32

    init (width1: Int32, length1: Int32) {
        this.width1 = width1
        this.length1 = length1
        this.perimeter1 = { => 2 * (width1 + length1) }
    }
    init (side: Int32) {
        this(side, side)
    }
    func area1(): Int32 { width1 * length1 }
}

// Define a generic struct type.
struct Rectangle2<T> {
    let width2: T
    let length2: T

    init (side: T) {
      this.width2 = side
      this.length2 = side
    }

    init (width2!: T, length2!: T) {
        this.width2 = width2
        this.length2 = length2
    }
}

The following is an example of the struct type definition for recursion and mutual recursion:

struct R1 { // error: 'R1' cannot have a member that recursively contains it
    let other: R1
}
struct R2 { // ok
    let other: Array<R2>
}

struct R3 { // error:  'R3' cannot have a member that recursively contains it
    let other: R4
}
struct R4 { // error:  'R4' cannot have a member that recursively contains it
    let other: R3
}

struct R5 { // ok
    let other: E1
}
enum E1 { // ok
    A(R5)
}

struct Member Variables

The syntax for defining a member variable is as follows:

variableDeclaration
    : variableModifier* NL* (LET | VAR) NL* patternsMaybeIrrefutable ((NL* COLON NL* type)? (NL* ASSIGN NL* expression) | (NL* COLON NL* type))
    ;

When defining member variables, pay attention to the following points:

1. A member variable defined outside the primary constructor can have an initial value or not. If there is an initial value, the initial value expression can reference only the initialized member variables defined before it and the static member functions in struct.

Constructors

In the Cangjie programming language, there are two types of constructors: primary constructor and init constructor (constructor for short).

Primary Constructor

The syntax of the primary constructor is defined as follows:

structPrimaryInit
    : (structNonStaticMemberModifier)? structName '('
      structPrimaryInitParamLists? ')'
 	  '{'
 	       expressionOrDeclarations?
 	  '}'
	;

structName
    : identifier
    ;

structPrimaryInitParamLists
    : unnamedParameterList  (','  namedParameterList)? 
       (',' structNamedInitParamList)?
    | unnamedParameterList (',' structUnnamedInitParamList)? 
       (',' structNamedInitParamList)?
    | structUnnamedInitParamList (',' structNamedInitParamList)?
    | namedParameterList (',' structNamedInitParamList)?
    | structNamedInitParamList
    ;

structUnnamedInitParamList
    : structUnnamedInitParam (',' structUnnamedInitParam)*
    ;

structNamedInitParamList
    : structNamedInitParam (',' structNamedInitParam)*
    ;

structUnnamedInitParam
    : structNonStaticMemberModifier?  ('let' | 'var')  identifier ':' type
    ;

structNamedInitParam
    : structNonStaticMemberModifier?   ('let' | 'var')  identifier '!' ':' type
      ('=' expression)?
    ;

The definition of the primary constructor consists of the following parts:

1. Modifier (Optional): It can be modified by all access modifiers. The default accessibility is internal. For details, see Access Modifiers in [Packages and Modules].

2. Primary constructor name: same as the type name. Do not use the func keyword before the primary constructor name.

3. Parameter list: Different from the init constructor, the primary constructor has two types of parameters: ordinary parameters and member variable parameters. The syntax and semantics of ordinary parameters are the same as those of parameters in the function definition.

Member variable parameters are introduced to reduce code redundancy. The definition of a member variable parameter includes the definition of a parameter and a member variable. In addition, it indicates the semantics of assigning a value to a member variable through a parameter. Omitted definitions and expressions are automatically generated by the compiler.

• The syntax of member variable parameters is the same as that of member variable definition. In addition, ! can be used to indicate whether a member variable parameter is a named parameter.

• The modifiers of the member variable parameter are public, private, protected, and internal. For details, see Access Modifiers in [Packages and Modules].

• Member variable parameters only support non-static member variables. That is, they cannot be modified by static.

• A member variable parameter cannot have the same name as a member variable outside the primary constructor.

• A member variable parameter can have no initial value. This is because the compiler generates a corresponding constructor for the primary constructor and assigns values to member variables in the constructor body.

• A parameter of a member variable can have an initial value. The initial value expression can reference other parameters or member variables (excluding instance member variables defined outside the primary constructor) that have been defined before the member variable is defined, but cannot modify the values of these parameters and member variables. Note that the initial value of the member variable parameter is valid only in the primary constructor and is not included in the member variable definition.

• Member variable parameters cannot be followed by ordinary parameters. In addition, the parameter sequence must comply with that defined in the function. Parameters of named variables cannot be followed by non-named parameters.

4. Main constructor body: The main constructor cannot call other constructors in this struct. Declarations and expressions can be written in the main constructor body. The declarations and expressions must meet the requirements of the init constructor.

The following is an example of the primary constructor definition:

struct Test{
    static let counter: Int64 = 3
    let name: String = "afdoaidfad"
    private Test( 
        name: String,             // regular parameter  
        annotation!: String = "nnn",   // regular parameter  
        var width!: Int64 = 1,     // member variable parameter with initial value
        private var length!: Int64,    // member variable parameter
        private var height!: Int64 = 3   // member variable parameter 
    ) {}
}

The primary constructor is the syntactic sugar of the init constructor. The compiler automatically generates the definitions of the constructor and member variables corresponding to the primary constructor. The constructor is automatically generated as follows:

• Its modifier is the same as that of the primary constructor.
• The sequence of parameters from left to right is the same as that declared in the parameter list of the primary constructor.
• The form of the constructor body is as follows:
  • Values are assigned to member variables. The syntax format is this.x = x, where x is the member variable name.
  • Then, other code of the main constructor body is used.

struct B<X,Y> { 
    B(
        x: Int64,          // primary constructor, it's name is the same as the struct
        y: X,
        v!: Int64 = 1,     // regular parameter
        private var z!: Y  // member variable parameter
    ) {}

    /* The corresponding init constructor with primary constructor auto-generated
    by compiler.
    
    private var z: Y    // auto generated member variable definition
    init( x: Int64, y: X, v!: Int64 = 1, z!: Y) { // auto generated named parameter definition
        this.z = z // auto generated assign expression of member variable
    }
    */
}

A struct can define only one primary constructor. In addition to the primary constructor, other constructors can be defined as usual, but other constructors and the constructor corresponding to the primary constructor must be overloaded.

init Constructor

In addition to the main constructor, you can also customize a constructor. The constructor is defined by using the keyword init, parameter list, and function body. Multiple constructors can be defined in a struct, but they and the constructor corresponding to the main constructor must form an overload. For details about function overload, see [Function Overload Definition]. Note:

1. The parameters of a constructor can have default values. Do not use the instance member variable this.variableName and its syntactic sugar variableName as the default values of constructor parameters.

2. Before all instance member variables are initialized, the constructor cannot use implicit parameter passing or functions or lambda that capture this. However, this.variableName or its syntactic sugar variableName can be used to access the initialized member variable variableName.

3. The lambda and nested functions in constructors cannot capture this, and this cannot be used independently as an expression.

4. In a constructor, this can be used to call other constructors. If this function is called, it must be called at the first expression in the constructor body. No expression or declaration is allowed before this function is called. Do not call expressions to call constructors through this outside the constructor.

5. If the constructor does not explicitly call other constructors, ensure that all instance member variables declared by the struct are initialized before return. Otherwise, an error is reported during compilation.

6. The compiler performs dependency analysis on the calling relationships between all constructors. If a constructor is called cyclically, an error is reported during compilation.

7. The return type of the constructor is Unit.

If a struct does not define a primary constructor or an init constructor, it attempts to generate a parameterless constructor (public-modified). If the instance member variable of the struct does not have an initial value, an error is reported during compilation.

Other Members of Struct

You can also define member functions, operator functions, member attributes, and static initializers in struct.

• For details about how to define a common member function, see [Function Definition].
• For details about the syntax for defining an operator function, see [Operator Overloading].
• For details about the syntax for defining member attributes, see [Attribute Definition].
• For details about the syntax for defining a static initializer, see [Static Initializers].

Modifiers in the Struct

A struct and its members in a class can be modified using access modifiers. For details, see Access Modifiers in [Packages and Modules].

Member functions and variables can be modified using static. These members are static members of the struct type, not members of the struct instance. Outside the struct definition, instance member variables and instance member functions can be accessed only through the struct instance, and static member variables and static member functions can be accessed only through the name of the struct type.

In addition, a function can be modified by mut, which is a special instance member function. For details about the mut function, see [mut Functions].

The struct constructor and the member variables defined in the main constructor can be modified only by using access modifiers.

Instantiation of Structs

After defining the struct type, you can create a struct instance. The struct instance can be defined in either of the following methods based on whether the instance contains type variables:

1. Define an instance of the non-general struct: StructName(arguments). StructName indicates the name of the struct type, and arguments indicates the argument list. StructName(arguments) calls the corresponding constructor based on the calling rule of overloaded functions (see [Function Overloading Resolution]), and then generates an instance of StructName. For example:

let newRectangle1_1 = Rectangle1(100, 200) // Invoke the first custom constructor.
let newRectangle1_2 = Rectangle1(300)      // Invoke the second custom constructor.

2. Define an instance of the generic struct: StructName<Type1, Type2, ..., TypeK>(labelValue1, labelValue2, ..., labelValueN). The only difference from defining an instance of a non-general struct is that the generic parameter needs to be instantiated. For example:

let newRectangle2_1 = Rectangle2<Int32>(100) // Invoke the custom constructor.
let newRectangle2_1 = Rectangle2<Int32>(width2: 10, length2: 20) // Invoke another custom constructor.

Note that if the variable structInstance of the struct type is defined using let, the value of the member variable varName cannot be changed using structInstance.varName = expr (even if varName is defined using var). If both structInstance and varName are defined using var, the value of varName can be changed using structInstance.varName = expr.

Class and Interface Types

class and interface are reference types and are defined as variables of the reference type. The variable name stores the reference pointing to the data value. Therefore, when a value is assigned or a function specifies parameters, class and interface copy the reference.

For details, see [Classes and Interfaces].

Type Conversion

As a strongly-typed language, the Cangjie programming language supports only explicit type conversion (also referred to as forcible type conversion). For the value type, valueType(expr) can be used to convert the type of the expression expr to valueType. For class and interface, [as Operators]) can be used to implement static type conversion. For the value type, valueTypeA can be converted to valueTypeB. That is, the conversion rule for converting valueTypeA to valueTypeB is defined. For the two value types that do not have the conversion rule, they cannot be converted. For class and interface, if a parent-child type relationship exists between two types in the inheritance relationship diagram, the two types can be converted (the conversion may fail). Otherwise, the two types cannot be converted.

The following describes the type conversion rules between value types and between class and interface types. For other types that are not mentioned, Cangjie does not support type conversion between them in the preceding two methods.

Conversion Between Value Types

For numeric types, only the following conversions are supported:

1. Conversion from the Rune type to the UInt32 type.

2. Conversion from integer types (including Int8, Int16, Int32, Int64, IntNative, UInt8, UInt16, UInt32, UInt64, and UIntNative) to the Rune type.

3. Bidirectional conversion between all numeric types (including Int8, Int16, Int32, Int64, IntNative, UInt8, UInt16, UInt32, UInt64, UIntNative, Float16, Float32, and Float64).

The conversion from Rune to UInt32 uses the UInt32(e) mode. e is an expression of the Rune type. The result of UInt32(e) is an integer of the UInt32 type corresponding to the Unicode scalar value of e.

The conversion from the integer type to the Rune type uses the Rune(num) mode. The num type can be any integer type. Only when the value of num is in the range [0x0000,0xD7FF] or [0xE000,0x10FFFF] (that is, Unicode scalar value), the character represented by the corresponding Unicode scalar value is returned. Otherwise, an error is reported during compilation (the value of num can be determined during compilation) or an exception is thrown during running.

main() {
    var c: Rune = 'a'
    var num: UInt32 = 0
    num = UInt32(c) // num = 97
    num -= 32       // num = 65
    c = Rune(num)   // c = `A`
    return 0
}

To ensure type security, the Cangjie programming language does not support implicit type conversion between numeric types (the type of a numeric literal is inferred from the context, which is not implicit type conversion). To convert a numeric type to another numeric type, you must use the explicit method NumericType(expr) to forcibly convert the expr type to the NumericType type (NumericType indicates any numeric type). If the conversion is successful, a new value of the NumericType type constructed from the expr type is returned. The syntax for numeric type conversion is defined as follows:

numericTypeConvExpr
    : numericTypes '(' expression ')'
    ;
numericTypes
    : 'Int8' | 'Int16' | 'Int32' | 'Int64' | 'IntNative' | 'UInt8' | 'UInt16' | 'UInt32' | 'UInt64' | 'UIntNative' | 'Float16' | 'Float32' | 'Float64'
    ;

If the size relationship between numeric types is defined based on the number of bits occupied by numeric types (a larger number of bits indicates a larger type, and a smaller number of bits indicates a smaller type), the Cangjie programming language supports the following type conversion:

1. Bidirectional conversion between signed integer types: When a small value is converted to a large value, the value result remains unchanged. If the value result exceeds the representation range of the small value type, the overflow processing policy is determined based on the attribute macro in the context. By default, the exception throwing policy is used. For details about different overflow policies, see [Arithmetic Expressions]. The following uses the conversion between Int8 and Int16 as an example. When an overflow occurs, the policy of throwing an exception is used.

main() {
    var i8Number: Int8 = 127
    var i16Number: Int16 = 0
    i16Number = Int16(i8Number) 	// ok: i16Number = 127
    i8Number = Int8(i16Number) 		// ok: i8Number = 127
    i16Number = 128
    i8Number = Int8(i16Number) 		// throw an ArithmeticException
    return 0
}

2. The rule of the bidirectional conversion between unsigned integer types is the same as the preceding rule. The following uses the conversion between UInt16 and UInt32 as an example (the same rule applies to other cases):

main() {
    var u16Number: UInt16 = 65535
    var u32Number: UInt32 = 0
    u32Number = UInt32(u16Number) 	// ok: u32Number = 65535
    u16Number = UInt16(u32Number) 	// ok: u16Number = 65535
    u32Number = 65536
    u16Number = UInt16(u32Number)   // throw an ArithmeticException
    return 0
}

3. Bidirectional conversion between floating-point types uses the round-to-nearest mode. The following is an example of the conversion between Float32 and Float64:

main() {
    var f32Number: Float32 = 1.1
    var f64Number: Float64 = 0.0
    f64Number = Float64(f32Number)   	// f64Number = 1.100000023841858
    f32Number = Float32(f64Number)    	// f32Number = 1.1
    f64Number = 1.123456789
    f32Number = Float32(f64Number) 	    // f32Number = 1.1234568
    f32Number = 4.4E38 					// f32Number = POSITIVE_INFINITY
    f64Number = Float64(f32Number) 	    // f64Number = POSITIVE_INFINITY
    f64Number = 4.4E38
    f32Number = Float32(f64Number) 	    // f32Number = POSITIVE_INFINITY
    f64Number = Float64(f32Number*0.0)
    f32Number = Float32(f64Number) 	    // f32Number = NaN
    return 0
}

4. Bidirectional conversion between signed integer types and unsigned integer types: Because the representation range of any signed integer type cannot contain the representation range of an unsigned integer type of the same length (or vice versa), the conversion is successful if the value of the expression to be converted is within the range of the target integer type during type conversion. Otherwise, the overflow processing policy is determined based on the attribute macro in the context. By default, the exception throwing policy is used. For details about different overflow processing policies, see [Arithmetic Expression]. The following uses the conversion between Int8 and UInt8 as an example. When an overflow occurs, the policy of throwing an exception is used.

main() {
    var i8Number: Int8 = 127
    var u8Number: UInt8 = 0
    u8Number = UInt8(i8Number) 	// ok: u8Number = 127
    u8Number = 100
    i8Number = Int8(u8Number) 	// ok: i8Number= 100
    i8Number= -100
    u8Number = UInt8(i8Number) 	// throw an ArithmeticException
    u8Number = 255
    i8Number = Int8(u8Number) 	// throw an ArithmeticException
    return 0
}

5. Conversion from an integer to a floating-point number: The result is a floating-point number as close as possible to the original integer. POSITIVE_INFINITY or NEGATIVE_INFINITY is returned if the value is out of the representation range of the target type.

6. Conversion from a floating-point number to an integer: The round-toward-zero mode is used to convert a floating-point number to a signed integer. That is, the integer part is retained and the decimal part is discarded. When the integer part exceeds the representation range of the target integer type, the integer overflow policy in the context is used. If the throwing policy is used, an exception is thrown. Otherwise, the conversion rule is as follows:

• NaN returns 0.
• If the value is less than the lower limit of the integer value range (including negative infinity), the lower limit of the integer value range is returned.
• If the value is greater than the upper limit of the integer value range (including positive infinity), the upper limit of the integer value range is returned.

main() {
    var i32Number: Int32 = 1024
    var f16Number: Float16 = 0.0
    var f32Number: Float32 = 0.0
    f16Number = Float16(i32Number) 	// ok: f16Number = 1024.0
    f32Number = Float32(i32Number) 	// ok: f32Number = 1024.0
    i32Number = 2147483647
    f16Number = Float16(i32Number) 	// f16Number = POSITIVE_INFINITY
    f32Number = Float32(i32Number) 	// precision lost: f32Number = 2.14748365E9
    
    f32Number = 1024.1024
    i32Number = Int32(f32Number) 	// ok: i32Number = 1024
    f32Number = 1024e10
    i32Number = Int32(f32Number) 	// throw an Exception
    f32Number = 3.4e40 				// f32Number = POSITIVE_INFINITY
    i32Number = Int32(f32Number) 	// throw an Exception
    f32Number = 3.4e40 * 0.0 		// f32Number = NaN
    i32Number = Int32(f32Number) 	// throw an Exception
    return 0
}

Conversion Between Class and Interface Types

For an instance obj of the class or interface type, if you need to convert its (static) type to another TargetType of the class or interface type, use obj as TargetType.

For details about how to use the as operator and the type conversion rules between the class and interface types, see [as Operators].

Type Aliases

If the name of a type is complex or not intuitive in a specific scenario, you can use a type alias to obtain a simple and intuitive alias for the type. The syntax for defining a type alias is as follows:

typeAlias
	: typeModifier? `type` identifier typeParameters? `=` type
	;

typeModifier is an optional accessibility modifier (namely, public), type is a keyword, identifier is any valid identifier, type is any type visible to top-level, and identifier and type are connected by using =. In addition, you can define a generic alias by adding a type parameter (typeParameters) after identifier. For details, see [Generics].Through the preceding statement, an alias named identifier is defined for type, and identifier and type are considered as the same type. For example:

type Point2D = (Float64, Float64)
type Point3D = (Float64, Float64, Float64)

let point1: Point2D = (0.5, 0.8)
let point2: Point3D = (0.5, 0.8, 1.1)

The preceding type definition does not define a new type. It is only used to define another name for an existing type. The alias and the original type are considered as the same type, and the alias does not affect the use of the original type.

Rules for Defining Type Aliases

1. The definition of a type alias can be used only in top-level.

func test() {
    type Point2D = (Float64, Float64) 			// error: type alias can only be defined at top-level
    type Point3D = (Float64, Float64, Float64) 	// error: type alias can only be defined at top-level
}

2. When type is used to define a type alias, the original type must be visible in the position defined by type.

class LongNameClassA {

}
type ClassB = LongNameClassB	// error: use of undeclared type 'LongNameClassB'

3. When a generic alias is defined, if the generic alias introduces a generic parameter that is not used in the original type, the compiler generates a warning.

type Class1<V> = GenericClassA<Int64, V> 		// ok. ClassA is a generic class
type Class2<Value, V> = GenericClassB<Int64, V> // warning: the type parameter 'Value' in 'Class2<Value, V>' is not used in 'GenericClassB<Int64, V>'
type Int<T> = Int32 				            // warning: the type parameter 'T' in 'Int<T>' is not used in `Int32`

4. When defining a generic alias, you are not allowed to add generic constraints to the alias and the type parameters in the original type. When using a generic alias, you can add generic constraints as required. In addition, existing generic constraints in the original type are passed to the alias.

type Class1<V> where V <: MyTrait = GenericClassA<Int64, V> // error: generic constraints are not allowed here
type Class2<V> = GenericClassB<Int64, V> where V <: MyTrait // error: generic constraints are not allowed here

type Class3<V> = GenericClassC<Int64, V>
func foo<V> (p: Class3<V>) where V <: MyTrait {             // add generic constraints when 'Class3<V>' is used
    functionBody
}

class ClassWithLongName<T> where T<:MyTrait {
    classBody
}
type Class<T> = ClassWithLongName<T>                       // Class<T> also has the constraint 'where T<:MyTrait'

5. Circular references (direct or indirect) are not allowed in one or more type definitions. A manner of determining the circular reference is to determine whether the circular reference exists by using a name instead of using a manner of expanding a type.

type Value = GenericClassAp<Int64, Value> 	// error: 'Value' references itself
type Type1 = (Int64)->Type1 		        // error: 'Type1' references itself
type Type2 = (Int64, Type2) 		            // error: 'Type2' references itself
type Type3 = Type4 				            // error: 'Type3' indirectly references itself
type Type4 = Type3

6. A type alias is considered as a type equivalent to the original type. For example, in the following example, a parameter of the Int type and a parameter of the Int32 type may be directly added. Int is defined as an alias of Int32. Note that aliases cannot be used to overload functions.

type Int = Int32
let numOne: Int32 = 10
let numTwo: Int = 20
let numThree = numOne + numTwo

func add(left: Int, right: Int32): Int { left + right }

func add(left: Int32, right: Int32): Int32 { left + right } 	// error: invalid redeclaration of 'add : (Int32, Int32)->Int32'

7. The default visibility defined by type is default. To use the type alias defined in this package in other packages, the following conditions must be met: (1) The visibility modifier of the original type in this package is public; (2) The type definition uses the public modifier. In addition, note that the alias can have a different visible range from the original type, but the visible range of the alias cannot be greater than the visible range of the original type.

// a.cj
package A
public class ClassWithLongNameA {
    
}
class ClassWithLongNameB {
    
}
 
public type classA = ClassWithLongNameA 		// ok
type classAInter = ClassWithLongNameA 	// ok 

/* error: classB can not be declared with modifier 'public', as 'ClassWithLongNameB' is internal */
public type classB = ClassWithLongNameB 		

// b.cj
package B
import A.*
let myClassA: A.classA = ClassWithLongNameA()

Usage of Type Aliases

A type alias can be used in any position that the original type can use on the right-hand side of the equal sign (=).

1. When it is used as a type, for example:

   type A = B
   class B {}
   var a: A = B() // Use typealias A as type B
   

2. When the type alias refers to a class or struct, it can be used as the constructor name.

   type A = B
   class B {}
   func foo() { A() }  // Use type alias A as constructor of B
   

3. When the type alias refers to a class, interface, or struct, it can be used as the name to access static members or functions.

   type A = B
   class B {
   	static var b : Int32 = 0;
   	static func foo() {}
   }
   func foo() { 
   	A.foo() // Use A to access static method in class B
   	A.b
   }
   

4. When the type alias refers to an enum, it can be used as the type name for declaring the constructor of the enum.

   enum TimeUnit {
   	Day | Month | Year
   }
   type Time = TimeUnit
   var a = Time.Day  
   var b = Time.Month   // Use type alias Time to access constructors in TimeUnit 
   

Relationship Between Types

There are two types of relationships: equality and subtype.

Type Equality

For any two types T1 and T2, T1 and T2 are considered equal (denoted as $T1 \equiv T2$) if they meet any of the following conditions:

• The type alias definition type T1 = T2 exists.

• In the class definition and extend of class, T1 is the name of class, and T2 is This.

• The names of T1 and T2 are the same (reflective).

• $T2 \equiv T1$ (symmetry).

• The type $Tk$ exists, which meets $T1 \equiv Tk$ and $Tk \equiv T2$ (transitive).

Subtypes

For any two types T1 and T2, T1 and T2 are considered as subtypes (denoted as $T1 <: T2$) if they meet any of the following conditions:

• $T1 \equiv T2$.

• T1 is of the Nothing type.

• Both T1 and T2 are of the Tuple type, and the type at each position of T1 is the subtype of the type at the position corresponding to T2.

• Both T1 and T2 are of the Function type. The parameter type of T2 is the subtype of the T1 parameter type, and the return type of T1 is the subtype of the T2 return type.

• T1 is of any class type, and T2 is of the Object type.

• Both T1 and T2 are of the interface type, and T1 inherits T2.

• Both T1 and T2 are of the class type, and T1 inherits T2.

• T2 is of the interface type, and T1 implements T2.

• The type $Tk$ exists, which meets $T1 <: Tk$ and $Tk <: T2$ (transitive).

Minimum Common Supertype

In a type system with subtypes, the minimum common parent type of two types may be required. For example, the type of the if expression is the minimum common supertype of the types of the two branches. The match expression is similar.

The minimum common supertype between two types is a subtype of all other common supertypes.

The minimum common supertype is defined as follows: For any two types T1 and T2, if the type LUB meets the following rules, LUB is the minimum common supertype of T1 and T2:

• For any type of T that meets both T1 <: T and T2 <: T, LUB <: T is true.

Note that if a type in the common supertype is not larger than other types, it is only an extremely small one and not necessarily minimum one.

Maximum Common Subtype

Inversion exists in the subtype relationship (see [Type Variation] in [Generics] for its definition).For example, if the parameter type of the function type is inversion, the maximum common subtype of the two types is required.

The maximum common subtype between two types is a supertype of all other common subtypes.

The maximum common subtype is defined as follows: For any two types T1 and T2, if the type GLB meets the following rules, GLB is the maximum common subtype of T1 and T2:

• For any type of T that meets both T <: T1 and T <: T2, T <: GLB is true.

Note that if a type in the common subtype is not smaller than other types, it is only an extremely large one and not necessarily maximum one.

Type Security

In the case of no data contention, the compiler ensures memory security and type security.

The following is an example in which type security and memory security cannot be ensured:

class C {
    var x = 1
    var y = 2
    var z = 3
}

enum E {
    A(Int64) | B(C)
}

var e = A(1)

main() {
    spawn {
        while (true) {
            e = B(C())      // writing to `e`
            e = A(0)
        }
    }
    while (true) {
        match (e) {         // reading from `e`
            case A(n) =>
                println(n+1)
            case B(c) =>
                c.x = 2
                c.x = 3
                c.x = 4
        }
    }
}

It cannot be ensured because there is data competition between the thread that assigns a value to the variable e and the thread that reads the variable. For more information about data contention, see [Concurrency].

Names, Scopes, Variables, and Modifiers

This chapter first describes names, scopes, and shadowing, then introduces one of the names—variables, including their definition and initialization, and finally introduces modifiers.

Names

In Cangjie, names are used to identify entities such as variables, functions, types, packages, and modules.

names must be valid [Identifiers].

In Cangjie, keywords, variables, functions, types (including class, interface, struct, enum, and type alias), generic parameters, package names, and module names share the same namespace. That is, entities declared or defined in the same scope must have different names (except the names that constitute overloading). Entities declared or defined in different scopes can have the same name, but this may lead to shadowing.

let f2 = 77

func f2() { // Error, function name is the same as the variable f2
    print("${f2}")
}     

// Variable, function, type names cannot be the same as keywords 
let Int64 = 77   // Error: 'Int64' is a keyword

func class() {  // Error: class is a keyword
    print("${f2}")
}    

main(): Int64 {  
    print("${f2}")   // Print 77

    let f2 = { => // Shadowed the global variable f2
       print("10")
    }
    f2()
    return 1
}

Scopes

An entity can be accessed by name within the scope of its name without needing a prefix qualifier. A scope can be nested, meaning that a scope contains itself and any nested scopes within it. If a name is not shadowed or overridden within its nested scope, it can also be accessed directly.

Blocks

In Cangjie, a structure consisting of a pair of matching curly braces and an optional expression and declaration sequence in the braces is called a block. Blocks are everywhere in Cangjie. For example, the function body defined by a function, two branches of an if expression, and the loop body of a while expression are all blocks. Blocks lead to new scopes.

The syntax of a block is defined as follows:

block
    : '{' expressionOrDeclarations '}'
    ;

A block has a value. The value of a block is determined by the expression and the declaration sequence within it. When a block is evaluated, the evaluation is performed in the order of the expressions and variable declarations within the block.

If the last item of a block is an expression, the value of that expression is the value of the block once it is evaluated.

{
    let a = 1
    let b = 2
    a + b
} // The value of the block is a + b

If the last item of a block is a declaration, the value of the block is () after the declaration is processed.

{
    let a = 1
} // The value of the block is ()

If a block does not contain any expression or declaration, the value of the block is ().

{ } // The value of this empty block is ()

Scope Levels

If duplicate names exist in the nested multi-level scope, the name introduced by the inner scope shadows the name of the outer scope, meaning the inner scope has a higher level than the outer one.

The comparison of scope levels in nested scopes is defined as follows:

1. Names introduced by import have the lowest scope level.

2. Top-level names in a package have a higher scope level than names in point 1.

3. Names introduced within a type, function definition, or expression, typically defined within a pair of curly braces {} (that is, in blocks), have a higher scope level than names outside {}.

4. For classes and interfaces, names in a subclass have a higher scope level than those in the superclass and may shadow or override the latter.

import p1.a   // a has the lowest scope level

var x = 1   // x 's scope level is higher than p1.a

open class A {    // A's scope level the same as x at line 3
    var x = 3     // This x has higher scope level than the x at line 3
    var y = 'a'  
    func f(a: Int32, b: Float64): Unit {

    }
}

class B <: A {
    var x = 5   // This x has higher scope level than the x at line 6

    func f(x!: Int32 = 7) { // This x's scope level is higher than the x at line 14

    }
}

Scope Principles

Based on the location of name introduction, there are three types of scopes: top-level, local-level, and type-internal. The following describes the different principles of the three types of scopes.

Top-level

Names introduced at the top level adhere to the following scope principles:

• The scope of top-level functions and types is the entire package, and their names are visible to the entire package. These types include class, interface, enum, struct, and type.
• Names of top-level variables, introduced by let, var, and const, have a scope that begins after their definition (including initialization) is complete and does not include the range from the start of the file to the variable declaration. These names are visible to other files in the package. However, the initialization process of variables may have side effects. Therefore, variables must be declared and initialized before use.

/* Global variables can be accessed only after defined. */
let x = y         //Error: y is used before being defined
let y = 4
let a = b         //Error: b is used before being defined 
let b = a         
let c = c         //Error: unresolved identifier 'c' (in the right of '=')  

//Function names are visible in the entire package
func test() { test2() }   // OK

func f() { test() } // OK

func test2(): Int64 {
    var x = 99
    return x
}

Local-level

Names declared or defined within a function definition or expression have a local-level scope. Variables defined in a block have a higher scope level than those defined outside the block.

• The scope of a local variable ranges from its declaration to the end of the current scope. A local variable must be defined and initialized before use. The shadowing of a local variable starts after the declaration or definition of the variable name.
• The scope of a local function ranges from its declaration to the end of the current scope. Recursive definition is supported, but mutual recursion is not supported.
• The scope of a parameter or a generic parameter of a function ranges from the parameter name declaration to the end of the function body. The scope level is the same as that of the variables defined in the function body.
  • The function definition func f(x: Int32, y!: Int32 = x) {} is valid.
  • The function definition func f(x!: Int32 = x) {} is invalid.
• Generic parameters introduced in generic type declarations or extensions have a scope that starts from the declaration of the parameter names to the end of the type body or extension body. The scope level of the generic parameter is the same as the names defined in the type.
  • In the generic type definition class C<T> {}, the scope of T ranges from its declaration to the end of the class C declaration.
  • In the generic type extension extend<T> C<T> {}, the scope of T ranges from its declaration to the end of the extension definition.
• Similar to a function, the scope of the parameter name of the lambda expression is the lambda expression function body. The scope level can be considered as the same as that of a variable defined in the function body of the lambda expression.
• The parameter names of the main functions and constructors are considered to be introduced by the function body block. Introducing a name that is the same as the parameter name in the function body will trigger a redefinition error.
• Names introduced in the condition of an if-let expression are considered to be introduced by the if block. If the same name is introduced again in the if block, a redefinition error is triggered.
• Names introduced by patterns in the match cases of a match expression have a higher scope level than the surrounding match expression, with a scope ranging from their introduction to the end of that match case. Each match case has an independent scope. Names introduced in the pattern binding of a match case are considered to be introduced by the scope following the fat arrow =>. If the same name is introduced again after the =>, a redefinition error is triggered.
• For all three types of loops, the scope level of the loop condition is the same as that of the loop block, meaning names introduced in them cannot shadow each other. In addition, loop conditions cannot reference variables defined in the loop body. Therefore:
  • In a for-in expression, the loop body can reference variables introduced in the loop condition.
  • In while and do-while expressions, their loop conditions cannot reference variables introduced in their loop bodies, even if the do-while condition follows the loop body.
• Variables introduced in the loop condition of a for-in loop cannot be used in expressions following the in keyword.
• For try exception handling, the scope of the block following try and that of each catch block are independent of each other. Names introduced by catch patterns are viewed as introduced by the block following catch. Introducing the same name in the catch block will trigger a redefinition error.
• In the try-with-resources expression, names introduced between the try keyword and the {} are considered to be introduced by the try block. Introducing the same name in the try block will trigger a redefinition error.

// a: The scope of a local variable begins after the declaration
let x = 4
func f(): Unit {
    print("${x}") // Print 4

    let x = 99    
    print("${x}") // Print 99
}

let y = 5
func g(): Unit {
    let y = y     // 'y' in the right of '=' is the global variable 'y'
    print("${y}") // Print 5 

    let z = z     // Error: unresolved identifier 'z' (in the right of '=')
}

// b: The scope of a local function begins after definition
func test1(): Unit {
    func test2(): Unit {
        print("test2")
        test3() // Error, test3's scope begins after definition
    }
    func test3(): Unit {
        test2()
    }

    test2()    
}

let score: Int64 = 90
let good = 70
var scoreResult: String = match (score) { // binding pattern
    case 60 => "pass" // constant pattern.
    case 100 => "Full" // constant pattern.
    case good => "good" // This good has higher scope level than the good at line 2
}

Type-internal

• The scope of members in class, interface, struct, or enum is the entire definition of that class, interface, struct, or enum.
• The scope of constructors defined within an enum is the entire enum definition. For specific rules regarding access to constructor names within an enum, see [Enum Type].

Shadowing

Generally, if the same name is introduced into two overlapping scopes with different levels, shadowing occurs. The name with a higher scope level shadows the name with a lower scope level. As a result, the name with a lower scope level either need to be prefixed with qualifiers or cannot be accessed. Shadowing is removed when the scope of the name with a higher scope level ends. Specifically, when the scope levels are different:

• If the name C with a higher scope level is of a type, shadowing occurs directly.

  // == in package a ==
  public class C {} // ver 1
  
  // == in package b ==
  import a.*
  
  class C {} // ver 2
  
  let v = C() // will use ver 2
  

• If the name x with a higher scope level is a variable, shadowing occurs directly. For details about the shadowing rules of member variables, see [Classes and Interfaces].

  let x = 1
  
  func foo() {
      let x = 2
      println(x) // will print 2
  }
  

• If the name p with a higher scope level is a package, shadowing occurs directly.

  // == in package a ==
  public class b {
      public static let c = 1
  }
  
  // == in package a.b ==
  public let c = 2
  
  // == in package test ==
  import a.*
  import a.b.*
  
  let v = a.b.c // will be 1
  

• If the name f with a higher scope level is a member function, the overloading rules are used to determine whether f is overloaded. If there is no overloading, it may result in overriding or redefinition; if there is no overloading and overriding or redefinition is not possible, an error is reported. For details, see [Overriding] and [Redefinition].

  open class A {
      public open func foo() {
          println(1)
      }
  }
  
  class B <: A {
      public override func foo() {  // override
          println(2)
      }
  
      public func foo() {  // error, conflicting definitions
          println(3)
      }
  }
  

• If the name f with a higher scope level is a non-member function, the overloading rules are used to determine whether f is overloaded. If there is no overloading, it is considered as shadowing.

  func foo() { 1 }
  
  func test() {
      func foo() { 2 } // shadows
      func foo(x: Int64) { 3 } // overloads
  
      println(foo()) // will print 2
  }
  

The following example shows the shadowing relationship between multiple names (including types and variables) with different scope levels.

func g(): Unit {
  	f(1, 2)  // OK. f is a top-level definition, which is visible in the whole file 
}

func f(x: Int32, y: Int32): Unit {  
    // var x = 1 // Error, x was introduced by parameter
    var i = 1       // OK

    for (i in 1..3) { // OK, a new i in the block
        let v = 1   
    }              // i and v disappear

    print("${i}")     // OK. i is defined at line 9
    // print("${v}") // Error, v disappeared and cannot be found
}

enum Maze {
    C1 | C2
    // | C1 // Error. The C1 has been used
}

The following example shows the shadowing relationship between names (including types and variables) in different packages.

// File a.cj
package p1

class A {}
var v: Int32 = 10

// File b.cj
package p2
import p1.A        // A belongs to the package p1
import p1.v        // v belongs to the package p1

// p2 has defined its own v, whose scope level is higher than the v from package p1
var v: Int32 = 20     

func displayV1(): Unit {
    // According to the scope level, p2.v shadows p1.v, therefore access p2.v here 
    print("${v}")          // output: 20
}

var a = A()         // Invoke A in p1

The following example shows the shadowing relationship in inheritance.

var x = 1   

open class A {
  	var x = 3   // this x shadows the top level x
}

class B <: A {
    var x = 5   // error: a member of the subtype must not shadow a member of the supertype.

    func f(x!: Int32 = 7): Unit { // this x shadows all the previous x

    }
}

Variables

As a statically typed language, Cangjie requires that the type of each variable be determined during compilation.

Variables can be classified into three types based on whether they can be modified: immutable variables (whose values cannot be changed once initialized), mutable variables (whose values can be changed), and const variables (which must be initialized during compilation and cannot be changed).

Definition of Variables

The syntax of defining variables is as follows:

variableDeclaration
    : variableModifier* ('let' | 'var' | 'const') patternsMaybeIrrefutable (((':' type)? ('=' expression)) | (':' type))
    ;

patternsMaybeIrrefutable
    : wildcardPattern
    | varBindingPattern
    | tuplePattern
    | enumPattern
    ;

The definition of a variable consists of four parts: modifier, the let, var, or const keywords, patternsMaybeIrrefutable, and variable type, which are described as follows:

1. Modifiers

   • The modifiers of the top-level variable are public, protected, private, and internal.
   • Local variables cannot be modified by modifiers.
   • The modifiers of the member variables of the class type are public, protected, private, internal, and static.
   • The modifiers of member variables of the struct type are public, private, internal, and static.

2. Keywords let, var, and const

   • let: defines immutable variables whose values cannot be changed once initialized.
   • var: defines mutable variables.
   • const: defines const variables.

3. patternsMaybeIrrefutable

   • let (or var, const) can only be followed by patterns that must or may be irrefutable (see [Classification of Patterns]). During semantic check, the system checks whether the pattern is irrefutable. If the pattern is not irrefutable, a compilation error is reported.
   • The new variables introduced in the pattern after let (or var, const) are all variables modified by let (or var).
   • When defining member variables in a class or struct, you can only use the binding patterns (see [Binding Patterns]).

4. The variable type is optional. If the variable type is not declared, an initial value must be assigned to the variable, and the compiler will attempt to infer the variable type from the initial value.

5. Variables can be defined at the top-level, within expressions, or in the class or struct types.

Note that:

(1) Use a colon (:) to separate the pattern and variable type. The pattern type must match the type after the colon.

(2) The keywords let, var, and const and the pattern are required.

(3) In addition to the preceding syntax definition, local variables are introduced in the following scenarios:

• For details about patterns between for and in in a for-in loop expression, see [For-in Expression].
• For details about parameters in the function and lambda definition, see [Parameters].
• For details about ResourceSpecifications in the try-with-resource expression, see [Exceptions].
• For details about pattern after case in the match expression, see [Pattern Matching Expressions].

(4) You can use a pair of backquotes () to change the keyword to a valid identifier, such as <idp:inline val="code" displayname="code">open and throw.

The following are some examples of variable definition:

let b: Int32                // Define read-only variable b with type Int32.
let c: Int64                // Define read-only variable c with type Int64.
var bb: String              // Define writeable variable bb with type String.
var (x, y): (Int8, Int16)   // Define two writeable variable: x with type Int8, x with type Int16.
var `open` = 1              // Define a variable named `open` with value 1.
var `throw` = "throw"       // Define a variable named `throw` with value "throw".
const d: Int64 = 0		// Define a const variable named d with value 0.

Initializing Variables

Immutable and Mutable Variables

Both immutable variables and mutable variables can be initialized in either of the following ways: initialization during definition and initialization after definition. Note that each variable must be initialized before being used. Otherwise, a compilation error is reported. The following is an example of variable initialization:

func f() {
    let a = 1               // Define and initialize immutable variable a.
    let b: Int32            // Define immutable variable b without initialization.
    b = 10                  // Initialize variable b.
    var aa: Float32 = 3.14  // Define and initialize mutable variable aa.
}

An immutable variable defined by let can be assigned a value only once (that is, initialization). If the variable is assigned a value for multiple times, a compilation error is reported. Mutable variables defined by var can be assigned multiple values.

func f() {
    let a = 1             // Define and initialize immutable variable a.
    a = 2                 // error: immutable variable a cannot be reassigned.
    var b: Float32 = 3.14 // Define and initialize mutable b.
    b = 3.1415            // ok: mutable variable b can be reassigned.
}

class C {
    let m1: Int64
    init(a: Int64, b: Int64) {
        m1 = a
        if (b > 0) {
            m1 = a * b  // OK: immutable variable can be reassigned in constructor.
        }
    }
}

Global and Static Variables

Global variables are defined at the top level. Static variables include those defined in class or struct. The initialization of global and static variables must meet the following rules:

• Global variables must be initialized immediately when they are declared. Otherwise, an error is reported. That is, an initialization expression must be provided during declaration.

• Static variables must be initialized immediately when they are declared. They can be initialized in the same way as global variables or in the static initializer. For details, see [Static Initializers].

  • Note that static variables cannot be initialized in other static variables.

  class Foo {
      static let x: Int64
      static let y = (x = 1) // it's forbidden
  }
  

• The initialization expression e cannot depend on uninitialized global variables or static variables. The compiler performs conservative analysis. If e may access an uninitialized global variable or static variable, an error is reported. The detailed analysis depends on the implementation of the compiler and is not specified in the specification.

The initialization time and sequence of global/static variables are as follows:

• All global/static variables are initialized before main (program entry).

• For global/static variables declared in the same file, the initialization sequence is from top to bottom based on the variable declaration sequence. If a static initializer is used, the initialization sequence is based on the initialization sequence rules of the static initializer. For details, see [Static Initializers].

• For global/static variables declared in different files of the same package or different packages, their initialization sequence depends on the dependency between the global/static variables in the files or packages.

• If the global/static variables in the A.cj file are directly or indirectly accessed during the initialization of the global/static variables in the B.cj file, the initialization of the global/static variables in the B.cj file depends on that of the global/static variables in the A.cj file. The reverse is also true.

• If the initialization processes of global/static variables in two or more files depend on each other, a cyclic dependency is formed, and the compiler reports an error. If there is no dependency between these files, the initialization sequence is uncertain and determined by the compiler implementation.

• If the variable, function, or type defined in the A package is directly or indirectly used in the B package, the B package depends on the A package. The reverse is also true.

• If there are cyclic dependencies between packages, the compiler reports an error. If there is no dependency between packages, their initialization sequence is uncertain and determined by the compiler implementation.

  /* The initialization of the global variable cannot depend on the global  
     variables defined in other files of the same package. */
  // a.cj
  let x = 2
  let y = z       // OK, b.cj does not depend on this file directly or indirectly.
  let a = x       // OK.
  let c = A()
  
  /* c.f is an open function, the compiler cannot statically determine whether the
     function meets the initialization rules of global variables, and an error may 
     be reported. */
  let d = c.f()
  
  open class A {
      // static var x = A.z     // Error, A.z is used before its initialization.
      // static var y = B.f     // Error, B.f is used before its initialization.
      static var z = 1
      public open func f(): Int64 {
          return 77
      }
  }
  
  class B {
      static var e = A.z    // OK.
      static var f = x      // OK.     
  }
  
  // b.cj      
  let z = 10      
  // let y = 10   // Error, y is already defined in a.cj.
  
  // main.cj
  main(): Int64 {
      print("${x}")
      print("${y}")
      print("${z}")
      return 1
  }
  

const Variables

For details, see [Constant Evaluation].

Modifiers

Cangjie provides many modifiers, which are classified into the following types:

• Access modifier
• Non-access modifier

Modifiers are usually placed at the beginning of a definition to indicate that the definition has certain features.

Access Modifier

For details, see Access Modifiers in [Packages and Modules].

Non-access Modifier

Cangjie provides many non-access modifiers to support various functionalities.

• open: The instance member can be overridden by a subclass, or the class can be inherited by a subclass. For details, see [Classes].
• override: The member overrides that of the superclass. For details, see [Classes].
• redef: The static member redefines that of the superclass. For details, see [Classes].
• static: the member is a static member and cannot be accessed through an instance object. For details, see [Classes].
• abstract: The class is an abstract class. For details, see [Classes].
• foreign: The member is an external member. For details, see [Cross-Language Interoperability].
• unsafe: The context for interoperability with the C language. For details, see [Cross-Language Interoperability].
• sealed: The class or interface can be inherited or implemented only in the current package. For details, see [Classes].
• mut: The member has variable semantics. For details, see [Functions].

For details about these modifiers, see the corresponding sections.

Expressions

An expression consists of one or more operands. Multiple operands are connected by operators. Each expression has a type. The process of calculating the expression value is called evaluation.

In the Cangjie programming language, expressions are almost ubiquitous. There are expressions that represent various calculations (such as arithmetic expressions and logical expressions), and expressions that represent branches and loops (such as if expressions and loop expressions). For expressions that contain multiple operators, the precedence, associativity, and operand evaluation sequence of each operator must be specified. The precedence and associativity specify the combination mode of operands and operators. The evaluation sequence of operands specifies the evaluation sequence of operands of binary and ternary operators. Both of them affect the value of an expression.

The following describes expressions in Cangjie in sequence.

Note: The operand types of each operator in this chapter are specified on the premise that the operator is not overloaded.

Literals

A literal is an expression with a fixed syntax. For a literal that does not contain other expressions (see [Literals]), its value is the value of the literal itself, and its type can be determined by its syntax or context.When the literal type cannot be determined, an integer literal is of the Int64 type, and a floating-point literal is of the Float64 type. For a set literal or a tuple literal (see [Tuple]) that can contain other expressions internally, its value is equal to the value of the literal obtained after all expressions inside it are evaluated.Its type is determined by its syntax.

Example of literals:

main(): Int64 {
    10u8                          // UInt8 literal
    10i16                         // Int16 literal
    1024u32                       // UInt32 literal
    1024                          // Int64 literal
    1024.512_f32                  // Float32 literal
    1024.512                      // Float64 literal
    'a'                           // Rune literal
    true                          // Bool literal
    "Cangjie"                     // String literal
    ()                            // Unit literal
    [1, 2, 3]                     // Array<Int64> literal
    (1, 2, 3)                     // (Int64, Int64, Int64) literal
    return 0
}

Variable Names and Function Names

Variable names and function names (including variables or functions pointed to by package names) are also expressions. For a variable name, its value is equal to the evaluated value of the variable, and its type is that of the variable. For a function name, its value is a closure (see [Closures]), and its type is that of the function.

Examples of variable names and function names:

let intNum: Int64 = 100 // 'intNum' is the name of a variable, whose value and type are '100' and 'Int64', respectively.

/* 'add' is the name of a function, whose value and type are '(p1: Int64, p2: Int64) => {p1 + p2}' and '(Int64, Int64) -> Int64', respectively. */
func add(p1: Int64, p2: Int64) { 
    p1 + p2 
} 

let value = p1.x // x is a variable defined in package p1.

For variable names, the variables declared by var are always mutable. A value can be assigned to a variable declared by let only once (during or after declaration). The variable is mutable before the value is assigned and immutable after the value is assigned.

Generic Function Name as Expression

In Cangjie, functions (see [Functions]) can be used as the first member, and generic functions (see [Generics]) that declare type parameters are also supported.For a generic function, the type argument of the generic function must be provided when the function name is used as an expression. Example:

func identity<T>(a: T) { // identity is a generic function
    return a 
}

var b = identity // error: generic function 'identity' needs type arguments

var c = identity<Int32> // ok: Int32 is given as a type argument

identity is a generic function. Therefore, identity is not a valid expression. Only identity<Int32> that provides the type argument is a valid expression.

If a function is overloaded in the current scope and contains multiple optional functions with complete types, it is ambiguous to directly use the name of this type as an expression. For example:

interface Add<T> {
    operator func +(a: T): T
}

func add<T>(i: T, j: Int64): Int64 where T <: Add<Int64> { // f1
    return i + j;
}

func add<T>(i: T, j: T): T where T <: Add<T> { // f2
    return i + j;
}

main(): Int64 {
    var plus = add<Int64> // error: ambiguous use of 'add'
    return 0
}

Condition Expressions

A conditional expression is an if expression. You can determine the code branch to be executed based on whether the conditions are met to implement the branch control logic.

The syntax of if expressions is defined as follows:

ifExpression
    : 'if' '(' ('let' deconstructPattern '<-')? expression ')' block ('else' ( ifExpression | block))?
    ;

if is the keyword, followed by an expression enclosed in parentheses, a block, and an optional else branch in sequence. The else branch starts with the else keyword and is followed by a new if expression or a block.

The following is an example of if expressions:

main(): Int64 {
    let x = 100
    // if expression without else branch
    if (x > 0) { 
        print("x is larger than 0")
    }

    // if expression with else branch
    if (x > 0) { 
        print("x is larger than 0")
    } else {
        print("x is not larger than 0")
    }

    // if expression with nested if expression
    if (x > 0) {
        print("x is larger than 0")
    } else if (x < 0) {
        print("x is lesser than 0")
    } else {
        print("x equals to 0")
    }    
    
    return 0 
}

The expression following if (the expression type must be Bool) is evaluated first. If the value of the expression is true, the block following the expression is executed. Otherwise, the if expression or block (if any) following else is executed. The value of the if expression is equal to the value of the expression in the execution branch.

An if expression that contains let is called an if-let expression. You can use the if-let expression to perform some simple deconstruction operations.

The following is an example of a basic if-let expression:

main(): Int64 {
    let x: Option<Int64> = Option<Int64>.Some(100)
    // if-let expression without else branch
    if (let Some(v) <- x) { 
        print("x has value")
    }
    // if-let expression with else branch
    if (let Some(v) <- x) { 
        print("x has value")
    } else {
        print("x has not value")
    }
    return 0 
}

In the if-let expression, the expression following <- (the expression type can be any type) is first evaluated. If the value of the expression matches the pattern following let, the block following the expression is executed. Otherwise, the if expression or block (if any) following else is executed. The value of the if-let expression is equal to the value of the expression in the execution branch.

The pattern following let supports the constant, wildcard, binding, tuple, and enum patterns.

Types of the if expression

For an if expression without an else branch, its type is Unit, and its value is (), because if expr1 {expr2} is the syntactic sugar of if expr1 {expr2; ()} else {()}.

For an if expression that contains an else branch:

• If the value of the if expression is not read or returned, the type of the if expression is Unit, and the two branches do not need to have a common supertype. Otherwise, see the following rules.

• If there is no specific type requirement in the context and the two branch types of if are set to T1 and T2, the type of the if expression is T, the minimum common supertype of T1 and T2. If the minimum common supertype T does not exist, an error is reported during compilation.

• If the context specifies type requirements, this supertype is the type of the if expression. In this case, the types of the two branches of if must be the subtypes of the type required by the context.

For example:

struct S1 { }
struct S2 { }

interface I1 {}
class C1 <: I1 {}
class C2 <: I1 {}

interface I2{}
class D1 <: I1 & I2 {}
class D2 <: I1 & I2 {}

func test12() {
    if (true) {  // OK. The type of this if expression is Unit.
        S1()
    } else {
        S2()
    }  

   if (true) {  // OK. The type of this if expression is Unit. 
        C1()
    } else {
        C2()
    }
    
    return if (true) {  // Error. The `if` expression is returned. There is no least common supertype of `D1` and `D2`. 
        D1()
    } else {
        D2()
    }
}

Note: To normalize the code format, improve the code maintainability, and avoid the dangling else problem, Cangjie requires that the execution part (even if there is only one expression) in each if branch and else branch use a pair of curly braces to enclose a block. (The dangling else problem refers to the problem that whether else expr2 in the code such as if cond1 if cond2 expr1 else expr2 belongs to the inner or the outer if cannot be determined. If else expr2 belongs to the inner if, the code should be interpreted as if cond1 (if cond2 expr1 else expr2). If it belongs to the outer if, the code should be interpreted as if cond1 (if cond2 expr1)expr2. However, if the branch is forced to use braces, this problem does not occur.)

Pattern Matching Expression

In Cangjie, match expressions can be used to implement pattern matching, and developers are allowed to use simpler code to describe complex branch control logic. Intuitively, a pattern is a structure that defines a set of instances that match the pattern. Pattern matching is to determine whether a given instance belongs to the instance set defined by the pattern. Obviously, there are only two matching results: success and failure. match expressions are classified into two types: match expressions with and without selector.

The syntax of match expressions is defined as follows:

matchExpression
    : 'match' '(' expression ')' '{' matchCase+ '}'
    | 'match' '{' ('case' (expression | '_') '=>' expressionOrDeclaration+)+ '}'
    ;
matchCase
    :  'case' pattern ('|' pattern)* patternGuard? '=>' expressionOrDeclaration+
    ;
patternGuard
    : 'where' expression
    ;

For a match expression with selector, expression following the keyword match is the selector to be matched. Multiple matchCases can be defined in {} after selector. Each matchCase starts with the keyword case, followed by a pattern or multiple patterns of the same type separated by | (For details about the definitions of different patterns, see [Patterns]), an optional pattern guard, a fat arrow =>, and a series of (at least one) declarations or expressions (separated by semicolons or newline characters).

During the execution of the match expression, a selector matches a pattern in the sequence defined by case. Once a selector matches the current pattern (and meets the pattern guard requirement), the code following the => is executed and the selector does not need to match the next pattern. If the selector does not match the current pattern, the system continues to match the next pattern. The same rule applies to the rest. The following example shows how to use constant patterns for branch control in a match expression:

let score: Int64 = 90
var scoreResult: String = match (score) {
    case 0 => "zero"
    case 10 | 20 | 30 | 40 | 50 => "fail"
    case 60 => "pass"
    case 70 | 80 => "good"
    case 90 | 100 => "excellent" // matched
    case _ => "not a valid score"
}

To ensure security and completeness, Cangjie requires that the combination of all patterns defined in case expressions and the corresponding patternGuards (if any) must be exhaustive, covering all possible values of selector. If the compiler determines that the combinations are not exhaustive, an error is reported. To implement complete coverage, you can use the wildcard _ in the last case to process the values that other cases fail to cover. In addition, it is not required that space defined by each pattern is mutually exclusive, that is, space covered by different patterns may overlap.

For a match expression without selector, the keyword match is not followed by expression. In each case within {}, only one expression of the Bool type (or the wildcard _, indicating that the value is always true) can be used between the keyword case and =>.

During the execution, the values of the expressions following case are checked in sequence. If the value of an expression is true, the code following => is executed, and all cases following => do not need to be checked. A match expression without selector is a concise expression for a series of nested if-else if expressions.

Similarly, the match expression without selector must be exhaustive (that is, at least one case is met in any case). The compiler performs exhaustive check if possible. If the check fails, an error is reported and the system prompts you to add case _.

let score = 80 
var result: String = match {
    case score < 60 => "fail"
    case score < 70 => "pass"
    case score < 90 => "good" // matched
    case _ => "excellent"
}

Similar to an if expression, the type of a match expression complies with the following rules regardless of whether the match expression contains selector:

• If the value of the match expression is not read or returned, the type of the match expression is Unit, and all branches do not need to have a common supertype. Otherwise, see the following rules.

• If there is no specific type requirement in the context and all branch types of match are T1, ..., Tn, the type of the match expression is T, the minimum common supertype of T1, ..., Tn. If the minimum common supertype T does not exist, an error is reported.

• If the context has specific type requirements, this supertype is the type of the match expression. In this case, the type of the expression following => in each case must be the subtype of the type required by the context.

Patterns

Changjie provides various patterns, including:

1. Constant patterns

2. Wildcard patterns

3. Binding patterns

4. Tuple patterns

5. Type patterns

6. Enum patterns

The syntax of patterns is defined as follows:

pattern
    : constantPattern
    | wildcardPattern
    | varBindingPattern
    | tuplePattern
    | typePattern
    | enumPattern
    ;

Constant Patterns

Constant patterns can be integer literals, byte literals, floating-point literals, Rune literals, Boolean literals, string literals (string interpolation is not supported), and unit literals. The type of a literal in the constant pattern must be the same as that of selector. The condition for successful matching between selector and a constant pattern is that selector is the same as the literal in the constant pattern.

The syntax of constant patterns is defined as follows:

constantPattern
    : literalConstant
    ;

The following is an example of using constant patterns:

func f() {
    let score: Int64 = 90
    var scoreResult: String = match (score) { 
        case 0 => "zero"
        case 10 | 20 | 30 | 40 | 50 => "fail"
        case 70 | 80 => "good"
        case 90 => "excellent" // matched
        case _ => "not a valid score"
    }
}

Note that floating-point literal matching complies with the floating-point equality comparison rules in constant patterns, which has the same precision problem as those encountered in other equality comparisons.

Wildcard Patterns

A wildcard pattern is represented by an underscore (_), which can match any value. It is usually used for partial matching (for example, as a placeholder) or as the last pattern of a match expression to match values that are not covered by other cases.

The syntax of wildcard patterns is defined as follows:

wildcardPattern
    : '_'
    ;

The following is an example of using wildcard patterns:

let score: Int64 = 90
var scoreResult: String = match (score) {
    case 60 => "pass"
    case 70 | 80 => "good"
    case 90 | 100 => "excellent" // matched
    case _ => "fail"             // wildcard pattern: used for default case 
}

Binding Patterns

A binding pattern can also match any value. However, different from a wildcard pattern, a binding pattern binds the matched value to the variable defined in binding pattern so that the value can be accessed in the expression following =>.

The syntax of binding patterns is defined as follows:

varBindingPattern
    : identifier
    ;

Variables defined in a binding pattern are immutable.

The following is an example of using binding patterns:

let score: Int64 = 90
var scoreResult: String = match (score) {
    case 60 => "pass"
    case 70 | 80 => "good"
    case 90 | 100 => "excellent" // matched
    case failScore =>            // binding pattern
        let passNeed = 60 - failScore
        "failed with ${failScore}, and ${passNeed} need to pass"
}

For a variable defined in the binding pattern, its scope starts from the position where the variable appears for the first time and ends before the next case. Note that | is used to connect multiple patterns, the binding pattern cannot be used and cannot be nested in other patterns. Otherwise, an error is reported.

let opt = Some(0)
match (opt) {
    case x | x => {}                // error: variable cannot be introduced in patterns connected by '|'
    case Some(x) | Some(x) => {}    // error: variable cannot be introduced in patterns connected by '|'
    case x: Int64 | x: String => {} // error: variable cannot be introduced in patterns connected by '|'
}

Tuple Patterns

A tuple pattern is used to match the values of Tuple. It is defined as multiple patterns enclosed in parentheses and separated by commas (,): (pattern_1, pattern_2, ... pattern_k). For example, (x, y, z) is a tuple pattern including three binding patterns, and (1, 0, 0) is a tuple pattern including three constant patterns. The number of sub-patterns in a tuple pattern must be the same as the dimension of selector. If the sub-patterns are constant patterns or enum patterns, their type must be the same as the type of selector dimension.

The syntax of tuple patterns is defined as follows:

tuplePattern
    : '(' pattern (',' pattern)+ ')' 
    ;

The following is an example of using tuple patterns:

let scoreTuple = ("Allen", 90)
var scoreResult: String = match (scoreTuple) { 
    case ("Bob", 90) =>  "Bob got 90"
    case ("Allen", score) =>  "Allen got ${score}" // matched
    case ("Allen", 100) | ("Bob", 100) =>  "Allen or Bob got 100"
    case (_, _) =>  ""
}

Type Patterns

The type check and type cast can be easily implemented using type patterns. The syntax of type patterns is defined as follows:

typePattern
  : (wildcardPattern | varBindingPattern) ':' type
  ;

For the type pattern varBindingPattern : type (or wildcardPattern : type): Check whether the runtime type of the value to be matched is the type defined by type on the right of : or its subtype. If the type is matched successfully, convert the value type to the defined type, and then bind the value of the new type to varBindingPattern on the left of :. (There is no binding for wildcardPattern : type.) The matching is successful only when the type is matched. Otherwise, the matching fails. Therefore, varBindingPattern : type (or wildcardPattern : type) can implement both type test and type cast.

The following is an example of type pattern matching:

open class Point { 
    var x: Int32 = 1
    var y: Int32 = 2
    init(x: Int32, y: Int32) {
        this.x = x
        this.y = y
    }
}
class ColoredPoint <: Point { 
    var color: String = "green"
    init(x: Int32, y: Int32, color: String) {
        super(x, y)
        this.color = color
    }
}
let normalPt = Point(5,10)
let colorPt = ColoredPoint(8,24,"red")
var rectangleArea1: Int32 = match (normalPt) {
    case _: Point => normalPt.x * normalPt.y  // matched
    case _ => 0
}
var rectangleArea2: Int32 = match (colorPt) {
    case cpt: Point => cpt.x * cpt.y          // matched
    case _ => 0
}

Enum Patterns

An enum pattern is used together with the enum type.

An enum pattern is used to match the enum constructor. The format is constructorName (parameterless constructor) or constructorName(pattern_1, pattern_2, ..., pattern_k) (parameterized constructor). Multiple patterns, separated by commas (,) in parentheses, match each parameter in sequence. The patterns can be of any other type and can be nested.

The syntax of enum patterns is defined as follows:

enumPattern
   : (userType '.')? identifier enumPatternParameters?
   ;
enumPatternParameters
   : '(' pattern (',' pattern)* ')'
   ;

The following is an example of enum pattern matching:

enum TimeUnit { 
    | Year(Float32)
    | Month(Float32, Float32)
    | Day(Float32, Float32, Float32)
    | Hour(Float32, Float32, Float32, Float32)
}
let oneYear = TimeUnit.Year(1.0) 
var howManyHours: Float32 = match (oneYear) {
    case Year(y) => y * Float32(365 * 24) // matched
    case Month(y, m) => y * Float32(365 * 24) + m * Float32(30 * 24)
    case Day(y, m, d) => y * Float32(365 * 24) + m * Float32(30 * 24) + d * Float32(24)
    case Hour(y, m, d, h) => y * Float32(365 * 24) + m * Float32(30 * 24) + d * Float32(24) + h
}

let twoYear = TimeUnit.Year(2.0)
var howManyYears: Float32 = match (twoYear) {
    case Year(y) | Month(y, m) => y // error: variable cannot be introduced in patterns connected by '|'
    case Year(y) | Month(x, _) => y // error: variable cannot be introduced in patterns connected by '|'
    case Year(y) | Month(y, _) => y // error: variable cannot be introduced in patterns connected by '|'
    ...
}

In the scope of pattern matching, if the identifier in a pattern is an enum constructor, the identifier is always matched as an enum pattern. Otherwise, the identifier is matched as a binding pattern.

enum Foo {
    A | B | C
}

func f() {
    let x = Foo.A
    match (x) {
        case A => 0 // enum pattern
        case B => 1 // enum pattern
        case C => 2 // enum pattern
        case D => 3 // binding pattern
    }
}

Note that the type of the enum pattern must be the same as that of the selector during matching. In addition, the compiler checks whether each constructor (including the values of the constructor parameters) of the enum type is completely overridden. If not, the compiler reports an error.

enum TimeUnit { 
    | Year(Float32)
    | Month(Float32, Float32)
    | Day(Float32, Float32, Float32) 
    | Hour(Float32, Float32, Float32, Float32)
}

let oneYear = TimeUnit.Year(1.0)
var howManyHours: Float32 = match (oneYear) { // error: match must be exhaustive
    case Year(y) => y * Float32(365 * 24)
    case Month(y, m) => y * Float32(365 * 24) + m * Float32(30 * 24)
}

Classification of Patterns

Generally, if a pattern does not match the value to be matched, the pattern is called refutable pattern. If a pattern always matches the value to be matched, the pattern is called irrefutable pattern. For the preceding patterns, the following rules are defined:

• Constant patterns are always refutable patterns.
• Wildcard patterns are always irrefutable patterns.
• Binding patterns are always irrefutable patterns.
• A tuple pattern is an irrefutable pattern only when all of its patterns are irrefutable patterns.
• Type patterns are always refutable patterns.
• An enum pattern is an irrefutable pattern only when the corresponding enum type has only one parameterized constructor, and other patterns (if any) contained in the enum pattern are irrefutable patterns.

Matching Rules of Character Strings, Bytes, and Rune

When the target of pattern matching is a value whose static type is Rune, both the Rune literal and the single-character string literal can be used as constant patterns representing Rune literals.

When the target of pattern matching is a value whose static type is Byte, a string literal representing an ASCII character can be used as a constant pattern representing the Byte literal.

Pattern Guards

To further determine the matched value, Cangjie supports pattern guard. pattern guard can be used in match expressions or for-in expressions. This section describes how to use pattern guard in match expressions. For details about how to use pattern guard in for-in expressions, see [for-in Expressions].

In match expressions, pattern guard is supported to provide a more powerful and accurate matching pattern. That is, where boolExpression is added between pattern and => (boolExpression is an expression whose value is of the Boolean type). The matching is successful only when the value matches the pattern and the boolExpression following the where is met. Otherwise, the matching fails.

The syntax of pattern guard is defined as follows:

patternGuard
    : 'where' expression 
    ;

The following is an example of using pattern guards:

let oneYear = Year(1.0) 
var howManyHours: Float32 = match (oneYear) {
    case Year(y) where y > 0.0f32 => y * Float32(365 * 24) // matched
    case Year(y) where y <= 0.0f32 => 0.0
    case Month(y, m) where y > 0.0f32 && m > 0.0f32 => y * Float32(365 * 24) + m * Float32(30 * 24)
    case Day(y, m, d) where y > 0.0f32 && m > 0.0f32 && d > 0.0f32 => y * Float32(365 * 24) + m * Float32(30 * 24) + d * Float32(24)
    case Hour(y, m, d, h) where y > 0.0f32 && m > 0.0f32 && d > 0.0f32 && h > 0.0f32 => y * Float32(365 * 24) + m * Float32(30 * 24) + d * Float32(24) + h
    case _ => 0.0
}

Loop Expressions

Cangjie supports three types of loop expressions: for-in, while, and do-while.

The syntax of loop expressions is defined as follows:

loopExpression
  : forInExpression
  | whileExpression
  | doWhileExpression
  ;

for-in Expressions

A complete for-in expression has the following form:

for (p in e where c) {
    s
}

pattern guard where c is optional. Therefore, a simpler format of for-in expressions is as follows:

for (p in e) {
    s
}

The syntax of for-in expressions is defined as follows:

forInExpression
    : 'for' '(' patternsMaybeIrrefutable 'in' expression patternGuard? ')' block
    ;
    
patternsMaybeIrrefutable
    : wildcardPattern
    | varBindingPattern
    | tuplePattern
    | enumPattern
    ;

patternGuard
    : 'where' expression
    ;

In the preceding syntax definition, the keyword for can be followed only by patterns that must or may be irrefutable (see [Classification of Patterns]). In semantic check, the system checks whether the patterns following for are irrefutable. If not, an error is reported during compilation. In addition, if the patterns after for contain any binding pattern, it is equivalent to declaring one (or more) let variables. The scope of each variable starts from the position where the variable appears for the first time to the end of the loop body.

for-in evaluates expression and then calls its iterator() function to obtain a value of the Iterator<T> type. The program starts to execute the loop by calling the next() function of Iterator<T>. You can use patterns to match the iteration elements. If the matching is successful (if patternGuard exists, its conditions must also be met), the loop body block is executed, and then next() is called again at the beginning to continue the loop, when next() returns None, the loop ends.

You can query Iterable<T> and Iterator<T> in the standard library.

main(): Int64 {
    let intArray: Array<Int32> = [0, 1, 2, 3, 4]
    for (item in intArray) {
        print(item)          // output: 01234
    }

    let intRange = 0..5
    for (number in intRange where number > 2) {
        print(number)        // output: 34
    }

    return 0
}

while Expressions

The syntax of while expressions is defined as follows:

whileExpression
    : 'while' '(' ('let' deconstructPattern '<-')? expression ')' block
    ;

The syntax includes the keyword while, parentheses that enclose an expression or a deconstruction match declared by let, and a block.

The following is an example of a basic while expression:

main(): Int64 {
    var hundred = 0
    while (hundred < 100) { // until hundred = 100
        hundred++
    }
    return 0
}

In the while expression, the expression following while (the expression type must be Bool) is first evaluated. If the value of the expression is true, the block following the expression is executed. Then, the expression value is recalculated and whether to execute the loop again is determined. If the value of the expression is false, the loop is terminated.

A while expression that contains let is called a while-let expression. You can use the while-let expression to perform some simple deconstruction operations.

The following is an example of a basic while-let expression:

main(): Int64 {
    var x: Option<Int64> = Option<Int64>.Some(100)
    // while-let expression
    while (let Some(v) <- x) { 
        print("x has value")
        x = ...
    }
    return 0 
}

In the while-let expression, the expression following <- (the expression type can be any type) is first evaluated. If the value of the expression matches the pattern following let, the block following the expression is executed. Then, the value of the expression is recalculated and matched again to determine whether to execute a loop again. If the matching fails, the current while loop is terminated.

The patterns following let can be constant, wildcard, binding, tuple, or enum patterns.

do-while Expressions

The syntax of do-while expressions is defined as follows:

doWhileExpression
    : 'do' block 'while' '(' expression ')' 
    ;

Different from the while expression, if the value of expression is false during the first loop iteration of the while expression, the loop body is not executed. However, for the do-while expression, during the first loop iteration, the loop body block is executed first, and then whether to execute the loop body again is determined based on the value of expression. That is, the loop body in the do-while expression is executed at least once. Example:

main(): Int64 {
    var hundred = 0
    do {
        hundred++
    } while (hundred < 100)
    return 0
}

Summary of Loop Expressions

The expression capabilities of the for-in, while, and do-while expressions are equivalent. Generally, if the number of loops is known or all elements in a sequence are traversed, for-in expressions are used. If the number of loops is unknown but the loop termination condition is known, while or do-while expressions are used.

The three loop expressions are of the Unit type.

The break and continue expressions must have their loop bodies. Therefore, for the three types of loop expressions, break or continue in the loop condition is bound to the nearest outer loop. If the outer loop does not exist, an error is reported. For example:

while (true) {
	println("outer") // printed once
	do {
		println("inner") // printed once
	} while (break)  // stop the execution of the outer loop
	println("unreached") // not printed
}

try Expressions

The try expressions are classified into ordinary try expressions that do not involve automatic resource management and try-with-resources expressions that involve automatic resource management.

The syntax of try expressions is as follows:

tryExpression
    : 'try' block 'finally' block
    | 'try' block ('catch' '(' catchPattern ')' block)+ ('finally' block)?
    | 'try' '(' resourceSpecifications ')' block ('catch' '(' catchPattern ')' block)* ('finally' block)?
    ;

Ordinary try expressions are used for error handling. For details, see chapter [Exceptions].

The try-with-resources expression is used to automatically release non-memory resources. For details, see chapter [Exceptions].

Control Transfer Expressions

Control transfer expressions change the execution sequence of programs. The type of control transfer expressions is Nothing, which is a subtype of any type. Cangjie provides the following control transfer expressions:

• break
• continue
• return
• throw

Like any other expression, a control transfer expression can be used as a subexpression to become a part of a complex expression, but may cause unreachable code (a compilation alarm will be generated for the unreachable part).

main(): Int64 {
    return return 1 // warning: the left return expression is unreachable
}

In the control transfer expression, break and continue must have their surrounding loop bodies, and the loop bodies cannot cross the function boundary. return must have its surrounding function body, and the function body cannot cross the function boundary. There is no requirement on throw.

A surrounding loop body "cannot cross" the function boundary. In the following example, break appears in the f function, and the outer while loop body is not considered as the loop body that surrounds break. continue appears in the lambda expression, and the outer while loop body is not considered as the loop body that surrounds continue.

while (true) {
    func f() {
        break // Error: break must be used directly inside a loop
    }
    let g = { =>
        continue // Error: continue must be used directly inside a loop
    }
}

The syntax of control transfer expressions is as follows:

jumpExpression
  : 'break'
  | 'continue'
  | 'return' expression?
  | 'throw'  expression
  ;

break Expressions

A break expression can be used only in the loop body of a loop expression, and the execute permission of the program is granted to the expression after the terminated loop expression. For example, the following code uses a break expression in the while loop body to calculate the least common multiple of 4 and 6 in the interval [1,49].

main(): Int64 {
    var index: Int32 = 0
    while (index < 50) {
        index = index + 1
        if ((index % 4 == 0) && (index % 6 == 0)) {
            print("${index} is divisible by both 4 and 6") // output: 12
            break
        }
    }
    return 0
}

Note that when break appears in a nested loop expression, only the loop expression that directly surrounds it can be terminated. The outer loop is not affected. For example, the following program outputs 12 is divisible by both 4 and 6 for five times and outputs the value of i each time:

main(): Int64 {
    var index: Int64 = 0
    for (i in 0..5) {
        index = i
        while (index < 20) {
            index = index + 1
            if ((index % 4 == 0) && (index % 6 == 0)) {
                print("${index} is divisible by both 4 and 6")
                break
            }    
        }
        print("${i}th test")
    }
    return 0
}

continue Expressions

A continue expression can be used only in the loop body of a loop expression. It ends the current iteration of the closest loop expression in advance and then start a new round of loop (the loop expression is not terminated). For example, in the following code output range [1,49], all numbers (12, 24, 36, and 48) that can be exactly divided by both 4 and 6 are output. Other numbers that do not meet the requirements are also explicitly output.

main(): Int64 {
    var index: Int32 = 0
    while (index < 50) {
        index = index + 1
        if ((index % 4 == 0) && (index % 6 == 0)) {
            print("${index} is divisible by both 4 and 6")
            continue
        }
        print("${index} is not what we want")
    }
    return 0
}

return Expressions

A return expression can be used only in the function body. It can terminate the execution of a function at any position and return a value, transferring the control flow from the called function to the calling function. A return statement can be in the following two formats: return and return expr (expr indicates an expression).

• If an expression is in return expr format, the value of expr is the return value of the function. Therefore, the type of expr must be the same as the return type in the function definition.

// return expression
func larger(a: Int32, b: Int32): Int32 {
    if (a >= b) {
        return a
    } else {
        return b
    }
}

• If an expression is in return format, it is considered as the syntactic sugar of return(). Therefore, the return type of the function must also be Unit.

// return expression
func equal(a: Int32, b: Int32): Unit {
    if (a == b) { 
        print("a is equal to b")
        return
    } else {
        print("a is not equal to b")
    }     
}

It should be noted that, the type of the return expression as a whole is not determined by its following expression (the expression following return is ()), but is of the Nothing type.

throw Expressions

The throw expressions throw exceptions. When a code block that contains a throw expression is called, if the throw expression is executed, the corresponding exception is thrown. The predefined exception handling logic captures and processes the exception, changing the program execution process.

In the following example, an arithmetic exception is thrown when the divisor is 0:

func div(a: Int32, b: Int32): Int32 {
    if (b != 0) {
        return a / b
    } else {
        throw ArithmeticException()
    }     
}

This section provides only the simplest examples of the return and throw expressions. For details, see chapters [Functions] and [Exceptions].

Numeric Type Conversion Expressions

A numeric type conversion expression implements conversion between numeric types. It adopts the value and the target type (the type of the original expression is not affected by the target type) after type conversion. For details about the conversion rules, see [Type Conversion].

The syntax of numeric type conversion expressions is defined as follows:

numericTypeConvExpr
    : numericTypes '(' expression ')'
    ;
    
numericTypes
    : 'Int8'
    | 'Int16'
    | 'Int32'
    | 'Int64'
    | 'UInt8'
    | 'UInt16'
    | 'UInt32'
    | 'UInt64'
    | 'Float16'
    | 'Float32'
    | 'Float64'
    ;

this and super Expressions

The this and super expressions are represented by this and super respectively. this can appear in all instance member functions and constructors, indicating the current instance. super can appear only in the class definitions, indicating the instance of the direct superclass of the currently defined type (For details, see [Classes]). Do not use an independent super expression.

The syntax of this and super expressions is defined as follows:

thisSuperExpression
    : 'this'
    | 'super'
    ;

spawn Expressions

A spawn expression creates and starts a thread. For details, see [Concurrency].

synchronized Expressions

The synchronized expressions are used in the synchronization mechanism. For details, see [Concurrency].

Parenthesized Expressions

A parenthesized expression is an expression enclosed in parentheses. The subexpression enclosed in parentheses is considered as a separate calculation unit and is preferentially calculated.

The syntax of parenthesized expressions is defined as follows:

parenthesizedExpression
    : '(' expression ')'
    ;

Example of a parenthesized expression:

1 + 2 * 3 - 4    // The result is 3.
(1 + 2) * 3 - 4  // The result is 5.

Postfix Expressions

A postfix expression consists of an expression and a postfix operator. Based on operators, postfix expressions are classified into member access expressions, function call expressions, and index access expressions. When the optional ? operator is used before their operators, the Option type can support these operators. For details about the ? operator, see the following description.

The syntax of postfix expressions is defined as follows:

postfixExpression
    : atomicExpression
    | type '.' identifier
    | postfixExpression '.' identifier typeArguments?
    | postfixExpression callSuffix
    | postfixExpression indexAccess
    | postfixExpression '.' identifier callSuffix? trailingLambdaExpression
    | identifier callSuffix? trailingLambdaExpression
    | postfixExpression ('?' questSeperatedItems)+
    ;

Member Access Expressions

The syntax of member access expressions is defined as the third item of the preceding postfix expression syntax:

postfixExpression '.' identifier typeArguments?

Member access expressions can be used to access members of a class, interface, and struct.

A member access expression is in the format of T.a. T indicates a specific instance or type name, which is called the body of the member access expression. a indicates the name of a member.

• If T is an instantiated object of a class, non-static members in the class or interface can be accessed in this way.

• If T is an instance of struct, non-static members in struct can be accessed by instance name.

• If T is the name of a class, interface, or struct, its static members can be accessed directly by type name.

Note that the access subject of static members of the class, interface, and struct can only be type names.

• T is this: In the scope of a class or interface, the this keyword can be used to access non-static members.

• T is super: In the scope of a class or interface, the super keyword can be used to access the non-static members of the superclass of the current class object.

For a member access expression e.a, if e is a type name:

• When a is a mutable static member variable of e, e.a is mutable. In other cases, e.a is immutable.

If e is an expression (assuming that the type of e is T):

• When T is of the reference type, if a is a mutable instance member variable of T, e.a is mutable. Otherwise, e.a is immutable.

• When T is of the value type, if e is mutable and a is a mutable instance member variable of T, e.a is mutable. Otherwise, e.a is immutable.

Function Call Expressions

The syntax of function call expressions is defined as the fourth item of the preceding postfix expression syntax. The syntax of callSuffix and valueArgument is defined as follows:

callSuffix
    : '(' (valueArgument (',' valueArgument)*)? ')'
    ;
    
valueArgument
    : identifier ':' expression
    | expression
    | refTransferExpression
    ;

refTransferExpression
    : 'inout' (expression '.')? identifier
    ;

Function call expressions are used to call functions. For details about functions, see [Functions].

For the function call expression f(x), assume that the type of f is T. If T is of the function type, the function named f is called. Otherwise, if T overloads the function call operator (), f(x) calls its operator overloading function () (see [Operators That Can Be Overloaded]).

Index Access Expressions

The syntax of index access expressions is defined as the fifth item of the preceding postfix expression syntax. The syntax of indexAccess is defined as follows:

indexAccess
    : '[' (expression | rangeElement) ']'
    ;

rangeElement
    :  '..'
    | ('..=' | '..' ) expression
    | expression '..'
    ;

Index access expressions are used for types that support index access (including the Array and Tuple types) to access elements in specific locations through indexes. For details, see [Array] and [Tuple] in [Types].

For the index access expression e[a] (assuming that the type of e is T):

• If T is of the Tuple type, e[a] is immutable.

• If T is not of the Tuple type and it overloads the [] operator in set form (see [Operators That Can Be Overloaded]), e[a] is mutable. Otherwise, e[a] is immutable.

For the index access expression e1[e2], the Cangjie language always evaluates e1 to v1, then evaluates e2 to v2, and finally selects the corresponding value based on the index v2 or calls the corresponding overloaded [] operator.

Question Mark Operators

The question mark operator ? is a unary postfix operator. It must be used together with and before the postfix operators ., (), {}, or [] described above to enable the Option type to support these postfix operators, such as a?.b, a?(b), and a?[b]. () is used for function call. When the last argument of the function call is lambda, the tailing closure syntax a?{b} can be used. An expression that contains ?., ?(), ?{}, or ?[] is called an optional chaining expression.

The syntax of optional chaining expressions is defined as the last item of the preceding postfix expression syntax. The syntax of questSeperatedItems is defined as follows:

questSeperatedItems
    : questSeperatedItem+
    ;

questSeperatedItem
    : itemAfterQuest (callSuffix | callSuffix? trailingLambdaExpression | indexAccess)?
    ;

itemAfterQuest
    : '.' identifier typeArguments?
    | callSuffix
    | indexAccess
    | trailingLambdaExpression
    ;

The rules for the optional chaining expressions are as follows:

1. For the expression e, delete all ? in e, change the type of the expression right before ? from Option<T> to T, and obtain the expression e1. If the type of e1 is Option, add ? between e and ., (), {}, or [] when using these operators after e. Otherwise, do not add ?.

2. The type of an optional chaining expression is Option<T> (That is, no matter how many ? operators exist, the type has only one layer of Option). The type T is that of the last expression (variable or function name, function call expression, or index access expression) in the optional chaining expression.

3. If the value of an expression of the Option type in the optional chaining expression is None, the value of the entire optional chaining expression is None. If the value of each expression of the Option type in the optional chaining expression is equal to a Some value, the value of the entire expression is Some(v) (the type of v is that of the last expression).

The following examples use the expressions a?.b, c?(d), and e?[f]:

1. The expression a must be of an Option<T1> type, and T1 must contain the instance member b. The expression c must be of an Option<(T2)->U2> type, and the type of d must be T2. The expression e must be of an Option<T3> type, and T3 supports index operators.

2. The types of expressions a?.b, c?(d), and e?[f] areOption<U1>, Option<U2>, and Option<U3>, whereU1 is the type of the instance member b in T1, U2 is the return value type of the function type (T2)->U2, and U3 is the return type of the index operation performed by T3.

3. When the values of a, c, and e are Some(v1), Some(v2), and Some(v3), respectively, the values of a?.b, c?(d), and e?[f] are Option<U1>.Some(v1.b), Option<U2>.Some(v2(d)), and Option<U3>.Some(v3[f]), respectively. When the values of a, c, and e are None, the values of a?.b, c?(d), and e?[f] are Option<U1>.None, Option<U2>.None, and Option<U3>.None, respectively. (Note that b, d, and f are not evaluated.)

The expressions a?.b, c?(d), and e?[f] are equivalent to the following match expressions respectively:

// a?.b is equivalent to the following match expression.
match (a) {
    case Some(v) => Some(v.b)
    case None => None<U1>
}

// c?(d) is equivalent to the following match expression.
match (c) {
    case Some(v) => Some(v(d))
    case None => None<U2>
}

// e?[f] is equivalent to the following match expression.
match (e) {
    case Some(v) => Some(v[f])
    case None => None<U3>
}

The next example contains multiple ? in the multi-layer access expression a?.b.c?.d (?. is an example that can be applied in other operations in similar ways.)

1. The a expression must be of an Option<Ta> type, and Ta must contain the instance member b. The type of b must contain the instance member variable c, and c must be of an Option<Tc> type. Tc must contain the instance member d.

2. The type of the expression a?.b.c?.d is Option<Td>, where Td is the type of the instance member d of Tc.

3. When the value of a is equal to Some(va) and that of va.b.c is equal to Some(vc), the value of a?.b.c?.d is equal to Option<Td>.Some(vc.d). When the value of a is equal to Some(va) and that of va.b.c is equal to None, the value of a?.b.c?.d is equal to Option<Td>.None (d is not evaluated). When the value of a is equal to None, the value of a?.b.c?.d is equal to Option<Td>.None (b, c, and d are not evaluated).

The expression a?.b.c?.d is equivalent to the following match expression:

// a?.b.c?.d is equivalent to the following match expression.
match (a) {
    case Some(va) =>
        let x = va.b.c
        match (x) {
            case Some(vc) => Some(vc.d)
            case None => None<Td>
        }
    case None =>
        None<Td>
}

Optional chaining expressions can also be used as lvalue expressions (see [Assignment Expressions]), such as a?.b = e1, a?[b] = e2, and a?.b.c?.d = e3.

If an optional chaining expression is on the left of an assignment expression, the former must be mutable (For details, see [Assignment Expressions]). Because the function type is immutable, only ?. and ?[] need to be considered. Both of them fall into two basic scenarios: a?.b = c and a?[b] = c (assuming that the type of a is Option<T>). The rules are as follows:

• a?.b is mutable only when T is of the reference type and b is mutable. In other cases, a?.b is immutable.

• a?[b] is mutable only when T is of the reference type and [] in set mode is overloaded. In other cases, a?[b] is immutable.

When a?.b (or a?[b]) is mutable, if the value of a is equal to Option<T>.Some(v), assign the value of c to v.b (or v[b]); if the value of a is equal to Option<T>.None, do not perform any operation (b and c are not evaluated).

Similarly, the expressions a?.b = e1, a?[b] = e2, and a?.b.c?.d = e3 are equivalent to the following match expressions:

// a?.b = e1 is equivalent to the following match expression.
match (a) {
    case Some(v) => v.b = e1
    case None => ()
}

// a?[b] = e2 is equivalent to the following match expression.
match (a) {
    case Some(v) => v[b] = e2
    case None => ()
}

// a?.b.c?.d = e3 is equivalent to the following match expression.
match (a) {
    case Some(va) => 
        match (va.b.c) {
            case Some(vc) => vc.d = e3
            case None => ()
        }
    case None => 
    	()
}

The following example is how the ? operator is used:

// The usuage of ?.
class C {
    var item: Int64 = 100
}
let c = C()
let c1 = Option<C>.Some(c)
let c2 = Option<C>.None
let r1 = c1?.item              // r1 = Option<Int64>.Some(100)
let r2 = c2?.item              // r2 = Option<Int64>.None
func test1() {
    c1?.item = 200             // c.item = 200
    c2?.item = 300             // no effect
}

// The usuage of ?()
let foo = {i: Int64 => i + 1}
let f1 = Option<(Int64) -> Int64>.Some(foo)
let f2 = Option<(Int64) -> Int64>.None
let r3 = f1?(1)               // r3 = Option<Int64>.Some(2)
let r4 = f2?(1)               // r4 = Option<Int64>.None

// The usuage of ?[] for tuple access
let tuple = (1, 2, 3)
let t1 = Option<(Int64, Int64, Int64)>.Some(tuple)
let t2 = Option<(Int64, Int64, Int64)>.None
let r7 = t1?[0]               // r7 = Option<Int64>.Some(1)
let r8 = t2?[0]               // r8 = Option<Int64>.None
func test3() {
    t1?[0] = 10               // error: 't1?[0]' is immutable
    t2?[1] = 20               // error: 't2?[0]' is immutable
}

Increment and Decrement Expressions

Increment and decrement expressions are expressions that contain increment operators (++) or decrement operators (--). a++ and a-- are syntactic sugars of a+=1 and a-=1, respectively. The increment and decrement operators add 1 to and subtract 1 from values, and can be used only as postfix operators. ++ and -- are non-associative. Therefore, it is (syntactically) forbidden that an expression contains two or more ++/-- operators, such as a++-- but does not use parentheses to specify the calculation sequence.

The syntax of increment and decrement expressions is defined as follows:

incAndDecExpression
    : postfixExpression ('++' | '--' )
    ;

The rules for expr++ (or expr--) expression are as follows:

1. The type of expr must be integer.

2. Because expr++ (or expr--) is the syntactic sugar of expr += 1 (or expr -= 1), expr must also be assignable (see [Assignment Expressions]).

3. The type of expr++ (or expr--) is Unit.

The following examples are the increment and decrement expressions:

var i: Int32 = 5
i++     // i = 6
i--     // i = 5
i--++   // syntax error
var j = 0
j = i-- // semantics error

Arithmetic Expressions

An arithmetic expression is an expression that contains arithmetic operators. Cangjie supports the following arithmetic operators: unary minus sign (-), addition (+), subtraction (-), multiplication (*), division (/), modulo (%), and exponentiation (**). Except that the unary minus sign is a unary prefix operator, other operators are binary infix operators. Their precedence and associativity are described below.

The syntax of arithmetic expressions is defined as follows:

prefixUnaryExpression
    : prefixUnaryOperator* incAndDecExpression
    ;
    
prefixUnaryOperator
    : '-'
    | ...
    ;

additiveExpression
    : multiplicativeExpression (additiveOperator multiplicativeExpression)*
    ;

multiplicativeExpression
    : exponentExpression (multiplicativeOperator exponentExpression)*
    ;

exponentExpression
    : prefixUnaryExpression (exponentOperator prefixUnaryExpression)*
    ;
    
additiveOperator
    : '+' | '-' 
    ;

multiplicativeOperator
    : '*' | '/' | '%' 
    ;

exponentOperator
    : '**' 
    ;

The operand of the unary minus sign (-) must be an expression of the numeric type. The value of the unary prefix minus sign expression is equal to the negated value of the operand. The type is the same as that of the operand.

let num1: Int64 = 8 
let num2 = -num1      // num2 = -8, with 'Int64' type
let num3 = -(-num1)   // num3 =  8, with 'Int64' type

For binary operators *, /, %, +, and -, the two operands must be of the same type. The operand of % can only be an integer. The operands of *, /, +, and - can be of any numeric type.

let a = 2 + 3       // add:      5
let b = 3 - 1       // sub:      2
let c = 3 * 4       // multi:   12
let d = 6.6 / 1.1   // division: 6
let e = 4 % 3       // mod:      1

In particular, when the operand of the division (/) is an integer, the non-integer value is rounded to an integer, rounding toward 0. The value of the integer modulo operation a % b is defined as a - b * (a / b).

let q1 =  7 /  3    // integer division:   2
let q2 = -7 /  3    // integer division:  -2
let q3 =  7 / -3    // integer division:  -2
let q4 = -7 / -3    // integer division:   2
let r1 =  7 %  3    // integer remainder:  1
let r2 = -7 %  3    // integer remainder: -1
let r3 =  7 % -3    // integer remainder:  1
let r4 = -7 % -3    // integer remainder: -1

** indicates the exponentiation operation. For example, x**y indicates that the y exponent of the base x is calculated. The left operand of ** must be of the Int64 or Float64 type.

1. When the left operand is of the Int64 type, the right operand must be of the UInt64 type, and the expression type must be Int64.

2. When the left operand is of the Float64 type, the right operand must be of the Int64 or Float64 type, and the expression type must be Float64.

let p1 = 2 ** 3               // p1 = 8
let p2 = 2 ** UInt64(3 ** 2)  // p2 = 512
let p3 = 2.0 ** 3             // p3 = 8.0
let p4 = 2.0 ** 3 ** 2        // p4 = 512.0
let p5 = 2.0 ** 3.0           // p5 = 8.0
let p6 = 2.0 ** 3.0 ** 2.0    // p6 = 512.0

When the left operand type is Float64 and the right operand type is Int64, the value of the exponentiation expression needs to be specified in some special cases as follows:

x ** 0 = 1.0                               // for any x
0.0 ** n = POSITIVE_INFINITY               // for odd n < 0
-0.0 ** n = NEGATIVE_INFINITY              // for odd n < 0
0.0 ** n = POSITIVE_INFINITY               // for even n < 0
-0.0 ** n = POSITIVE_INFINITY              // for even n < 0
0.0 ** n = 0.0                             // for even n > 0
-0.0 ** n = 0.0                            // for even n > 0
0.0 ** n = 0.0                             // for odd n > 0
-0.0 ** n = -0.0                           // for odd n > 0
POSITIVE_INFINITY ** n = POSITIVE_INFINITY // for n > 0
NEGATIVE_INFINITY ** n = NEGATIVE_INFINITY // for odd n > 0
NEGATIVE_INFINITY ** n = POSITIVE_INFINITY // for even n > 0
POSITIVE_INFINITY ** n = 0.0               // for n < 0
NEGATIVE_INFINITY ** n = -0.0              // for odd n < 0
NEGATIVE_INFINITY ** n = 0.0               // for even n < 0.

Note: In addition to the preceding special cases, when the value of the left operand is NaN, the value of the exponentiation expression is equal to NaN regardless of the value of the right operand.

When the left operand type is Float64 and the right operand type is Float64, the value of the exponentiation expression needs to be specified in some special cases as follows:

x ** 0.0 = 1.0                              // for any x
x ** -0.0 = 1.0                             // for any x
0.0 ** y = POSITIVE_INFINITY                // for the value of y is equal to an odd integer < 0 
-0.0 ** y = NEGATIVE_INFINITY               // for the value of y is equal to an odd integer < 0 
0.0 ** NEGATIVE_INFINITY = POSITIVE_INFINITY 
-0.0 ** NEGATIVE_INFINITY = POSITIVE_INFINITY 
0.0 ** POSITIVE_INFINITY = 0.0 
-0.0 ** POSITIVE_INFINITY = 0.0 
0.0 ** y = 0.0                             // for finite y > 0.0 and its value is equal to an odd integer 
-0.0 ** y = -0.0                           // for finite y > 0.0 and its value is equal to an odd integer 
-1.0 ** POSITIVE_INFINITY = 1.0
-1.0 ** NEGATIVE_INFINITY = 1.0
1.0 ** y = 1.0                             // for any y 
x ** POSITIVE_INFINITY = 0.0               //  for -1.0 < x < 1.0
x ** POSITIVE_INFINITY = POSITIVE_INFINITY // for any x < -1.0 or for any x > 1.0
x ** NEGATIVE_INFINITY = POSITIVE_INFINITY // for -1.0 < x < 1.0 
x ** NEGATIVE_INFINITY = 0.0               // for any x < -1.0 or for any x > 1.0 
POSITIVE_INFINITY ** y = 0.0               // for y < 0.0 
POSITIVE_INFINITY ** y = POSITIVE_INFINITY // for y > 0.0 
NEGATIVE_INFINITY ** y = -0.0              // for finite y < 0.0 and its value is equal to an odd integer 
NEGATIVE_INFINITY ** y = NEGATIVE_INFINITY // for finite y > 0.0 and its value is equal to an odd integer 
NEGATIVE_INFINITY ** y = 0.0               // for finite y < 0.0 and its value is not equal to an odd integer 
NEGATIVE_INFINITY ** y = POSITIVE_INFINITY // for finite y > 0.0 and its value is not equal to an odd integer
0.0 ** y = POSITIVE_INFINITY               // for finite y < 0.0 and its value is not equal to an odd integer 
-0.0 ** y = POSITIVE_INFINITY              // for finite y < 0.0 and its value is not equal to an odd integer 
0.0 ** y = 0.0                             // for finite y > 0.0 and its value is not equal to an odd integer
-0.0 ** y = 0.0                            // for finite y > 0.0 and its value is not equal to an odd integer
x ** y = NaN                               // for finite x < 0.0 and finite y whose value is not equal to an integer

Note: In addition to the special cases listed above, if the value of an operand is NaN, the value of the exponentiation expression is equal to NaN.

If the result of an arithmetic expression is of the integer type, integer overflow may occur. Cangjie provides three attribute macros and compilation options to control the processing behavior of integer overflow (hereinafter referred to as behavior). They are shown in the following table.

Note: 1. The default behavior is throwing. 2. If an attribute macro and a compilation option are used in a range at the same time and represent different behaviors, the behavior represented by the attribute macro prevails.

Behavior example:

@OverflowThrowing
func test1(x: Int8, y: Int8) { // if x equals to 127 and y equals to 3
    let z = x + y // throwing OverflowException
}

@OverflowWrapping
func test2(x: Int8, y: Int8) { // if x equals to 127 and y equals to 3
    let z = x + y // z equals to -126
}

@OverflowSaturating
func test3(x: Int8, y: Int8) { // if x equals to 127 and y equals to 3
    let z = x + y // z equals to 127
}

The following is an example of the conflict between the scope of an attribute macro and that of a compilation option:

// Compile with cjc --int-overflow saturating test.cj
// this file's name is test.cj

@OverflowWrapping
func test2(x: Int8, y: Int8) { 
    let z = x + y // the behavior is wrapping
}

func test3(x: Int8, y: Int8) { 
    let z = x + y // the behavior is saturating
}

In particular, for INT_MIN * -1, INT_MIN / -1, and INT_MIN % -1, the specified behaviors are as follows:

Note that in the scenario where the integer overflow behavior is throwing, if the integer overflow can be detected in advance in the compilation phase, the compiler directly reports an error.

Relational Expressions

A relational expression is an expression that contains relational operators. There are six relational operators: equality (==), inequality (!=), less than (<), greater than (<=), less than or equal to (>), and greater than or equal to (>=). Relational operators are binary operators, and the types of the two operands must be the same. A relational expression is of the Bool type. That is, its value can only be true or false. Precedence and associativity of relational operators are described below.

The syntax of relational expressions is defined as follows:

equalityComparisonExpression
    : comparisonOrTypeExpression (equalityOperator comparisonOrTypeExpression)?
    ;

comparisonOrTypeExpression
    : shiftingExpression (comparisonOperator shiftingExpression)?
    | ...
    ;
    
equalityOperator
    : '!=' | '=='
    ;
    
comparisonOperator
    : '<' | '>' | '<=' | '>='
    ;

The following examples are relational expressions:

main(): Int64 {
    3 < 4         // return true
    3 <= 3        // return true
    3 > 4         // return false
    3 >= 3        // return true
    3.14 == 3.15  // return false
    3.14 != 3.15  // return true
    return 0
}

It should be noted that a relational operator is non-associative, that is, an expression similar to a < b < c cannot be written.

main(): Int64 {
    3 < 4 < 5      // error: `<` is non-associative 
    3 == 3 != 4    // error: `==` and `!=` are non-associative 
    return 0
}

type test and type cast Expressions

A type test expression is an expression that contains the operator is, and a type cast expression is an expression that contains the operator as. The precedence and associativity of is and as are described below.

The syntax of type test and type cast expressions is defined as follows:

comparisonOrTypeExpression
    : ...
    | shiftingExpression ('is' type)?
    | shiftingExpression ('as' userType)?
    ;

is Operators

e is T is an expression used for type checking. The type of e is T is Bool. e can be any type of expression, and T can be any type.

When the runtime type R of e is a subtype of T, the value of e is T is true; otherwise, the value is false.

The following are examples of is operators:

open class Base {
    var name: String = "Alice"
}
class Derived1 <: Base {
    var age: UInt8 = 18
}
class Derived2 <: Base {
    var gender: String = "female"
}

main(): Int64 {
    
    var testVT = 1 is Int64            // testVT = true
    testVT = 1 is String               // testVT = false
    testVT = true is Int64             // testVT = false
    testVT = [1, 2, 3] is Array<Int64> // testVT = true

    let base1: Base = Base()
    let base2: Base = Derived1()
    let base3: Base = Derived2()

    let derived1: Derived1 = Derived1()
    let derived2: Derived2 = Derived2()

    var test = base1 is Base          // test = true
    test = base1 is Derived1          // test = false
    test = base1 is Derived2          // test = false
    test = base2 is Base              // test = true
    test = base2 is Derived1          // test = true
    test = base2 is Derived2          // test = false
    test = base3 is Base              // test = true
    test = base3 is Derived1          // test = false
    test = base3 is Derived2          // test = true

    test = derived1 is Base           // test = true
    test = derived1 is Derived1       // test = true
    test = derived1 is Derived2       // test = false
    test = derived2 is Base           // test = true
    test = derived2 is Derived1       // test = false
    test = derived2 is Derived2       // test = true

    return 0
}

as Operators

e as T is an expression used for type conversion. The type of e as T is Option<T>. e can be any type of expression, and T can be any specific type.

When the runtime type R of e is a subtype of T, the value of e as T is Some(e); otherwise, the value is None.

The following are examples of as operators:

open class Base {
    var name: String = "Alice"
}
class Derived1 <: Base {
    var age: UInt8 = 18
}
class Derived2 <: Base {
    var gender: String = "female"
}

main(): Int64 {
    let base1: Base = Base()
    let base2: Base = Derived1()
    let base3: Base = Derived2()

    let derived1: Derived1 = Derived1()
    let derived2: Derived2 = Derived2()
    
    let castOP1 = base1 as Base			// castOP = Option<Base>.Some(base1)
    let castOP2 = base1 as Derived1		// castOP = Option<Derived1>.None
    let castOP3 = base1 as Derived2		// castOP = Option<Derived2>.None
    let castOP4 = base2 as Base			// castOP = Option<Base>.Some(base2)
    let castOP5 = base2 as Derived1		// castOP = Option<Derived1>.Some(base2)
    let castOP6 = base2 as Derived2		// castOP = Option<Derived2>.None
    let castOP7 = base3 as Base			// castOP = Option<Base>.Some(base3)
    let castOP8 = base3 as Derived1		// castOP = Option<Derived1>.None
    let castOP9 = base3 as Derived2		// castOP = Option<Derived2>.Some(base3)

    let castOP10 = derived1 as Base		// castOP = Option<Base>.Some(derived1)
    let castOP11 = derived1 as Derived1	// castOP = Option<Derived1>.Some(derived1)
    let castOP12 = derived1 as Derived2	// castOP = Option<Derived2>.None
    let castOP13 = derived2 as Base		// castOP = Option<Base>.Some(derived2)
    let castOP14 = derived2 as Derived1	// castOP = Option<Derived1>.None
    let castOP15 = derived2 as Derived2	// castOP = Option<Derived2>.Some(derived2)

    return 0
}

Bitwise Operation Expression

A bitwise expression is an expression that contains bitwise operators. Cangjie supports one unary prefix bitwise operation operator bitwise NOT (!) and five binary infix bitwise operation operators, including left shift (<<), right shift (>>), bitwise AND (&), and bitwise XOR (^), and bitwise OR (|). The operands of bitwise operators must be of the integer type. The operands are considered as binary sequences, and then logical operations (0 is considered as false and 1 is considered as true) or shift operations are performed on each bit to implement bitwise operations. In operations with &, ^, and |, logical operations are performed between bits (For details, see [Logical Expressions]). The precedence and associativity of bitwise operators are described below.

The syntax of bitwise operation expressions is defined as follows:

prefixUnaryExpression
    : prefixUnaryOperator* incAndDecExpression
    ;
    
prefixUnaryOperator
    : '!'
    | ...
    ;

bitwiseDisjunctionExpression
    : bitwiseXorExpression ( '|' bitwiseXorExpression)*
    ;

bitwiseXorExpression
    : bitwiseConjunctionExpression ( '^' bitwiseConjunctionExpression)*
    ;

bitwiseConjunctionExpression
    : equalityComparisonExpression ( '&' equalityComparisonExpression)*
    ;
    
shiftingExpression
    : additiveExpression (shiftingOperator additiveExpression)*
    ;

shiftingOperator
    : '<<' | '>>'
    ;

The following are example of bitwise operation expressions:

func foo(): Unit {
    !10             // The result is -11
    !20             // The result is -21
    10 << 1         // The result is 20
    10 << 1 << 1    // The result is 40
    10 >> 1         // The result is 5
    10 & 15         // The result is 10
    10 ^ 15         // The result is 5
    10 | 15         // The result is 15
    1 ^ 8 & 15 | 24 // The result is 25
}

For a shift operator, its operand must be of the integer type (but the types of the two operands can be different). Regardless of whether the operator is left or right shift, the right operand cannot be a negative number. (If such an error is detected during compilation, an error is reported. If this error occurs during running, an exception is thrown.)

For a shift operation of an unsigned number, the shift and padding rules are as follows: left shift pads 0s for low bits and discards high bits, and right shift pads 0s for high bits and discards low bits. For a shift operation of a signed number, the shift and padding rules are as follows:

1. The shift padding rules for positive numbers and unsigned numbers are the same.
2. If negative numbers are shifted left, 0s are padded to the low bits and high bits are discarded.
3. If negative numbers are shifted right, 1s are padded to the high bits and low bits are discarded.

let p: Int8 = -30   
let q = p << 2      // q = -120
let r = p >> 2      // r = -8 
let r = p >> -2     // error
let x: UInt8 = 30 
let b = x << 3      // b = 240
let b = x >> 1      // b = 15

In addition, if the number of bits (right operand) shifted right or left is greater than or equal to the operand width, this is an overshift. If the overshift can be detected during compilation, an error is reported. Otherwise, an exception is thrown during running.

let x1 : UInt8 = 30 // 0b00011110
let y1 = x1 >> 11   // compilation error

Range Expressions

A range expression is an expression that contains interval operators. A range expression is used to create Range instances. The syntax of range expressions is defined as follows:

rangeExpression
    : bitwiseDisjunctionExpression ('..=' | '..') bitwiseDisjunctionExpression (':' bitwiseDisjunctionExpression)?
    | bitwiseDisjunctionExpression
    ;

There are two types of range operators: .. and ..=, which are used to create "left-closed and right-open" and "left-closed and right-closed" Range instances respectively. For details, see [Range].

Logical Expressions

A logical expression is an expression that contains logical operators. The operand of a logical operator must be an expression of the Bool type. Cangjie supports three logical operators: logical NOT (!), logical AND (&&), and logical OR (||). Their precedence and associativity are described below.

The syntax of logical expressions is defined as follows:

prefixUnaryExpression
    : prefixUnaryOperator* incAndDecExpression
    ;
    
prefixUnaryOperator
    : '!'
    | ...
    ;

logicDisjunctionExpression
    : logicConjunctionExpression ( '||' logicConjunctionExpression)*
    ;

logicConjunctionExpression
    : rangeExpression ( '&&' rangeExpression)*
    ;

The logical NOT (!) is a unary operator, which is used to negate the Boolean value of its operand: The value of !false is true. The value !true is false.

The logical AND (&&) and logical OR (||) are binary operators. For the expression expr1 && expr2, its value is equal to true only when the values of expr1 and expr2 are equal to true. For the expression expr1 || expr2, its value is equal to false only when the values of expr1 and expr2 are equal to false.

Short-circuit evaluation is used for && and ||. When expr1 && expr2 is calculated, expr2 does not need to be evaluated if expr1=false, and the value of the entire expression is false. When expr1 || expr2 is calculated, expr2 does not need to be evaluated if expr1=true, and the value of the entire expression is true.

main(): Int64 {
    let expr1 = false
    let expr2 = true
    !true                           // Logical NOT, return false.
    1 > 2 && expr1                  // Logical AND, return false without computing the value of expr1.
    1 < 2 || expr2                  // Logical OR, return true without computing the value of expr2.
    return 0
}

coalescing Expressions

The coalescing expression is an expression that contains coalescing operators. The coalescing operator is a binary infix operator represented by ??. Its precedence and associativity are described below.

The syntax of coalescing expressions is defined as follows:

coalescingExpression
    : logicDisjunctionExpression ('??' logicDisjunctionExpression)*
    ;

The coalescing operator is used to deconstruct the Option type. Assume that the type of the expression e1 is Option<T>. For the expression e1 ?? e2:

1. The expression e2 has the type T.

2. The expression e1 ?? e2 has the type T.

3. When the value of e1 is equal to Option<T>.Some(v), the value of e1 ?? e2 is equal to v (in this case, e2 is not evaluated, that is, the short-circuit evaluation condition is met). When the value of e1 is equal to Option<T>.None, the value of e1 ?? e2 is equal to e2.

The expression e1 ?? e2 is the syntactic sugar of the following match expression:

// when e1 is Option<T>
match (e1) {
    case Some(v) => v
    case None => e2
}

The following are examples of using the coalescing expressions:

main(): Int64 {
    let v1 = Option<Int64>.Some(100)
    let v2 = Option<Int64>.None
    let r1 = v1 ?? 0
    let r2 = v2 ?? 0
    print("${r1}") // output: 100
    print("${r2}") // output: 0
    
    return 0
}

Flow Expressions

A flow expression is an expression that contains flow operators. There are two types of flow operators: |> infix operator (called pipeline) that represents the data flow direction and ~> infix operator (called composition) that represents a combination of functions. The precedence of |> is the same as that of ~>, and is between || and =. |> and ~> are both left-associative. For details, see the following information. The syntax of flow expressions is defined as follows:

flowExpression
    : logicDisjunctionExpression (flowOperator logicDisjunctionExpression)*
    ;

flowOperator
    : '|>' | '~>'
    ;

pipeline Operators

The pipeline expression is the syntactic sugar of a single-parameter function call. For example, e1 |> e2 is the syntactic sugar of let v = e1; e2(v) (that is, e1 on the left of the |> operator is evaluated first). e2 is an expression of the function type, and the type of e1 is a subtype of the parameter type of e2. Alternatively, the type of e2 overloads the function call operator () (see [Operators That Can Be Overloaded]).

Note: The f cannot be an init or super constructor.

func f(x: Int32): Int32 { x + 1 }

let a: Int32 = 1
var res = a |> f // ok
var res1 = a |> {x: Int32 => x + 1} // ok

func h(b: Bool) { b }
let res3 = a < 0 || a > 10  |> h // Equivalence: (a < 0 || a > 10)  |> h

func g<T>(x: T): T { x }
var res4 = a |> g<Int32> // ok

class A {
    let a: Int32
    let b: Int32
    init(x: Int32) {
        a = x
        b = 0
    }
    init(x: Int32, y: Int32) {
        x |> init // error: `init` is not a valid expression
        b = y
    }
}

// PIPELINE with operator `()` overloading
class A {
    operator func ()(x: Int32) {
        x
    }
}
let obj = A()
let a: Int32 = 1
let res = a |> obj // Equivalence: obj(a)

composition Operators

A composition expression indicates a combination of two single-parameter functions. For example, the composition expression e1 ~> e2 is the syntactic sugar of let f = e1; let g = e2; {x = > g(f(x))} (that is, e1 on the left of the ~> operator is evaluated first). If f and g are expressions of the function type or their type overloads the function call operator () (see [Operators That Can Be Overridden]) of a single parameter, the following four situations may occur:

Note: The evaluated values of e1 and e2 cannot be init or super.

func f(x: Int32): Float32 { Float32(x) }
func g(x: Float32): Int32 { Int32(x) }

var fg = f ~> g // Equivalence: {x: Int32 => g(f(x))}

let lambdaComp = {x: Int32 => x} ~> f // ok

func h1<T>(x: T): T { x }
func h2<T>(x: T): T { x }
var hh = h1<Int32> ~> h2<Int32> // ok

// COMPOSITION with operator `()` overloading
class A {
    operator func ()(x: Int32): Int32 {
        x
    }
}
class B {
    operator func ()(x: Float32): Float32 {
        x
    }
}
let objA = A()
let objB = B()
let af = objA ~> f // ok
let fb = f ~> objB // ok
let aa = objA ~> objA // ok

Assignment Expressions

An assignment expression is an expression that contains assignment operators. It is used to change the value of a left operand to the value of a right operand. The type of the right operand must be a subtype of the type of the left operand. When an assignment expression is evaluated, the expression on the right of = is evaluated first, and then the expression on the left of = is evaluated.

When a compound assignment expression is used, the left value of the expression on the left of = is calculated first, and then the right value is obtained based on the left value. Then, the right value is used to calculate the expression on the right of = (if there is a short-circuit rule, the rule is followed). Finally, a value is assigned.

Except for the value that can be assigned as defined by the subtype, if the right operand is a string literal that contains only a single character and the type of the left operand is Byte or Rune, the type of the string value is forcibly converted to Byte or Rune and assigned to the left operand. If the type conversion fails, the compiler reports an error.

Assignment operators are classified into ordinary assignment operators and compound assignment operators. The syntax of assignment expressions is defined as follows:

assignmentExpression
    : leftValueExpressionWithoutWildCard assignmentOperator flowExpression
    | leftValueExpression '=' flowExpression
    | tupleLeftValueExpression `=` flowExpression
    | flowExpression
    ;

tupleLeftValueExpression
    : `(` (leftValueExpression | tupleLeftValueExpression) (`,` (leftValueExpression | tupleLeftValueExpression))+ `,`? `)`
    ;

leftValueExpression
    : leftValueExpressionWithoutWildCard
    | '_'
    ;

leftValueExpressionWithoutWildCard
    : identifier
    | leftAuxExpression '?'? assignableSuffix
    ;

leftAuxExpression   
    : identifier typeArguments?
    | type
    | thisSuperExpression
    | leftAuxExpression ('?')? '.' identifier typeArguments?
    | leftAuxExpression ('?')? callSuffix
    | leftAuxExpression ('?')? indexAccess
    ;

assignableSuffix
    : fieldAccess
    | indexAccess
    ;

fieldAccess
    : '.' identifier
    ;

assignmentOperator
    : '=' | '+=' | '-=' | '**=' | '*=' | '/=' | '%=' | '&&=' | '||=' 
    | '&=' | '|=' | '^=' | '<<=' | '>>='
    ;

The expression that appears on the left of a (compound) assignment operator is called a lvalue expression (leftValueExpression in the preceding definition).

Syntax: The lvalue expression can be an identifier, _, or leftAuxExpression followed by a assignableSuffix (including fieldAccess and indexAccess). There can be optional ? operators (syntactic sugar for assigning values to instances of Option Type) between leftAuxExpression and assignableSuffix. The leftAuxExpression may be in the following syntax form: 1. an identifier that includes an optional type of argument (typeArguments); 2. this or super; 3. a leftAuxExpression is followed by a . (there can be optional ? operators between them) and an identifier with optional type arguments; 4. a leftAuxExpression is followed by a function call postfix callSuffix or an index access postfix indexAccess (there can be optional ? operators before callSuffix or indexAccess).

The semantics of lvalue expression can only be one of the following:

1. Variables indicated by identifier (see [Variable Names and Function Names]).

2. The wildcard _ indicates that the evaluation result of the expression on the right of = is ignored. (Wildcards are not allowed in compound assignment expressions.)

3. Member access expression e1.a or e2?.a (see [Member Access Expressions])

4. Index access expression e1[a] or e2?[a] (see [Index Access Expressions])

Note: e1 and e2 must be expressions that comply with the leftAuxExpression syntax.

Left value expression is valid only when Left value expression is mutable. For details about the variability of the preceding expressions, see the corresponding chapters.

The type of assignment expressions is Unit, and the value is (). In this way, problems such as incorrectly using an assignment expression as a judgment expression can be avoided. In the following example, if (a = b) is executed first, the return value is (). However, () cannot be displayed on the left of =. Therefore, an error is reported when ()=0 is executed. Similarly, the expression following if must be of the Bool type. Therefore, an error is also reported for the if expression in the following example. In addition, = is non-associative. Therefore, an expression such as a = b = 0 that contains more than two ='s cannot pass the syntax check.

main(): Int64 {
    var a = 1
    var b = 1
    a = (b = 0) // semantics error
    if (a = 5) {  // semantics error
    }
    a = b = 0   // syntax error
    
    return 0
}

The compound assignment expression a op = b cannot be simply regarded as a = a op b, a combination of an assignment expression and other binary operators (op can be any binary operator among arithmetic operators, logical operators, and bitwise operators, and the types of operands a and b are the types required by the operator op). In Cangjie, a in a op = b is evaluated only once (the side effect occurs only once), and a in a = a op b is evaluated twice (the side effect occurs twice). A compound assignment expression is also an assignment expression, so compound assignment operators are also non-associative. A compound assignment expression also requires that the two operands be of the same type.

The following examples describe how to use compound assignment expressions:

a **= b
a *= b 
a /= b
a %= b 
a += b 
a -= b 
a <<= b
a >>= b
a &&= b
a ||= b
a &= b 
a ^= b 
a |= b 

Finally, if you overload the **, *, /, %, +, -, <<, >>, &, ^, or | operator, Cangjie provides the default implementation of the corresponding compound assignment operator **=, *=, /=, %=, +=, -=, <<=, >>=, &=, ^=, or |=. However, some additional requirements should be met. Otherwise, the value assignment semantics cannot be provided for a = a op b.

1. The return type of an overloaded operator must be the same as the type of a left operand or its subtype. That is, a, b, and op in a op = b must pass the type check of a = a op b. For example, when there is a subtype relationship A <: B <: C, if a type of + overloaded by the user is (B, Int64) -> B or (B, Int64) -> A, Cangjie can provide a default implementation. If a type of + overloaded by the user is (B, Int64) -> C, Cangjie does not provide a default implementation.

2. The value of a in a op= b must be assignable, for example, a variable.

A multiple assignment expression is a special assignment expression. In such expression, there must be a tuple on the left and right of the equal sign (=) respectively. All elements in the left tuple must be left values, and the type of each element in the right tuple must be the subtype of the lvalue type in the corresponding position. Note: If _ is displayed in the tuple on the left, the evaluation result at the position corresponding to the tuple on the right of the equal sign is ignored (that is, the type check at this position can always be passed).

The multiple assignment expression can assign the value of the right tuple type to the corresponding left value in the left tuple at a time, so that code for assigning values one by one is not needed.

main(): Int64 {
    var a: Int64
    var b: Int64

    (a, b) = (1, 2) // a == 1, b == 2
    (a, b) = (b, a) // swap, a == 2, b == 1
    (a, _) = (3, 4) // a == 3
    (_, _) = (5, 6) // no assignment

    return 0
}

A multiple assignment expression can be considered as a syntactic sugar in the following form: The expression on the right of the assignment expression is evaluated first, and then the left value is assigned one by one from left to right.

main(): Int64 {
    var a: Int64
    var b: Int64
    (a, b) = (1, 2)
    // desugar
    let temp = (1, 2)
    a = temp[0]
    b = temp[1]
    return 0
}

Lambda Expressions

A Lambda expression is a value of the function type. For details, see [Functions].

Quote Expressions

Quote expressions are used to reference code and represent it as operable data objects. They are mainly used for metaprogramming. For details, see [Metaprogramming].

Macro Call Expressions

Macro call expressions call macros defined by Cangjie and are mainly used for metaprogramming. For details, see [Metaprogramming].

Reference Value Transfer Expressions

Reference value transfer expressions can be used only when CFunc is called during C interoperability. For details, see the description of the inout parameter in [Cross-Language Interoperability].

Precedence and Associativity of Operators

For an expression that contains two or more operators, its value is determined by the grouping and combination mode of the operators and operands. The grouping and combination mode depends on the precedence and associativity of the operators. To put it simply, the precedence specifies the evaluation sequence of different operators, and the associativity specifies the evaluation sequence of operators with the same precedence.

If an expression contains multiple operators with different precedence, its subexpressions with the operators of higher precedence is evaluated first, followed by those of lower precedence. If a subexpression contains multiple operators of the same precedence, the sequence depends on the associativity of the operators.

The following table lists the precedence, associativity, feature description, usage, and expression type of each operator. The closer to the top of the table, the higher the precedence of the operator.

Note: When ? is used together with ., (), {}, or [], it indicates a syntactic suger and evaluation does not strictly follow their inherent precedence and associativity. For details, see [Question Mark Operators].

Evaluation Sequence of Expressions

The evaluation sequence of expressions specifies the sequence in which the values of operands are calculated. Obviously, only expressions containing binary operators have the concept of evaluation sequence. The default evaluation sequence of Cangjie is as follows:

1. For an expression that contains logical AND (&&), logical OR (||), and coalescing (??), the right operand of an operator is evaluated only when it affects the value of the entire expression. Otherwise, only the left operand is evaluated. Therefore, the evaluation sequence of &&, ||, and ?? is as follows: The left operands are evaluated first, followed by the right operands.

2. For an optional chaining expression, the ? operators separate it into several subitems and the subitems are evaluated from left to right in sequence (based on the evaluation sequence of the used operators).

3. Other expressions (such as arithmetic expressions, relational expressions, and bitwise expressions) are also evaluated from left to right.

Functions

A function is an independent code snippet that completes a specific task. It can be identified by a function name, which can be used for calling a function. In Cangjie, functions are first-class citizens. Functions support variable assignment, and can be used as parameters or return values.

Function Definition

In Cangjie, function definition must comply with the following syntax rules:

functionDefinition
    	: functionModifierList? 'func'
    	identifier 
        typeParameters?
        functionParameters
    	(':' type)?
    	(genericConstraints)?
    	block
    	;

The summary is as follows:

• The keyword func is used to define a function.
• func can be preceded by a function modifier.
• func must be followed by the function name.
• The optional type parameter list is enclosed by <>. Multiple type parameters are separated by ,.
• The function parameters are enclosed by (). Multiple parameters are separated by ,. The parameter type of each parameter must be specified. For details, see [Parameters].
• The default function return type is specified by :type.
• When a function is defined, a function body, which is a block (excluding function parameters), must be specified.

The following example shows all elements of a complete function definition. The access modifier public is not used, indicating that the function can be accessed in the package. The function is named foo, has a parameter a of the Int64 type, a return type Int64, and a function body.

func foo(a: Int64): Int64 { a }

A function name cannot be assigned a value. That is, the function name cannot appear in the program as the lvalue of an expression.

The operation in the following example is forbidden.

func f(a: Int64): Int64 { a }

// f = {a: Int64 => a + 1}		// compile-time error

Function Modifiers

Modifier of Global Function

Global functions can be modified by all access modifiers. The default accessibility is internal. For details, see Access Modifiers in [Packages and Modules].

Modifiers of Local Functions

No modifier is available for the local function.

Modifiers of Member Functions

The modifiers of class member functions include public, protected, private, internal, static, open, override, and redef. For details, see [Members of a Class] and Access Modifiers in [Packages and Modules].

The modifiers of interface member functions include static and mut. For details, see [Interface Members].

The modifiers of struct member functions include mut, public, private, internal, and static. For details, see [Struct Type].

The modifiers of enum member functions include public, private, internal, and static. For details, see [Enum Type].

If no access modifier is provided, member functions other than interface member functions can be accessed in the current package and subpackages. Interface member functions contain the semantics of public by default.

Parameters

When a function is defined, the sequence of parameters in the parameter list is non-named parameters followed by named parameters (including named parameters with and without default values). The syntax of the parameter list is defined as follows:

functionParameters
    : ('(' (unnamedParameterList (',' namedParameterList)? )? ')')
      | ('(' (namedParameterList)? ')')
    ;

nondefaultParameterList
    : unnamedParameter (',' unnamedParameter)* (',' namedParameter)*
    | namedParameter (',' namedParameter)*
    ;

namedParameterList
    : (namedParameter | defaultParameter) (',' (namedParameter | defaultParameter))*
    ;

namedParameter
    : identifier '!' ':' type 
    ;

defaultParameter
    : identifier '!' ':' type '=' expression
    ;

unnamedParameterList
    : unnamedParameter (',' unnamedParameter)*
    ;

unnamedParameter
    : (identifier | '_') ':' type
    ;

For non-named parameters, you can use a _ to replace the parameters that are not used in a function body.

func bar(a: Int64 , b!: Float64 = 1.0, s!: String) {}   // OK
func bar2(a: Int64 = 1, b!: Float64 = 1.0, s: String = "Hello") {}   // Error
func foo(a: Int64, b: Float64)(s: String = "Hello") {}  // Error

func f1(a: Int64, _: Int64): Int64 {
    return a + 1
}

func f2(_: String): Unit {
    print("Hello Cangjie")
}

All function parameters are immutable variables, that is, they are modified by let and cannot be assigned values in a function definition.

func foo(a: Int64, b: Float64) {
    a = 1       // Error: the parameter 'a' is immutable, and cannot be assigned.
    b = 1.0     // Error: the parameter 'b' is immutable, and cannot be assigned.
}

The parameter type of a function is not affected by whether the parameter is a named parameter or whether the parameter has a default value. In addition, when the parameter type is discussed, a type and its alias are considered to be the same type.

Naming Parameters

When defining a function, add ! to the end of a parameter name to define a named parameter.

namedParameter
    : identifier '!' ':' type
    ;

• During function definition, non-named parameters are not allowed after named parameters.

func add1(a: Int32, b!: Int32): Int32 { a + b } // ok

func add2(a!: Int32, b: Int32): Int32 { a + b } // error

• When a parameter is defined as a named parameter and this function is called, you must use the parameter name: prefix before the argument value to specify the parameter corresponding to the argument. Otherwise, a compilation error is reported.

func add(a: Int32, b!: Int32): Int32 { a + b }

add(1, b: 2) // ok
add(1, 2)    // error

• If an abstract function or a function modified by open has a named parameter, the implementation function or the function modified by override must retain the same named parameter.

  open class A {
  	public open func f(a!: Int32): Int32 {
  		return a + 1
  	}
  }
  class B <: A {
  	public override func f(a!: Int32): Int32 { // ok
  		return a + 1
  	}
  }
  class C <: A {
  	public override func f(b!: Int32): Int32 { // error
  		return b + 1
  	}
  }
  

Default Values of Parameters

Function parameters can have default values. You can use = to define default values for parameters. After the default value is defined for a parameter, it can be ignored when that function is called. The function body uses the default value. For better understanding, parameters with default values are called optional parameters.

When a function is defined, an optional parameter is a named parameter. The ! must be added to the end of the optional parameter name. Otherwise, an error is reported during compilation.

defaultParameter
    : identifier '!' ':' type '=' expression
    ;  

In the following example, an add function is defined, and its parameter type list is (Int32, Int32). When the function is defined, b has the default value 1. Therefore, when the add function is called and only the value 3 is passed, 3 is assigned to a, and the result 4 is returned.

If 3 and 2 are passed, the value of b is 2.

func add(a: Int32, b!: Int32 = 1): Int32 { a + b }

add(3)			// invoke add(3, 1), return 4
add(3, b: 2)	// return 5

• Functions that are modified by the open keyword in a class or interface cannot have optional parameters.

• The operator function cannot contain optional parameters.

• Anonymous functions (lambda expressions) do not allow optional parameters.

• The name introduced in the default value of a function parameter is obtained from the static scope. That is, the introduced name is a name that can be accessed when the function is defined.

• The name introduced in the default value of a function parameter can be accessed when the function is defined, and does not need to be consistent with the accessibility of the function itself.

• The function parameter and its default value do not belong to the function body.

• The default value of a parameter is evaluated when the function is called, not when the function is defined.

• When a function is called, parameters are evaluated from left to right based on the definition sequence. The default value of a function parameter can reference the parameters defined before it.

• When a function is called using its function name, the default value can be used. When a function is called using its variable name, the default value cannot be used.

  // Compile-time error.
  // func f(a: Int32, b!: Int32 = 2, c: Int32): Int32 { ... }
  
  // OK.
  func f1(a: Int32, b: Int32, c!: Int32 = 3, d!: Int32 = 4): Int32 { 
      a + b + c + d
  }
  
  func test() {
      f1(1, 2)	    // 10,  f1(1, 2, 3, 4)
      f1(1, 2, c: 5)	    // 12,  f1(1, 2, 5, 4)
  }
  

  /* The names introduced in the default value, does not need to have the same or least restrictive accessibility of the function. */
  var x = 10
  var y = 10
  func g() {}
  public func f2(a!: Int64 = x * 2 + y, b!: ()->Unit = g) {}  // OK.
  
  class AAA {
      static private var x = 10
  
      func f(a!: Int64 = x) { // OK, public method can use private static field.
          print("${a}")
          x = x + 10
          print("${x}")
      }
  }
  

  /* 
  When a function is called, the name in the function declaration can use the default value. When a function is called by using a variable name, arguments cannot be optional.
  */
  func f1(): (Int64) -> Unit { g1 }
  
  func g1(a!: Int64 = 42) {
      print("g1: ${a}")
  }
  
  let gg1 = f1()   
  let x = gg1()    // Error, cannot ommit the argument.
  let gg3 = g1     
  let a = gg3()    // Error, cannot ommit the argument.
  

The parameters of a function and their default values do not belong to the function body. Therefore, the return expression in the following example does not contain the function body that surrounds the expression. That is, the return expression does not belong to the outer function f (because the definition of the inner function g has taken effect) or the function body of the inner function g.

func f() {
    func g(x! :Int64 = return) { // Error: return must be used inside a function body
        0
    }
    1
}

Function Body

The function body consists of a block.

Local Variables

In Cangjie, variables can be defined in the function body, which are called local variables.

A variable can be modified as a mutable variable by using var or as an immutable variable by using let.

func foo(): Unit {
    var a = 1
    let b = 1
}

Nested Functions

In Cangjie, functions can be defined in the function body, which is called nested functions. Nested functions can capture variables defined in external functions or other nested functions. Nested functions support recursion.

func foo(): Unit {
    func add(a: Int32, b: Int32) { a + b }

    let c = 1

    func nest(): Unit {
        print("${c}")			// 1
        var b = add(1, 2)	// b = 3
    }
}

Return Type of Functions

The return type of a function can be one of the following:

• Any type (see [Types]).

• Functions returning a tuple: The tuple type can be used as the return type of a function, allowing multiple values to be returned as a composite value. In the following example, the return value is a tuple (a, b), and the return type is (Int32, Int32).

  func returnAB(a: Int32, b: Int32): (Int32, Int32) { (a, b) }
  

• Function type as the return type: You can use a function type as the return type of another function. In the following example ,the : is followed by the add function type (Int32, Int32) -> Int32.

  func returnAdd(a: Int32, b: Int32): (Int32, Int32) -> Int32 {
      return {a, b => a + b}    // Return a lambda expression.
  }
  

To specify the return type of a function, use :Type after the parameter list of the function's definition. In this case, the type of the function body and the type of e in all return e expressions in the function body must be subtypes of the specified type (Type). Otherwise, a compilation error is reported.

class A {}
class B <: A {}
// Return is not written.
func add(a: Int32, b: Int32): B {
    var c = a + b
    if (c > 100) {
        return B()
    } else {
        return A() // Compilation error since A is not a subtype of B.
    }
}

Specifically, if the return type is specified as Unit (for example, func f(x:Bool):Unit { x}), the compiler automatically inserts the expression return () at all possible return points in the function body so that the return type of the function is always Unit. The following is an example:

func Column(c: (Data) -> Unit): Unit { 2 } // return () is automatically inserted
func Column(c: (Data) -> Unit) { 2 }   // return type is Int64

If the return type of a function is not specified, the compiler infers the return type of the function based on the function body and all return expressions in the function body. This process is incomplete. For example, if the function is (mutually) recursive and its return type cannot be inferred, a compilation error is reported. (Note: The return type cannot be inferred for a function without a function body.)

The rules for inferring the return type of a function are as follows: The function body is a sequence of expressions and declarations. We denote the type of the last item in the sequence as T0. (If the last item of a block is an expression, the return type of the function is the type of that expression. If the last item is a declaration, then T0 = Unit.) Then, we denote the type of e in all return e expressions (including those in all subexpressions) in the function body as T1... Tn. The return type of the function is the minimum common supertype of T0, T1, ..., Tn. If the minimal common supertype does not exist, a compilation error occurs. The following is an example:

open class Base {}
class Child <: Base {}

func f(a: Rune) {
    if (false) {
        return Base()
    }
    return Child()
}

• The type of the function body is the type of the last item in the block, that is, the type of return Child(), which is Nothing.
• In the first return e expression return Base(), the type of e is Base.
• In the second return e expression return Child(), the type of e is Child.
• The minimum common supertype of Nothing, Base, and Child is Base. Therefore, the return type of this function is Base.

Note: The return value of a function has the semantics of let.

Function Declarations

In Cangjie, the difference between function declaration and function definition is that the former does not have a function body. The syntax for function declaration is as follows:

functionDeclaration
    	: functionModifierList? 'func'
    	identifier 
        typeParameters?
        functionParameters
    	(':' type)?
    	genericConstraints?
    	;

Function declarations can appear in abstract classes and interfaces.

Function Redefinition

For non-general functions, functions with the same name and parameter type in the same scope are considered redefined, and a compilation error occurs. The following situations should be noted:

• Functions with the same name are considered redefined even if their return types are different.
• A generic function and a non-generic function with the same name never constitutes a redefinition.
• During inheritance, if a function in a subclass has the same name and parameter types as a function in the superclass and its return type is the subtype of the function in the superclass, this constitutes overriding, but not a redefinition. (This is because the scope of the subclass is different from that of the superclass.)

For two generic functions, after one function's generic parameter is renamed, if the non-generalized part of this function and that of the other function constitute a redefinition, the two generic functions constitute a redefinition. An example is as follows:

1. The following two generic functions constitute a redefinition because the renaming of [T1 |-> T2] applies to the first function, causing the non-generic parts of both functions to constitute a redefinition.

   func f<T1>(a: T1) {}
   func f<T2>(b: T2) {}
   

2. The following two generic functions do not constitute a redefinition because the previously-mentioned renaming cannot be found.

   func f<X,Y>(a:X, b:Y) {}
   func f<Y,X>(a:X, b:Y) {}
   

3. The following two generic functions constitute a redefinition because there is a renaming of [X |-> Y, Y |-> X], causing the non-generic parts of both functions to constitute a redefinition.

   func f<X,Y>(a:X, b:Y) {}
   func f<Y,X>(a:Y, b:X) {}
   

Function Types

The function type consists of the parameter type and return type, which are connected using ->.

functionType:
    : '(' (type (, type)*)? ')' '->' type

The following are some examples:

• Example 1: There is no parameter, and the return type is Unit.

  func hello(): Unit { print("Hello!") }
  
  // function type: () -> Unit
  

• Example 2: The parameter type is Int32, and the return type is Unit.

  func display(a: Int32): Unit { print("${a}") }
  
  // function type: (Int32) -> Unit
  

• Example 3: The two parameters are of the Int32 type, and the return type is Int32.

  func add(a: Int32, b: Int32): Int32 { a + b }
  
  // function type: (Int32, Int32) -> Int32
  

• Example 4: The parameter type is (Int32, Int32) -> Int32, Int32 and Int32, and the return type is Unit.

  func printAdd(add: (Int32, Int32) -> Int32, a: Int32, b: Int32): Unit {
      print("${add(a, b)}")
  }
  // function type: ((Int32, Int32) -> Int32, Int32, Int32) -> Unit
  

• Example 5: The two parameters are of the Int32 type, and the return type is the function type (Int32, Int32) -> Int32.

  func returnAdd(a: Int32, b: Int32): (Int32, Int32) -> Int32 {
    {a, b => a + b}
  }
  
  // function type: (Int32, Int32) -> (Int32, Int32) -> Int32
  

• Example 6: If both parameters are of the Int32 type, the tuple type (Int32, Int32) is returned.

  func returnAB(a: Int32, b: Int32): (Int32, Int32) { (a, b) }
  
  // function type: (Int32, Int32) -> (Int32, Int32)
  

Function Calls

For details about the syntax of function call expressions, see [Function Call Expressions].

Named Arguments

When a function is called, the parameter name: prefix is used before the argument value to specify the parameter corresponding to this argument. Only parameters defined by ! in the function definition can use the syntax for named arguments.

When a function is called, all named parameters must be passed using named arguments. Otherwise, an error is reported.

In a function call expression, non-named arguments are not allowed after named arguments. When named arguments are used to specify argument values, the sequence of the arguments does not need to match that of the parameter list.

func add(a!: Int32, b!: Int32): Int32 {
    a + b
}

var sum1 = add(1, 2)        // error
var sum2 = add(a: 1, b: 2)  // OK, 3
var sum3 = add(b: 2, a: 1)  // OK, 3

Function Call Type Check

This section describes the type check required for a given call expression. If the called function involves overloading, the type check and overloading resolution must be based on the rules of [Function Overloading].

1. If a type parameter is specified in the function call expression, the type check can be passed only when the number of type arguments is the same as the number of type parameters. For example, if the function call expression is f<T1, ..., Tm>(A1, ..., An) and m type arguments are specified, the number of function type parameters must be m.

open class Base {}
class Sub <: Base {}
func f<X, Y>(a: X, b: Y) {}  // f1
func f<X>(a: Base, b: X) {}  // f2
f<Base>(Base(), Sub()) // f2 may pass the type checking

2. Type check of a function must be based on the arguments in the call expression and the return type R specified in the type check context.

Assume that the function is defined as follows:

$$ f_i<T_{i1},...,T_{ip}>(A_{i1}, ..., A_{ik}): R_i \ \ where \ \ C_{i1}, ..., C_{iq_i} $$ (1) If the call expression contains the type argument, that is, fi<T1, ..., Tp>(A1, ..., Ak), the rules for the type check of the fi function are as follows:

      (a) Type argument constraint check: The type argument `<T1, ..., Tp>` must meet the type constraint of the `fi` function.

$$ \sigma = [T_1 \mapsto T_{i1}, ..., T_p \mapsto T_{ip}] $$ $$ \Delta \vdash \sigma \ \ solves \ \ C_{i1}, ..., C_{iq_i} $$ (b) Parameter type check: After the type arguments are substituted into the parameters of the function fi, the argument types (A1, ..., Ak) are the subtypes of the type after the type argument is substituted into the parameter.

$$ \sigma = [T_1 \mapsto T_{i1}, ..., T_p \mapsto T_{ip}] $$ $$ \Delta \vdash (A1, ..., Ak) <: \sigma (A_{i1},...,A_{ik}) $$ (c) Return type check: If the context of the call expression requires a specific type R, type check needs to be performed based on the return type. After the type argument is substituted into the return type Ri of the function fi, the return type is the subtype of R.

$$ \sigma = [T_1 \mapsto T_{i1}, ..., T_p \mapsto T_{ip}] $$ $$ \Delta \vdash \sigma R_i <: R $$ (2) If the call expression does not contain the type argument, that is, f(A1, ..., An), the rules for the type check of the fi function are as follows:

(a) If `fi` is a non-generic function, the type check is performed based on the following rules:



    	(i) Parameter type check: The argument types `(A1, ..., Ak)` are subtypes of the parameter types.

$$ \Delta \vdash (A1, ..., Ak) <: (A_{i1},...,A_{ik}) $$ (ii) Return type check: If the context of the called expression requires a specific type R, the return type Ri of the checked function fi is the subtype of R.

$$ \Delta \vdash R_i <: R $$

open class Base {}
class Sub <: Base {}
func f(a: Sub) {1}  // f1
func f(a: Base) {Base()}  // f2
let x: Base = f(Sub())  // f2 can pass the type checking

(b) If `fi` is a generic function, the type check is performed based on the following rules:



    	 (i) Parameter type check: Substitution exists so that the argument types `(A1, ..., Ak)` are the subtypes of the types after parameter type substitution.

$$ \sigma = [T_1 \mapsto T_{i1}, ..., T_p \mapsto T_{ip}] $$ $$ \Delta \vdash (A1, ..., Ak) <: \sigma (A_{i1},...,A_{ik}) $$ (ii) Return type check: If the context of the call expression requires a specific type R, type check needs to be performed based on the return type. After the type argument in (i) is substituted into the return type Ri of the function fi, the return type is the subtype of R.

$$ \sigma = [T_1 \mapsto T_{i1}, ..., T_p \mapsto T_{ip}] $$ $$ \Delta \vdash \sigma R_i <: R $$

Note that:

1. If a function has a default value, the default value is padded before type check.
2. If a function has named parameters, the sequence of the named parameters may be different from that of the parameters. During type check, the named arguments must correspond to the matching named parameters.

Trailing Lambda

When the last parameter of a function is the function type, and the argument corresponding to the function call is lambda, you can use the trailing lambda syntax to place lambda at the end of the function call outside the parentheses ().

func f(a: Int64, fn: (Int64)->Int64) { fn(a) }
 
f(1, { i => i * i }) // normal function call
f(1) { i => i * i } // trailing lambda
 
func g(a!: Int64, fn!: (Int64)->Int64) { fn(a) }
 
g(a: 1, fn: { i => i * i }) // normal function call
g(a: 1) { i => i * i } // trailing lambda

If a function call has only one lambda as an argument, you can omit () and write only lambda.

func f(fn: (Int64)->Int64) { fn(1) }

f{ i => i * i }

If the trailing lambda does not contain parameters, => can be omitted.

func f(fn: ()->Int64) { fn() }

f{ i * i }

Note that the trailing lambda syntax can be used only for function calls with function name/variable name, and the lambda expression that is trailing lambda interprets it only as the parameter of the function corresponding to function name/variable name. This means that the following two call examples are invalid:

func f(): (()->Unit)->Unit {
    {a => }
}

f() {} // error, the lambda expression is not argument for f.

func g(a: ()->Unit) {}

if (true) { g } else { g } () {} // error, illegal trailing lambda syntax

The preceding expression must be assigned to a variable first. The trailing lambda syntax can be used only when the variable name is used for calling. The code is as follows:

let f2 = f()
f2 {} // ok
let g2 = if (true) { g } else { g }
g2() {} // ok

This syntax can be used for both common function calls and constructor calls, including this() and super().

this(1, { i => i * i } )
this(1) { i => i * i }

super(1, { i => i * i } )
super(1) { i => i * i }

Variable-Length Parameters

Variable-length parameters are special syntactic sugar for function calls. When the last non-named parameter is of the Array type, the parameter sequence can be directly passed to the corresponding position of the argument to replace the Array literal.

1. Variable-length parameters do not have special declaration syntax. It only requires the last non-named parameter in the function declaration is of the Array type.
2. When a function is called, multiple elements of Array can be passed one by one in the form of a common parameter list.
3. Among non-named parameters, only the last parameter can use variable-length parameters. This syntactic sugar cannot be used for named parameters.
4. Variable-length parameters are applicable to global functions, static member functions, instance member functions, local functions, constructors, function variables, lambda, function call operator overloading, and index operator overloading. Other operator overloading, compose, and pipeline calling modes are not supported.
5. There may be zero or more variable-length parameters.
6. Variable-length parameters take effect only when function overloading does not exist. The priority is the lowest.

func f1(arr: Array<Int64>) {}
func f2(a: Int64, arr: Array<Int64>) {}
func f3(arr: Array<Int64>, a: Int64) {}
func f4(arr1!: Array<Int64>, a!: Int64, arr2!: Array<Int64>) {}

func g() {
    let li = [1, 2, 3]
    f1(li)
    f1(1, 2, 3) // using variable length argument
    f1() // using variable length argument
    f2(4, li)
    f2(4, 1, 2, 3) // using variable length argument

    f3(1, 2, 3) // error, Array is not the last parameter
    f4(arr1: 1,2,3, a: 2, arr2: 1,2,3) // error, named parameters cannot use variable length argument
}

The function overloading resolution always preferentially considers the functions that can be matched without using variable-length parameters. Variable-length parameters are used for parsing only when no function can be matched.

If the compiler cannot make a resolution, an error is reported.

open class A {
    func f(v: Int64): Unit { // f1
    }
}

class B <: A {
    func f(v: Array<Int64>): Unit { // f2
    }
}

func p1() {
    let x = B()
    x.f(1) // call the f1
}

func g<T>(arg: T): Unit { // g1
}

func g(arg: Array<Int64>): Unit { // g2
}

func p2() {
    g(1) // call the g1
}

func h(arg: Any): Unit { // h1
}
func h(arg: Array<Int64>): Unit { // h2
}

func p3() {
    h(1) // call the h1
}

Function Scopes

In Cangjie, a function can be defined at the top level of the source program or inside the function.

• Global Functions

  A function defined at the top level of a source program is called a global function, and its scope is global. In the following example, the globalFunction function is a global function. Its scope is global.

  func globalFunction() {}
  

• Nested Functions

  A function defined in a function body is a nested function, and its scope is local. For details, see [Scopes]. In the following example, the nestedFunction function is a nested function, and its scope ranges from its definition to the end of the globalFunction function body.

  func globalFunction() {
  	func nestedFunction() {}
  }
  

• Member Functions

  Member functions can be declared or defined in the type definition. The scope of a member function is the entire type and its extensions.

  interface Myinterface {
  	func foo(): Unit
  	static func bar(): Unit
  }
  
  class MyClass {
  	func foo() {}
    static func bar() {}
  }
  

• Member Functions of Extensions

  Additional member functions can be declared in an extension. Its scope is all extensions of the extended type and is restricted by access modifiers.

  extend MyType {
  	func foo(): Unit {}
  }
  

Lambda Expressions

A lambda expression is an anonymous function.

The syntax of the lambda expression is as follows:

lambdaExpression    
        : '{' NL* lambdaParameters? '=>' NL* expressionOrDeclarations '}'
        ;

lambdaParameters
    : lambdaParameter (',' lambdaParameter)* ','?
    ;

lambdaParameter
    : (identifier | '_') (':' type)?
    ;

The lambda expression has two forms: one is with parameters, for example, {a: Int64 => e1; e2}, and the other one is without parameters, for example, { => e1; e2}. (e1 and e2 are expressions or declaration sequences).

let f1: (Int64, Int64)->Int64 = {a: Int64, b: Int64 => a + b}

var f2: () -> Int32 = { => 123 }

For a lambda expression with parameters, you can use a _ to replace a parameter. A _ indicates the parameters that are not used in the function body of the lambda expression.

let f2 = {n: Int64, _: Int64 => return n * n}
let f3: (Int32, Int32) -> Int32 = {n, _ => return n * n}
let f4: (String) -> String = {_ => return "Hello"}

The lambda expression does not support the declaration of the return type.

• If the return type of a lambda expression is explicitly specified in the context, its return type is the type specified in the context. If the specified return type is Unit, the Cangjie compiler inserts return () at all possible return points in the function body of the lambda expression so that the return type of the function is always Unit. The following is an example of specifying the return type as Unit:

  func column(c: (Data) -> Unit) {...}
  func row(r: (Data) -> Unit) {...}
  
  func build():Unit {
      column { _ =>
          row { _ =>
              buildDetail()
              buildCalendar()
          } // OK. Well typed since 'return' is inserted.
          width(750)
          height(700)
          backgroundColor("#ff41444b")
      }  // OK. Well typed since 'return' is inserted.
  }
  

• If such context does not exist, the type of the expression on the right of => is considered as the return type of the lambda expression. Similar to functions, if the return type cannot be inferred, a compilation error is reported.

The type annotation of the parameter in the lambda expression can be left empty. The compiler attempts to infer the type from the context. If the compiler cannot infer the type, a compilation error is reported.

var sum1: (Int32, Int32) -> Int32 = {a, b => a + b}

var sum2: (Int32, Int32) -> Int32 = {a: Int32, b => a + b}

var display = { => print("Hello") }

var a = { => return 1 }

The rules for the content on the right of => is the same as that of a common function body. You can also omit return. If the right side of => is empty, the return value is ().

sum1 = {a, b => a + b}

sum2 = {a, b => return a + b}		// Same as that in the previous line.

A lambda expression can be called immediately. The following is an example:

let r1 = {a: Int64, b: Int64 => a + b}(1, 2) // r1 = 3
let r2 = { => 123 }()                        // r2 = 123

Closures

In Cangjie, a closure is a self-contained function or lambda. A closure can capture variables from the static scope that defines it. Even if a call to a closure is not in the defined scope, the captured variables can still be accessed. Variable capture occurs when a closure is defined.

Not all variable accesses within a closure are considered captures. The following cases are not considered captures:

• A local variable defined inside a function or lambda is accessed in the function or lambda.
• A parameter of a function or lambda is accessed in the function or lambda.
• Global variables and static member variables are accessed in functions or lambdas.
• An instance member variable is accessed in an instance member function. As the instance member function passes this as a parameter, all instance member variables are accessed through this in the instance member function.

There are two cases for capturing variables:

• Capturing variables declared by let: The values of these variables cannot be modified in closures. If the captured variable is of the reference type, you can change the value of its mutable instance member variable. Functions or lambdas that capture only local variables declared by let can be used as first-class citizens. That is, they can be assigned to variables, used as arguments or return values, and used as expressions.
• Capturing variables declared by var: Functions or lambdas that capture mutable variables can only be called and cannot be used as first-class citizens. For example, they cannot be assigned to variables, used as arguments or return values, or used as expressions.

Note that capturing is transitive. If the f function calls the g function that captures the var variable which is not defined inside the f function, the f function also captures the var variable and cannot be used as a first-class citizen.

In the following example, h captures only the variable y declared by let. h can be used as a first-class citizen.

func f(){    
    let y = 2
    func h() {
        print(y)  // OK, captured an immutable variable.
    }
    let d = h    // OK, h can be assigned to variable
    return h   // OK, h can be a return value
}

In the following example, g captures the variable x declared by var. g cannot be used as a first-class citizen and can only be called.

func f() {
    var x = 1

    func g() {
        print(x)  // OK, captured a mutable variable.
    }
    let b = g  // Error, g cannot be assigned to a variable
    
    g  // Error, g cannot be used as an expression
    g()  // OK, g can be invoked
    
    // Lambda captured a mutable variable, cannot be assigned to a variable
    let e = { => print("${x}") }  // Error

    let i = { => x*x }()  // OK, lambda captured a mutable variable, can be invoked.

    return g  // Error, g cannot be used as a return value.
}

In the following example, g captures the variable x declared by var, f calls g, and x captured by g is not defined in f. f cannot be used as a first-class citizen.

func h(){
    var x = 1
    
    func g() { x }   // captured a mutable variable
    
    func f() {
        g()      // invoked g
    }
    return f // error
}

In the following example, g captures the x variable declared by var, and f calls g. However, x captured by g is defined inside f, and f does not capture other variables declared by var. Therefore, f is still used as a first-class citizen.

func h(){
    func f() {
        var x = 1
        func g() { x }   // captured a mutable variable

        g()
    }
    return f // ok
}

Functions or lambdas that access global variables, static member variables, and instance member variables modified by var can still be used as first-class citizens.

class C {
    static var a: Int32 = 0 
    static func foo() {
        a++       // OK
        return a
    }
}

var globalV1 = 0

func countGlobalV1() {
    globalV1++    
    C.a = 99      
    let g = C.foo  // OK
}

func g(){
    let f = countGlobalV1 // OK
    f()
}

The captured variables must meet the following rules:

• A captured variable must be visible when a closure is defined. Otherwise, an error is reported during compilation.
• Variables must have been initialized before being captured. Otherwise, an error is reported during compilation.
• If a function contains a local variable with the same name as a variable outside the function, when the closure in the function captures the variable outside the function because the scope of the local variable does not start, a warning is reported to avoid misuse.

// 1. The captured variable must be defined before the closure.  
let x = 4
func f() {
    print("${x}")    // Print 4.  
    let x = 99	
    func f1() {
        print("${x}")    
    }
    let f2 = { =>
        print("${x}")     
    } 
    f1()          // Print 99.
    f2()          // Print 99.
}

// 2. The variable must be initialized before being captured.
let x = 4
func f() {
    print("${x}")    // Print 4.  
    let x: Int64	
    func f1() {
        print("${x}")    // Error: x is not initialized yet.
    }
    x = 99
    f1()          
}

// 3. If there is a  local variable in a block, closures capture variables of the same name in the outer scope will report a warning.
let x = 4
func f() {
    print("${x}")    // Print 4.
    func f1() {
        print("${x}")	// warning
    }
    let f2 = { =>
        print("${x}")  	// warning
    }
    let x = 99
    f1()   // print 4       
    f2()   // print 4       
}

Function Overloading

Definition of Function Overloading

In Cangjie, function overloading occurs when multiple function definitions with the same function name exist in the same scope, but they do not constitute redefinition. When function overloading exists, the correct function definition to be used is determined during the function call based on the types of the arguments in the call expression and the context.

Rules for Function Overloading

• The function name must be the same and meet one of the following conditions:

  • The function name is introduced by the func keyword.
  • The function is a constructor defined in a class or struct, including the main constructor and the init constructor.

• The parameter types must be different. That is, one of the following conditions must be met:

  • The number of function parameters is different.

  • The number of function parameters is the same, but the parameter types in the corresponding positions are different.

• The functions must be visible in the same scope.

Note that the parameter type of a function is not affected by whether the parameter is a named parameter or whether the parameter has a default value. In addition, when the parameter type is discussed, a type and its alias are considered to be the same type. For example, the parameter types of the four functions in the following example are the same:

type Boolean = Bool
func f(a : Bool) {}
func f(a! : Bool) {}
func f(a! : Bool = false) {}
func f(a! : Boolean) {}

Example 1: The two functions defined at the top level of the source file have different parameter types. f constitutes overloading.

// f overloading
func f() {...}						
func f(a: Int32) {...}				

Example 2: The f1 function in the I interface, C1 class, and C2 class constitutes overloading.

interface I {
	func f1() {...}			
}

open class C1 {
  func f1(a: Int32) {...}			
}

class C2 <: C1 & I {
    // f1 overloading
    func f1(a: Int32, b: String) {...}
}

Example 3: Constructors of a type constitute overloading.

class C {
    var name: String = "abc"
    
    // constructor overloading
    init(){
        print(name)
    }
    
    init(name: String){
        this.name = name
    }
}

Example 4: In the following example, the number of function parameters is the same, the types at corresponding positions are the same, and only the constraints of the type variables contained in the parameter types are different. This does not constitute overloading.

interface I1{}
interface I2{}

func f<T>(a: T) where T <: I1 {}
func f<T>(a: T) where T <: I2 {} // Error, not overloading

mut Functions

The mut function is a special instance member function. In the mut member function of the struct type, member variables can be modified through this. In the non-mut member function of the struct type, member variables cannot be modified through this.

Definition of the mut Function

The mut function is modified by the mut keyword and can be defined only in the interface, struct, and struct extensions. In addition, it can be used only for instance member functions (static member functions are not supported).

struct A {
    mut func f(): Unit {} // ok
    mut static func g(): Unit {} // error
    mut operator func +(rhs: A): A { // ok
        return A()
    }
}

extend A {
    mut func h(): Unit {} // ok
}

class B {
    mut func f(): Unit {} // error
}

interface I {
    mut func f(): Unit // ok
}

In the mut function, you can assign values to the fields of the struct instance. The values will modify the instance and take effect immediately. Like instance member functions, this is not required and can be inferred by the compiler.

struct Foo {
    var i = 0
    mut func f() {
        this.i += 1 // ok
        i += 1 // ok
    }
}

main() {
    var a = Foo()
    print(a.i) // 0
    a.f()
    print(a.i) // 2
    a.f()
    print(a.i) // 4
    return 0
}

this in the mut function has the following restrictions:

• It cannot be captured (meaning that the fields of the current instance cannot be captured).
• It cannot be used as an expression.

struct Foo {
    var i = 0
    mut func f(): Foo {
        let f1 = { => this } // error
        let f2 = { => this.i = 2 } // error
        let f3 = { => this.i } // error
        let f4 = { => i } // error
        return this //  error
    }
}

mut Function in Interfaces

The struct type must be modified by the same mut modifier when implementing an interface function. When a type other than struct implements an interface function, the mut modifier cannot be used.

interface I {
    mut func f1(): Unit
    func f2(): Unit
}
struct A <: I {
    public mut func f1(): Unit {} // ok
    public func f2(): Unit {} // ok
}
struct B <: I {
    public func f1(): Unit {} // error
    public mut func f2(): Unit {} // error
}
class C <: I {
    public func f1(): Unit {} // ok
    public func f2(): Unit {} // ok
}

Note that when a struct instance is assigned to an interface type, the copy semantics is used. Therefore, the mut function of the interface cannot change the value of the struct instance.

interface I {
    mut func f(): Unit
}
struct Foo <: I {
    var v = 0
    public mut func f(): Unit {
        v += 1
    }
}
main() {
    var a = Foo()
    var b: I = a
    b.f()
    print(a.v) // 0
    return 0
}

Access Rules

If a variable is declared by let and the type may be struct (including the static type being struct, or the type variable might be of the struct type), the variable cannot access the function that is modified by mut. In other cases, the access is allowed.

interface I {
    mut func f(): Unit
}
struct Foo <: I {
    var i = 0
    public mut func f(): Unit {
        i += 1
    }
}
class Bar <: I {
    var i = 0
    public func f(): Unit {
        i += 1
    }
}
main() {
    let a = Foo()
    a.f() // error
    var b = Foo()
    b.f() // ok
    let c: I = Foo()
    c.f() // ok
    return 0
}
func g1<T>(v: T): Unit where T <: I {
    v.f() // error
}
func g2<T>(v: T): Unit where T <: Bar & I {
    v.f() // ok
}

If the type of a variable may be struct (including the static type being struct, or the type variable might be of the struct type), then the variable cannot use functions modified by mut of this type as high-order functions. It can only call those mut functions.

interface I {
    mut func f(): Unit
}
struct Foo <: I {
    var i = 0
    public mut func f(): Unit {
        i += 1
    }
}
class Bar <: I {
    var i = 0
    public func f(): Unit {
        i += 1
    }
}
main() {
    var a = Foo()
    var fn = a.f // error
    var b: I = Foo()
    fn = b.f // ok
    return 0
}
func g1<T>(v: T): Unit where T <: I {
    let fn = v.f // error
}
func g2<T>(v: T): Unit where T <: Bar & I {
    let fn = v.f // ok
}

Non-mut instance member functions (including lambda expressions) cannot access the mut function of this, while the reverse is allowed.

struct Foo {
    var i = 0
    mut func f(): Unit {
        i += 1
        g() // ok
    }
    func g(): Unit {
        f() // error
    }
}

interface I {
    mut func f(): Unit {
        g() // ok
    }
    func g(): Unit {
        f() // error
    }
}

Classes and Interfaces

Classes

Defining Classes

In the Cangjie programming language, the keyword class is used to define a class. The class definition includes the following parts:

• Optional modifiers.
• Keyword class.
• Class name, which must be a valid identifier.
• Optional type parameters.
• Optional superclasses or superinterfaces (write them after <: and use & to separate them) that are specified. If a superclass exists, it must be written first. Otherwise, an error is reported during compilation.
• Optional generic constraints.
• Class body.

A class can be defined only at the top level of a source file. The syntax for defining a class is as follows:

classDefinition
     : classModifierList? 'class' identifier
     typeParameters?
     ('<:' superClassOrInterfaces)?
     genericConstraints?
     classBody
     ;
superClassOrInterfaces
    : classType ('&' superInterfaces)?
    | superInterfaces
    ;    

The following is an example of class definition:

interface I1<X> {}
interface I2 {}
open class A{}

// The following class B inherits class A and implements interface I2.
open class B <: A & I2 {}

/* The following class C declares 1 type parameters U. It inherits B and implements  interfaces I1<U> and I2. Also, its type parameters have constraints U <: A */
class C<U> <: B & I1<U> & I2 where U <: A {}

Class Modifiers

In this section, we will introduce the modifiers that can be used to define classes.

Access Modifiers

Classes can be modified by all access modifiers. The default accessibility is internal. For details, see Access Modifiers in [Packages and Modules].

Inheritance Modifiers

• open: If a class is modified by open, other classes can inherit this class.

  /* The following class is declared with modifier `open`, indicating that it can be inherited. */
  open class C1 {  	
      func foo(): Unit {
          return
      }
  }
  
  class C2 <: C1 {}
  

Note that:

A non-abstract class that is not modified by open cannot be inherited by any class.

• sealed: The class can be inherited only in the package where the class is defined.

  • sealed can only modify abstract classes.

  • sealed contains the semantics of public. Therefore, public is optional when the sealed class is defined.

  • The subclasses of sealed can be non-sealed classes, and can still be modified by open or sealed, or do not use any inheritance modifier. If the subclasses of sealed are modified by both public and open, the subclasses can be inherited outside the package.

  • The subclasses of sealed may not be modified by public.

  // package A
  package A
  public sealed class C1 {}   // OK
  sealed class C2 {}          // OK, 'public' is optional when 'sealed' is used
  
  class S1 <: C1 {}  // OK
  public open class S2 <: C1 {}   // OK
  public sealed class S3 <: C1 {}  // OK
  open class S4 <: C1 {}   // OK
  
  // package B
  package B
  import A.*
  
  class SS1 <: S2 {}  // OK
  class SS2 <: S3 {}  // Error, S3 is sealed class, cannot be inherited here.
  

Note that:

A non-abstract class that is not modified by open or sealed cannot be inherited by any class.

Abstract Class Modifiers

• abstract: belongs to the abstract class. Different from an ordinary class, an abstract class can define ordinary functions and declare abstract functions. Only the class modified by this modifier is an abstract class. A function without a function body is called an abstract function.

  Note that:

  • The abstract modifier of the abstract class contains the semantics that can be inherited. Therefore, the open modifier is optional when the abstract class is defined. You can also use the sealed modifier for the abstract class, indicating that the abstract class can be inherited only in its package.
  • Do not define abstract functions of private in abstract classes.
  • Instances cannot be created for abstract classes.
  • The abstract subclasses of an abstract class are allowed not to implement abstract functions in the class.
  • The non-abstract subclasses of an abstract class must implement all abstract functions in the class.

Class Inheritance

Classes support only single inheritance. A class specifies the direct superclass of the current class with <: superClass (The superclass is a defined class).

The following example shows the syntax of how the C2 class inherits the C1 class:

open class C1 {}
class C2 <: C1 {}

The superclass can be a generic class. You only need to provide a valid type during inheritance. The following example shows the non-generic class C2 and the generic class C3 inherit the generic class C1:

open class C1<T> {}
class C2 <: C1<Int32> {}
class C3<U> <: C1<U> {}

Except for `Object`, every class has its superclass. If a class has no superclass defined, its superclass is `Object` by default.

```cangjie
class Empty {} 	//  Inherit from Object implicitly:  class Empty <: Object {}

Classes support only single inheritance. The syntax in the following example will cause a compilation error.

open class C1 {}
open class C2 {}
class C3 <: C1 & C2 {}		// Error: Multiple inheritance is not supported.

When a class inherits another class, the latter is called a superclass, and the former is called a subclass.

open class C1 {}			// C1 is superclass
class C2 <: C1 {}			// C2 is subclass

A subclass inherits all members of its superclass, except for private members and constructors.

A class can directly access the members of its superclass. However, during overwriting, an overwritten instance member of the superclass cannot be directly accessed by its name. In this case, you can use super to specify the member (super points to the direct superclass of the current class object) or create an object and access the member through the object.

Interface Implementation

A class can implement one or more interfaces. You can use <: I1 & I2 &... & Ik to declare the interfaces to be implemented by the current class. Multiple interfaces are separated by &. If a superclass is also specified by the current class, place the interfaces after the superclass. Example:

interface I1 {}
interface I2 {}

// Class C1 implements interface I1
open class C1 <: I1 {}        

// Class C2 inherits class C1 and implements interface I1, I2.
class C2 <: C1 & I1 & I2 {}

The interfaces can also be generic. In this case, valid type parameters need to be provided when the generic interfaces are implemented. Example:

interface I1<T> {}
interface I2<U> {}
class C1 <: I1<Int32> & I2<Bool> {}
class C2<K, V> <: I1<V> & I2<K> {}

When a type implements an interface, a non-generic interface cannot be directly implemented multiple times, while a generic interface cannot be directly implemented multiple times with the same type parameters. For example:

interface I1 {}
class C1 <: I1 & I1 {} // error

interface I2<T> {}
class C2 <: I2<Int32> & I2<Int32> {} // error
class C3<T> <: I2<T> & I2<Int32> {}  // ok

If the type parameter Int32 is used when the generic class C3 is defined, two interfaces of the same type are implemented. As a result, the compiler reports an error at the position where the type is used.

interface I1<T> {}
open class C3<T> <: I1<T> & I1<Int32> {}  // ok
var a: C3<Int32> // error 
var b = C3<Int32>() // error
class C4 <: C3<Int32> {}// error

For details about the interfaces, see chapter [Interfaces].

Class Body

Class body indicates the content included in the current class. It is enclosed in braces and contains the following content:

• Optional static initializers
• Optional primary constructors
• Optional constructors
• Definitions of optional member variables
• Definitions or declarations of optional member functions and member operator functions
• Definitions or declarations of optional member properties
• Optional macro call expressions
• Optional class finalizers

The syntax of the class body is defined as follows:

classBody
    : '{'  
           classMemberDeclaration*
           classPrimaryInit?
           classMemberDeclaration*
       '}'
    ;
    
classMemberDeclaration
    : classInit
    | staticInit
    | variableDeclaration
    | functionDefinition
    | operatorFunctionDefinition
    | macroExpression
    | propertyDefinition
    | classFinalizer
    ;

The syntax definition of the preceding class body includes the following content:

staticInit: definition of a static initializer. Only one static initializer can be defined for a class.

classPrimaryInit: definition of the primary constructor. Only one can be defined for a class.

classInit: definition of the init constructor.

variableDeclaration: declaration of a member variable.

operatorFunctionDefinition: definition of an overloaded member function of an operator.

macroExpression: macro call expression. After the macro is expanded, it must comply with the syntax definition of classMemberDeclaration.

propertyDefinition: property definition.

classFinalizer: definition of a class finalizer.

The definitions or declarations introduced in the class body are members of the class. For details, see chapter [Members of a Class].

Members of a Class

The members of a class are as follows:

• Members inherited from the superclass (if any).
• If a class implements an interface, its members also include those inherited from the interface.
• Members declared or defined in the class body, including static initializers, primary constructor, init constructor, static member variables, instance member variables, static member functions, instance member functions, static member properties, and instance member properties.

Class members can be categorized by different dimensions:

Members can be classified into static members and instance members based on whether they are modified by static. Static members refer to members that can be accessed without instantiating class objects. Instance members refer to members that can be accessed through objects only after class objects are instantiated.

Members are classified into static initializers, constructors, member functions, member variables, and member properties.

Note that: All static members cannot be accessed by their names.

Constructors

In the Cangjie programming language, there are two types of constructors: primary constructor and init constructor (constructor for short).

Primary Constructor

The syntax of the primary constructor is defined as follows:

classPrimaryInit
    : classNonStaticMemberModifier?  className '(' classPrimaryInitParamLists? ')'
 	  '{'
 	       superCallExression?
 	       ( expression
           | variableDeclaration
           | functionDefinition)*
 	  '}'
	;
	
className
    : identifier
    ;
    
classPrimaryInitParamLists
    : unnamedParameterList (',' namedParameterList)? (',' classNamedInitParamList)?
    | unnamedParameterList (',' classUnnamedInitParamList)? 
        (',' classNamedInitParamList)?
    | classUnnamedInitParamList (',' classNamedInitParamList)?
    | namedParameterList (',' classNamedInitParamList)?
    | classNamedInitParamList  
    ;

classUnnamedInitParamList
    : classUnnamedInitParam (',' classUnnamedInitParam)*
    ;

classNamedInitParamList
    : classNamedInitParam (',' classNamedInitParam)*
    ;

classUnnamedInitParam
    : classNonStaticMemberModifier? ('let'|'var') identifier ':' type
    ;

classNamedInitParam
    : classNonStaticMemberModifier? ('let'|'var') identifier'!' ':' type ('=' expression)?
    ;
   
classNonStaticMemberModifier
    : 'public'
    | 'protected'
    | 'internal'
    | 'private'
    ;

The definition of the primary constructor consists of the following parts:

1. Modifier: optional. The primary constructor can be modified by public, protected, or private. If none of them is used, the primary constructor is visible in the package. For details, see [Access Modifiers].

2.Primary constructor name: same as the type name. Do not use the func keyword before the primary constructor name.

3. Parameter list: Different from the init constructor, the primary constructor has two types of parameters: ordinary parameters and member variable parameters. The syntax and semantics of ordinary parameters are the same as those of parameters in the function definition.

Member variable parameters are introduced to reduce code redundancy. The definition of a member variable parameter includes the definition of a parameter and a member variable. In addition, it indicates the semantics of assigning a value to a member variable through a parameter. Omitted definitions and expressions are automatically generated by the compiler.

• The syntax of member variable parameters is the same as that of member variable definition. In addition, ! can be used to indicate whether a member variable parameter is a named parameter.

• The modifiers of member variables include public, protected, private. For details, see [Access Modifiers].

• Member variable parameters only support instance member variables. That is, they cannot be modified by static.

• A member variable parameter cannot have the same name as a member variable outside the primary constructor.

• A member variable parameter can have no initial value. This is because the compiler generates a corresponding constructor for the primary constructor and assigns values to member variables in the constructor body.

• A member variable parameter can also have initial value. The initial value is used only as the default value of constructor parameter. The initial value expression of a member variable parameter can reference other parameters or member variables (excluding instance member variables defined outside the primary constructor) that have been defined before the member variable is defined, but cannot modify the values of these parameters and member variables. Note that the initial value of the member variable parameter is valid only in the primary constructor and is not included in the member variable definition.

• Member variable parameters cannot be followed by ordinary parameters. In addition, the parameter sequence must comply with that defined in the function. Parameters of named variables cannot be followed by non-named parameters.

4. Primary constructor body: If the constructor of the superclass is explicitly called, the first expression in the function body must be the expression that calls the constructor of the superclass. In addition, this cannot be used to call other constructors in the same class as the primary constructor. After the superclass constructor is called, expressions, local variable declarations, and local function definitions can be written in the primary constructor body. The declarations, definitions, and expressions must meet the rules for using this and super in the init constructor. For details, see [init Constructor].

The following is an example of the primary constructor definition:

class Test{
    static let counter: Int64 = 3
    let name: String = "afdoaidfad"
    private Test( 
        name: String,                  // regular parameter  
        annotation!: String = "nnn",   // regular parameter  
        var width!: Int64 = 1,       // member variable parameter with initial value
        private var length!: Int64,    // member variable parameter
        private var height!: Int64 = 3   // member variable parameter 
    ) {
    }
}

When the primary constructor is defined, ordinary parameters are not allowed after the parameters of member variables. The following is an example:

class Test{
    static let counter: Int64 = 3
    let name: String = "afdoaidfad"
    private Test( 
        name: String,                  // regular parameter  
        annotation!: String = "nnn",   // regular parameter  
        var width!: Int64 = 1,       // member variable parameter with initial value
        length!: Int64          // Error: regular parameters cannot be after member variable parameters 
    ) {
    }
}

The primary constructor is the syntactic sugar of the init constructor. The compiler automatically generates the definitions of the constructor and member variables corresponding to the primary constructor. The constructor is automatically generated as follows:

• Its modifier is the same as that of the primary constructor.
• The sequence of parameters from left to right is the same as that declared in the parameter list of the primary constructor.
• The form of the constructor body is as follows:
  • Values are assigned to member variables in sequence. The syntax format is this.x = x, where x is the member variable name.
  • Code in the primary constructor body.

open class A<X> {
    A(protected var x: Int64, protected var y: X) {
        this.x = x
        this.y = y
    }
}

class B<X> <: A<X> { 
     B(      // primary constructor, it's name is the same as the class
        x: Int64,    // regular parameter
        y: X,        // regular parameter
        v!: Int64 = 1,     // regular parameter
        private var z!: Int64 = v  // member variable parameter
        ) {
          super(x, y)
     }
    
     /* The corresponding init constructor with primary constructor auto-generated
        by compiler.
     
     private var z: Int64  // auto generated member variable definition
     init( x: Int64,    
        y: X,        
        v!: Int64 = 1,
        z!: Int64 = v) {         // auto generated named parameter definition
          super(x, y)
          this.z = z         // auto generated assign expression of member variable
     }
     */
}

A class can define only one primary constructor. In addition to the primary constructor, other constructors can be defined as usual, but other constructors and the constructor corresponding to the primary constructor must be overloaded.

init Constructor

The constructor is specified using the init keyword and cannot contain the func keyword. The return type cannot be explicitly defined for the constructor, and the function body is required. The return type of the constructor is Unit.

The syntax of the constructor is as follows:

Init
    : nonSMemberModifier?  'init' '(' InitParamLists? ')'
 	  '{'
 	       (superCallExression | initCallExpression)?
 	       ( expression
           | variableDeclaration
           | functionDefinition)*
 	  '}'
	;

InitParamLists
  : unnamedParameterList (',' namedParameterList)? 
  | namedParameterList
  ;

You can add an access modifier before init to limit the access scope of the constructor. For details, see [Access Modifiers].

When an object of a class is constructed, the constructor of this class is called. If there is no accessible constructor that matches the parameter type, an error is reported during compilation.

In a class, you can provide multiple init constructors for the class. These constructors must meet the requirements of function overloading. For details, see [Function Overloading].

class C {
    init() {}
    init(name: String, age: Int32) {}
}

The constructor called when creating an instance of a class executes the expressions in the class in the following sequence:

1. Initialize the variables that are defined outside the primary constructor and have default values.

2. If the constructor does not explicitly call the superclass constructor or other constructors of the class, the parameterless constructor super() constructor of the superclass is called. If the superclass does not have a parameterless constructor, an error is reported.

3. Execute the code in the constructor body.

If a class does not define a primary constructor or an init constructor, it attempts to generate a parameterless constructor (public-modified). If the superclass does not have a parameterless constructor or the instance member variables of the class do not have initial values, an error is reported during compilation.

The rules for using constructors, this, and super are as follows:

• Do not use the instance member variable this.variableName and its syntactic sugars variableName and super.variableName as the default values of constructor parameters.
• The init constructor can call either the superclass constructor or other constructors of the current class, but only one of them can be called. If this function is called, it must be called at the first expression in the constructor body. No expression or declaration is allowed before this function is called.
• If the constructor does not explicitly call other constructors or the superclass constructor, the compiler inserts the parameterless constructor of the direct superclass at the beginning of the constructor body. If the superclass does not have a parameterless constructor, a compilation error is reported.
• After the constructor of the superclass or other constructors of the class are called in the constructor body, super.x can be used to access the instance member variable x of the superclass.
• If the constructor does not explicitly call other constructors, ensure that all instance member variables declared by the class are initialized before return. Otherwise, an error is reported during compilation.
• Do not call instance member functions or instance member properties in the constructors of a class that can be inherited.
• Do not allow this escape in the constructors of a class that can be inherited.
• Before all instance member variables are initialized, constructors are forbidden to use implicit parameter transfer, functions or lambda that capture this, super.f to access the instance member method f of the superclass, or independent this expressions. However, this.x or its syntax x can be used to access the initialized member variable x.
• Do not call the constructors of this class through this outside the constructor body.
• Circular dependency between constructors is not allowed. Otherwise, a compilation error will be reported.

var b: Int64 = 1
class A {
    var a: Int64 = 1
    var b: ()->Int64 =  { 3 }    // OK
    
    /* Cannot use lambda which captured `this` before all of the instance member  
       variables are initialized. */
    var c: ()->Int64 =  { a }    // Error
    
    /* Cannot use function which captured `this` before all of the instance member        variables are initialized. */
    var d: ()->Int64 = f       // Error
    
    var e: Int64 = a + 1    // OK
    
    func f(): Int64 {
        return a
    }
}

class B {
    var a: Int64 = 1
    var b: ()->Int64 
    
    init() {
        b =  { 3 }     
    }
    
    init(p: Int64) {
        this()
        b = { this.a } // OK
        b = f   // OK
    }
    
    func f(): Int64 {
        return a
    }
}

var globalVar: C = C()
func f(c: C) {
    globalVar = c
}
open class C {
    init() {
        globalVar = this // Error, `this` cannot escape out of constructors of `open` class
        f(this) // Error, `this` cannot escape out of constructors of `open` class
        m() // Error: calling instance function is forbidden in constructors of `open` class
    }
    
    func m() {}
}

Static Initializers

Static variables in a class or structure can also be initialized by using assignment expressions in a static initializer. Static initializers cannot be used in enumerations and interfaces.

The syntax of a static initializer is as follows:

staticInit
    : 'static' 'init' '(' ')'
    '{'
    expressionOrDeclarations?
    '}'
    ;

The rules of a static initializer are as follows:

• The static initializer is automatically called, but cannot be explicitly called by developers.

• The static initializer is called when the package to which it belongs is loaded, which is similar to the initialization expression of a static variable.

• A class or structure can have only one static initializer.

• For a non-generic class or structure, the static initializer is called only once.

• For a generic class or structure, the static initializer is called only once for instantiation of each different type.

  • Note that the static initializer will not be called at all if the generic class or structure is not instantiated.

• The static initializer is called after all static member variables in the class or structure have been directly initialized, just as the constructor is called after all instance fields have been directly initialized.

  • This means that further declared static member variables can be referenced in the static initializer.

  • This also means that the static initializer can be located anywhere in the class or structure, which does not matter much.

• In the same file, the static initializer is called across classes in a top-down order even if there is an inheritance relationship between the classes.

  • This means that there is no guarantee that all static member variables of the superclass must be initialized before the current class is initialized.

  class Foo <: Bar {
    static let y: Int64
  
    static init() { // called first
      y = x // error: not yet initialized variable
    }
  }
  
  open class Bar {
    static let x: Int64
  
    static init() { // called second
      x = 2
    }
  }
  

• Static member variables must be initialized in only one way, either directly through the expression on the right or in the static initializer.

  • Although a variable static variable can be initialized by assigning a value directly and in the static initializer at the same time, the variable initialization in this case is only a direct assignment, and the assignment in the static initializer is considered as a simple re-assignment. This means that a value is directly assigned to the variable before the static initializer is called.

  • If an immutable static variable is assigned a value directly and in the static initializer at the same time, the compiler reports an error about re-assignment.

    • This error is also reported if multiple values are assigned to an immutable static variable in the static initializer.

  • If a static variable is neither initialized directly nor in the static initializer, the compiler reports an error about the uninitialized variable.

  • The above can be detected by a special initialization analysis, depending on the implementation.

• The static initializer cannot have any parameters.

• The return expression cannot be used in the static initializer.

• Throwing an exception in the static initializer causes the program to terminate, just like throwing an exception in the expression on the right of a static variable.

• Instance member variables or uninitialized static member variables not cannot be used in the static initializer.

• The code of the static initializer is synchronous to prevent leakage of partially initialized classes or structures.

• Static properties, including getter and setter, must be declared completely.

• Unlike static functions, static initializers cannot be used in extensions (within extend).

• Because the static initializer is called automatically and cannot be called explicitly, visibility modifiers (that is, public and private) cannot be used to modify the static initializer.

The following is an example of the initialization analysis rules:

class Foo {
    static let a: Int64
    static var c: Int64
    static var d: Int64 // error: uninitialized variable
    static var e: Int64 = 2
    static let f: Int64 // error: uninitialized variable
    static let g: Int64 = 1

    let x = c

    static init() {
        a = 1
        b = 2

        Foo.c // error: not yet initialized variable
        let anotherFoo = Foo()
        anotherFoo.x // error: not yet initialized variable

        c = 3
        e = 4
        g = 2 // error: reassignment
    }

    static let b: Int64
}

Member Variables

Declaring Member Variables

Variables declared in classes and interfaces are called member variables. A member variable can be declared immutable by using the keyword let or mutable by using the keyword var.

Instance member variables outside the primary constructor can be declared with or without initial values. If there is an initial value, the initial value expression can use this variable to declare the previous member variable. These member variables are initialized before the constructor of the superclass is called. Therefore, the qualified name with super cannot be used to access the member variables of the superclass in the initial value expression.

The following is a code example of variables:

open class A {
    var m1: Int32 = 1
}
class C <: A {
    var a: Int32 = 10
    let b: Int32 = super.m1  // Error
}

Variable Modifiers

Variables in a class can be modified by access modifiers. For details, see Access Modifiers in [Packages and Modules].

In addition, if a variable in a class is modified by static, it is a static variable of the class. static can be used together with other access modifiers. A static variable is inherited by a subclass. The static variable of the subclass is the same as that of the superclass.

class C {
    static var a = 1
}

var r1 = C.a	// ok

Class Member Functions

Declaring and Defining Class Member Functions

You can define functions in a class and declare functions in an abstract class. The difference between definition and declaration is whether the function has a function body.

Class member functions are classified into instance member functions and static member functions.

The syntax for defining or declaring a class member function is as follows:

functionDefinition
    : modifiers 'func' identifier typeParameters? functionParameters (':' returnType)? genericConstraints? (('=' expression) | block)?    
   	;

Instance Member Functions

The first implicit parameter of an instance member function is this. Each time an instance member function is called, a complete object needs to be transferred first. Therefore, do not call an instance member function before the object is created, but the type of the function will not include the implicit parameter. The criterion for determining whether a class object is created is that the constructor of the class has been called.

Instance member functions can be classified into abstract member functions and non-abstract member functions.

Abstract Member Functions

An abstract member function can be declared only in an abstract class or interface. It does not have a function body.

abstract class A {
	public func foo(): Unit		// abstract member function
}

Non-abstract Member Functions

A non-abstract member function can be defined in any class and must have a function body.

class Test {
    func foo(): Unit { // non-abstract member function
        return
    }	
}

By default, abstract instance member functions have the semantics of open. When defining an abstract instance member function in an abstract class, the open modifier is optional, but public or protected must be explicitly specified as its visibility modifier.

Static Member Functions

A static member function is modified by the static keyword. It does not belong to an instance but belongs to its type. In addition, a static function must have a function body.

• Static member functions cannot use instance member variables, call instance member functions, or call the keyword super or this.

• A static member function can reference other static member functions or static member variables.

• Static member functions can be modified by private, protected, public, or internal. For details, see [Access Modifiers].

• When a static member function is inherited by another subclass, the static member function is not copied to the original subclass.

• Static member functions in both abstract and non-abstract classes must have implementations.

Example:

class C<T> {
  static let a: Int32 = 0
  static func foo(b: T): Int32 {
    return a
  }
}

main(): Int64 {
    print("${C<Int32>.foo(3)}")
    print("${C<Bool>.foo(true)}")
    return 0
}

This program has its own static member variable a and static function foo for C<Int32> and C<Bool> respectively.

Static functions in a class can declare new type variables, which can also have constraints. When calling a type variable, you only need to provide a valid type for a class and then a valid type for a static function.

class C<T> {
	static func foo<U>(a: U, b: T): U { a }
}

var a: Bool = C<Int32>.foo<Bool>(true, 1)
var b: String = C<Bool>.foo<String>("hello", false)

func f<V>(a: V): V { C<Int32>.foo<V>(a, 0) }

Modifiers of Class Member Functions

Class member functions can be modified by all access modifiers. For details, see [Access Modifiers].

Other modifiable non-access modifiers are as follows:

• open: If a member function needs to be overridden, use the open modifier. It conflicts with the static modifier. When an instance member with open is inherited by a class, open is also inherited. If a class has members modified by open but the current class is not modified by open or does not contain the open semantics, open is not effective for these members. In this case, the compiler reports a warning. (No warning is reported for inherited open members or override members.)

  A function modified by open must be modified by public or protected.

  // case 1
  open class C1 {        // In this case, the 'open' modifier before 'class C1' is required.
      public open func f() {}
  }
  class C2 <: C1 {
      public override func f() {}
  }
  // case 2
  open class A {
      public open func f() {}
  }
  open class B <: A {}
  class C <: B {
      public override func f() {} // ok
  }
  // case 3
  interface I {
     func f() {}
  }
  open class Base <: I {} // The function f Inherits the open modifier.
  class Sub <: Base {
     public override func f() {} // ok
  }
  

• override: When a function overrides another function that can be overridden, override can be used to modify the function. (override does not have the semantics of open. If a function modified by override needs to be overridden, you need to use open to modify the function.) The example is provided above. For details about function coverage rules, see chapter [Overriding].

• static: The function modified by static is a static member function and must have a function body. Static member functions cannot be modified by open.

  Instance members of the class to which a static member function belongs cannot be accessed within the function. Static members of the class to which an instance member function belongs can be accessed within the function.

  class C {
  	static func f() {}   // Cannot be overwritten and must have a function body.
  }
  

• redef: When a static function redefines a static function inherited from the supertype, redef is an optional modifier for the static function.

  open class C1 {
    static func f1() {}
    static func f2() {}
  }
  class C2 <: C1 {
    redef static func f1() {}
    redef static func f2() {}
  }
  

Class Finalizer

A class finalizer is an instance member function of a class. It is called when an instance of the class is collected as garbage.

class C {
    // below is a finalizer
    ~init() {}
}

The finalizer syntax is as follows:

classFinalizer
    : '~' 'init' '(' ')' block
    ;

1. A finalizer has no parameters, return types, generic type parameters, or modifiers, and cannot be called by users.
2. Classes with finalizers cannot be modified by open. Only non-open classes can have finalizers.
3. Only one finalizer can be defined for a class.
4. Finalizers cannot be defined in extensions.
5. The time when a finalizer is triggered is uncertain.
6. A finalizer may be executed on any thread.
7. The execution sequence of multiple finalizers is uncertain.
8. The behavior of a finalizer throwing an uncaught exception is determined by the implementation.
9. The behavior of creating threads or using thread synchronization in a finalizer is determined by the implementation.
10. After a finalizer is executed, if the object can still be accessed, the consequences are determined by the implementation.
11. Do not use this to escape from a finalizer.
12. Instance members cannot be called in a finalizer.

For example:

class SomeType0 {
    ~init() {} // OK
}
class SomeType1 {
    ~init(x: Int64) {} // Error, finalizer cannot have parameters
}
class SomeType2 {
    private ~init() {} // Error, finalizer cannot have accessibility modifiers
}
class SomeType3 {
    open ~init() {} // Error, finalizer cannot have open modifier
}
open class SomeType4 {
    ~init() {} // Error, open class can't have a finalizer
}

var GlobalVar: SomeType5 = SomeType5()
class SomeType5 {
    ~init() {
        GlobalVar = this // do not escape `this` out of finalizer, otherwise, unexpected behavior may happen.
    }
}

Class Member Properties

You can also define member properties in a class. For details about the syntax for defining member properties, see chapter [Properties].

Instantiating Classes

After defining a non-abstract class type, you can create a class instance. There are two methods of creating a class instance based on whether the instance contains type variables:

1. Create an instance of the non-general type class: ClassName. ClassName indicates the name of the class type, and arguments indicates the argument list. The ClassName(arguments) function calls the corresponding constructor based on the calling rule of overloaded functions (see [Function Overloading]), and then generates an instance of the ClassName function. For example:

class C {
    var a: Int32 = 1
    init(a: Int32) {
        this.a = a
    }
    init(a: Int32, b: Int32) {
        this.a = a + b
    }
}

main() : Int64 {
    var myC = C(2)      // invoke the first constructor
    var myC2 = C(3, 4)  // invoke the second constructor
    return 0
}

2.Create an instance of the generic class: ClassName<Type1, Type2, ..., TypeK>(arguments). The only difference between creating an instance of a generic class and creating an instance of a non-generic class is whether generic parameters need to be instantiated. Generic arguments can be explicitly specified or omitted (in this case, the compiler infers the specific type based on the program context). For example:

class C<T, U> {
    var a: T 
    var b: U
    init(a: T, b: U) {
        this.a = a
        this.b = b
    }
}

main() : Int64 {
    var myC = C<Int32, Int64>(3, 4)
    var myC2 = C(3,4)   // The type of myC2 is inferred to C<Int64, Int64>.
    return 0
}

Object Class

The Object class is the superclass of all class types (excluding the interface type). The Object class does not contain any member. That is, the Object class is an empty class. There are parameterless constructors modified by public in the Object class.

This Type

In a class, the This type placeholder is supported. It can be used only as the return type of the instance member function. During compilation, it is replaced with the type of the class to which the function belongs for type check.

1. If the return type of a function is This, the function can return only the expression of the This type.
2. The expression of the This type contains this and other functions that return This.
3. The This type is the subtype of the current type. The This type can be automatically cast to the current type, but the latter cannot be cast to the former.
4. The This type cannot be explicitly used in the function body. If a This type expression is not used in return values, the current type is inferred.
5. If an instance member function only has the This expression without declaring the return type, its return type is inferred as This.
6. When an open function that contains This is overridden, the return type must remain This.
7. If the open function in the superclass returns the type of the superclass, the subclass can use This as the return type when it is overridden.

open class C1 {
	func f(): This {  // its type is `() -> C1`
	    return this
    }
    
    func f2() { // its type is `() -> C1`
        return this
    }
    
    public open func f3(): C1 {
        return this
    }
}

class C2 <: C1 {
	// member function f is inherited from C1, and its type is `() -> C2` now
    
    public override func f3(): This { // ok
        return this
    }
}

var obj1: C2 = C2()
var obj2: C1 = C2()

var x = obj1.f()	// During compilation, the type of x is C2 
var y = obj2.f()	// During compilation, the type of y is C1 

Interfaces

An interface is used to define an abstract type. It does not contain data but can define the behavior of the type. If a type declares that it implements an interface and all members of the interface, it is considered that the interface is implemented.

The members of an interface can include instance member functions, static member functions, operator overloading functions, instance member properties, and static member properties. These members are abstract, but the default implementations can be defined for functions and properties.

Defining Interfaces

Syntax for Defining Interfaces

An interface is defined using the keyword interface in the following sequence: modifier (default or not), interface keyword, interface name, optional type parameter, whether to specify a superinterface, optional generic constraint, and interface body.

The following are some interface definitions:

interface I1 {}
public interface I2<T> {}
public interface I3<U> {}
public interface I4<V> <: I2<V> & I3<Int32> {}

The syntax for interfaces is defined as follows:

interfaceDefinition
    : interfaceModifierList? 'interface' identifier
    typeParameters?
    ('<:' superInterfaces)?
    genericConstraints?
    interfaceBody
    ;

The interface can be defined only at the top level.

The {} of the interface body cannot be omitted.

interface I {}		// {} not allowed to be omitted

Modifiers of an Interface

In this section, we will introduce the modifiers that can be used to define interfaces.

Access Modifiers

• By default, if the access modifier is not used, the access can be performed only inside a package. You can also use the public modifier so that the package can be accessed externally.

  public interface I {}  // can be accessed outside the package
  interface I2 {}		// can only be accessed inside the package
  

Inheritance Modifiers

• By default, if the inheritance modifier is not used, an interface has the semantics modified by open. The interface can be inherited, implemented, or extended at any position where the interface can be accessed. Certainly, the open modifier may also be used explicitly. In addition, you can use the sealed modifier to indicate that the interface can be inherited, implemented, or extended only in the package where the interface is defined.
• sealed contains the semantics of public. Therefore, public is optional when the sealed interface is defined.
• Interfaces that inherit or classes that implement the sealed interface can still be modified by sealed optionally. If the subinterface of the sealed interface is modified by public and not by sealed, the subinterface can be inherited, implemented, or extended outside the package.
• The type that inherits and implements the sealed interface may not be modified by public.

// package A
package A
public sealed interface I1 {}   // OK
sealed interface I2  {}         // OK, 'public' is optional when 'sealed' is used
open interface I3 {}            // OK
interface I4  {}                // OK, 'open' is optional

class C1 <: I1 {}  // OK
public open class C2 <: I1 {}   // OK
public sealed class C3 <: I1 {}  // OK
extend Int64 <: I1 {}   // OK

// package B
package B
import A.*

class S1 <: C2 {}  // OK
class S2 <: C3 {}  // Error, C3 is sealed class, cannot be inherited here.

Interface Members

An interface has the following members:

• Members declared in the interface body (that is, in {}): static member functions, instance member functions, operator overloading functions, static member properties, and instance member properties.

• Members inherited from other interfaces. In the following example, the members of I2 include the members that can be inherited from I1:

  interface I1 {
     func f(): Unit
  }
  interface I2 <: I1 {}
  

The BNF of interface members is as follows:

interfaceMemberDeclaration    
       : (functionDefinition|macroExpression|propertyDefinition) end*   
       ;

Functions in an Interface

Declaring and Defining Functions in an Interface

An interface can contain instance member functions and static member functions. These functions are compiled in the same way as ordinary instance member functions and static member functions, but may not be implemented. These functions are called abstract functions.

An abstract function with an implementation is called a function with a default implementation.

The following is an example of an abstract function:

interface MyInterface {
    func f1(): Unit // Default implementation not included
    static func f2(): Unit // Default implementation not included

    func f3(): Unit { // Default implementation included
        return
    }
    static func f4(): Unit { // Default implementation included
        return
    }
}

An abstract function can have named parameters without default values.

interface MyInterface {
    func f1(a!: Int64): Unit // OK
    func f2(a!: Int64 = 1): Unit // Error, cannot have parameter default values
}

Modifiers of Functions and Properties in an Interface

If a function or property defined in an interface contains the public semantics and is modified by public, a compilation alarm is generated. Do not use the protected, internal, or private modifier to modify the functions or properties defined in an interface.

The following is an incorrect example:

interface MyInterface {
    public func f1(): Unit // Access modifiers cannot be used
    private static func f2(): Unit // Access modifiers cannot be used
}

A function modified by static is called a static member function, which can have no function body. The static function without a function body cannot be directly called using an interface type. The static function with a function body can be called using an interface type. When the type name of an interface is used to directly call its static member function, if the function directly or indirectly calls other static functions that are not implemented in the interface (or other interfaces), an error is reported during compilation.

interface I {
    static func f1(): Unit
    static func f2(): Unit {}
    static func f3(): Unit {
        f1()
    }
}

main() {
    I.f1() // Error, cannot directly call
    I.f2() // OK
    I.f3() // Error, f1 not implemented
}

By default, the instance member functions in the interface have the semantics of open. The open modifier is optional in defining instance member functions in an interface.

interface I {
    open func foo1() {} // ok
    func foo2() {}      // ok
} 

A function modified by mut is a special instance member function, which can be used to abstract the variable behavior of the struct type.

interface I {
    mut func f(): Unit
}

Member Properties in an Interface

You can also define member properties in an interface. For details about the syntax for defining member properties, see [Properties].

Default Implementations of an Interface

Abstract functions and abstract properties in an interface can have default implementations.

When an interface is inherited or implemented by another interface or type, if it is not re-implemented, its default implementations are copied to its subtype.

1. In the default implementation of an instance member function, this can be used. The type of this is that of the current interface.
2. Default implementations, like non-abstract member functions, can access all accessible elements in the current scope.
3. Default implementations are a type of syntax sugar that provides a default behavior for the implementation type. An interface can use the default implementations of its superinterface.
4. The default implementation does not belong to the inheritance semantics. Therefore, override, redef, or super cannot be used.
5. If the subtype of an inherited interface is a class, the open semantics is retained by default and can be overridden by the subclasses of the class.

interface I {
    func f() { // f: () -> I
        let a = this // a: I
        return this
    }
}

Interface Inheritance

An interface can inherit one or more interfaces.

interface I1<T> {}
interface I2 {}
interface I3<U> <: I1<U> {}	// inherit a generic interface.
interface I4<V> <: I1<Int32> & I2 {} // inherit multiple interfaces.

When a subinterface inherits its superinterface, it inherits all members of the superinterface.

A non-generic interface cannot be directly inherited for multiple times, and a generic interface cannot be directly inherited for multiple times using the same type of parameters. For example:

interface I1 {}
interface I2 <: I1 & I1 {} // error

interface I3<T> {}
interface I4 <: I3<Int32> & I3<Int32> {} // error
interface I5<T> <: I3<T> & I3<Int32> {}  // ok

If the type parameter of the generic interface I3 is set to Int32, the compiler reports an error at the position where the type is used.

interface I1<T> {}
interface I2<T> <: I1<T> & I1<Int32> {}  // ok
interface I3 <: I2<Int32> {} // error

main() {
    var a: I2<Int32> // error 
}

Default Implementations of a Subinterface

If an interface inherits a function or property without a default implementation from its superinterface, only the declaration of the function or property can be written in the interface (the default implementation can also be defined). In addition, the override or redef modifier before the function declaration or definition is optional. Example:

interface I1 {
    func f1(): Unit
    static func f2(): Unit
}
interface I2 <: I1 {
    func f1(): Unit        // ok
    static func f2(): Unit // ok
}
interface I3 <: I1 {
    override func f1(): Unit     // ok
    redef static func f2(): Unit // ok
}
interface I4 <: I1 {
    func f1(): Unit {}        // ok
    static func f2(): Unit {} // ok
}
interface I5 <: I1 {
    override func f1(): Unit {}     // ok
    redef static func f2(): Unit {} // ok
}

If an interface inherits a function or property with a default implementation from its superinterface, it is not allowed to write only the declaration of the function or property in the interface without implementation. If a new default implementation is provided in the interface, the override or redef modifier before the definition is optional. Example:

interface I1 {
    func f1(): Unit {}
    static func f2(): Unit {}
}
interface I2 <: I1 {
    func f1(): Unit        // error, 'f1' must has a new implementation
    static func f2(): Unit // error, 'f2' must has a new implementation
}
interface I3 <: I1 {
    override func f1(): Unit {}     // ok
    redef static func f2(): Unit {} // ok
}
interface I4 <: I1 {
    func f1(): Unit {}        // ok
    static func f2(): Unit {} // ok
}

If an interface inherits the default implementations with the same signature member from its superinterfaces, the interface must provide new default implementations of its own version. Otherwise, a compilation error is reported.

interface I1 {
    func f() {}
}
interface I2 {
    func f() {}
}
interface I3 <: I1 & I2 {} // error, I3 must implement f: () -> Unit

Interface Implementation

Overriding and Overloading During Interface Implementation

When a type implements one or more interfaces, the rules are as follows:

1. When a type that is not of the abstract class implements an interface, it must implement all functions and properties.
2. When an abstract class implements an interface, it is allowed not to implement the functions and properties in the interface.
3. The name and parameter list of the implementation function must be the same as those of the corresponding function in the interface.
4. The return type of the implementation function must be the same as or a subtype of the corresponding function in the interface.
5. For a generic function in an interface, the type variable constraint of the function must be looser or the same as that of the corresponding function in the interface.
6. The mut modifier of the implementation property must be the same as the corresponding property in the interface.
7. The type of the implementation property must be the same as the corresponding property in the interface.
8. If multiple interfaces have only one default implementation of the same function or property, it is allowed not to implement the function or property but use the default implementation.
9. If multiple interfaces contain multiple default implementations of the same function or property, the function or property must be implemented. The default implementation cannot be used.
10. If the same function or property in the interface already has the implementation type (inherited from the superclass or defined by the current class), the default implementation in any interface will not be used.
11. When a type implements an interface, the override modifier (or redef modifier) before the definition of a function or property is optional, regardless of whether the function or property in the interface has a default implementation.

In the following example: when a type that is not of the abstract class implements an interface, the abstract functions and abstract properties in the interface must be implemented, like f1 and f3; the default implementation of a function in the interface can be omitted, like f2; the abstract class is allowed not to implement the instance member functions in the interface, like the abstract class C1 that does not implement f1 in the interface I.

interface I {
    func f1(): Unit
    func f2(): Unit {
        return
    }
    static func f3(): Int64
}
class C <: I {
    public func f1(): Unit {}
    public func f2(): Unit {
        return
    }
    public static func f3(): Int64 {
        return 0
    }
}

abstract class C1 <: I {
    public static func f3(): Int64 {
        return 1
    }
}

Example: f and g in the I interface are generic functions and the E and F classes meet the requirement that the type variable constraints of the implementation functions are looser than or same as those of the implemented functions, so the compilation is successful. Class D does not meet the requirement, so an error is reported for the compilation.

// C <: B <: A
interface I {
    static func f<T>(a: T): Unit where  T <: B
    static func g<T>(): Unit where T <: B
}

class D <: I  {
    public static func f<T>(a: T) where T <: C {} // Error, stricter constraint
    public static func g<T>() where T <: C {} // Error, stricter constraint
}

class E <: I  {
    public static func f<T>(a: T) where T <: A {} // OK, looser constraint
    public static func g<T>() where T <: A {} // OK, looser constraint
}

class F <: I  {
    public static func f<T>(a: T) where T <: B {} // OK, same constraint
    public static func g<T>() where T <: B {} // OK, same constraint
}

More examples:

// case 1
interface I1 {
    func f(): Unit
}
interface I2 {
    func f(): Unit
}
class A <: I1 & I2 {
    public func f(): Unit {} // ok
}

// case 2
interface I1 {
    func f(): Unit
}
interface I2 {
    func f(): Unit {}
}
open class A {
    public open func f(): Unit {} // ok
}
class B <: A & I1 & I2 {
    public override func f(): Unit {} // ok
}

// case 3
interface I1 {
    func f(): Unit
}
interface I2 {
    func f(): Unit {}
}
class A <: I1 & I2 {} // ok, f from I2

// case 4
interface I1 {
    func f(): Unit {}
}
interface I2 {
    func f(): Unit {}
}
class A <: I1 & I2 {} // error
class B <: I1 & I2 { // ok,
    public func f(): Unit {}
}

// case 5
interface I1 {
    func f(a: Int): Unit {}
}
interface I2  {
    func f(a: Int): Unit {}
}

open class A  {
    public open func f(a: Int): Unit {}
}
open class B <: A & I1 & I2{ // ok, f from A
}

Rules for Overloading Functions During Interface Implementation

The functions in the parent and child scope must use the same names but different parameter lists.

The following examples show some cases of function overloading when a type implements an interface. Note that when a type implements an interface, implementation needs to be provided for the overloaded function declaration.

Example 1: In I1 and I2, the function f is declared with different parameter lists respectively. During class C implementation, fs whose parameter type is Unit and Int32 are implemented at the same time.

interface I1 {
    func f(): Unit
}
interface I2 {
    func f(a: Int32): Unit
}
class C <: I1 & I2 {
    public func f(): Unit {}        // The f in I1 needs to be implemented.
    public func f(a: Int32): Unit {}     // The f in I2 needs to be implemented.
}

Example 2: In I1 and I2, the default function f is defined with different parameter lists respectively. f does not need to be implemented in C.

interface I1 {
    func f() {}
}
interface I2 {
    func f(a: Int32) {}
}
class C <: I1 & I2 {
}

Example 3: In I1, a function whose name is f and parameter type is Unit is declared. In I2, a function whose name is f and parameter type is Int32 is defined. In class C, the f function whose parameter type is Unit must be implemented.

interface I1 {
    func f(): Unit
}
interface I2 {
    func f(a: Int32):Unit {
        return
    }
}
class C <: I1 & I2 {
    public func f(): Unit {
        return
    }
}

Any Interface

The Any interface is an empty interface built in the language. By default, all interface types inherit the Any interface, and all non-interface types implement the Any interface. Therefore, all types can be used as subtypes of the Any type.

class A {}

struct B {}

enum C { D }

main() {
    var i: Any = A() // ok
    i = B() // ok
    i = C.D // ok
    i = (1, 2) // ok
    i = { => 123 } // ok
    return 0
}

The Any interface can be explicitly declared in the type definition. If the Any interface is not explicitly declared, it will be implicitly implemented by the compiler. However, the Any interface cannot be re-implemented through extension.

class A <: Any {} // ok

class B {} // Implicit implement Any

extend B <: Any {} // error

Overriding, Overloading, Hiding, and Redefinition

Overriding

Definition of Overriding

When you define a non-abstract instance function for a type with the same name and open semantics as that of its supertype, the optional override can be used as the modifier to override the function of the supertype. Comply with the following rules when overriding functions:

• The name of the function must be the same as that of the function to be overridden.

• The parameter list of the function must be the same as that of the function to be overridden.

  The same parameter list means that the functions have the same parameter types and number of parameters.

• The return type of the function is the same as or its subtype of that of the function to be overridden.

• If functions in multiple parent scopes are overridden by the same function, the overriding rule for each function is determined by the other rules above.

Example:

• If the function f in the I interface has the same parameter list and return type for the C1 and C2 classes, the overriding requirements are met.

• If f1 has the same parameter list for the C1 and C2 classes, the return type in C1 is Father, and the return type in C2 is Child, the overriding requirements are met because Child is a subtype of Father.

open class Father {}
class Child <: Father {}

open class C1 {
    public open func f() {}
    public open func f1(): Father { Father() }
}

interface I {
    func f() {}
}

class C2 <: C1 & I {
    public override func f() {}                  // OK.
    public override func f1(): Child { Child() } // OK.
}

Some of the details to note include:

1. Functions modified by private in a class are not inherited and cannot be accessed in subclasses.

2. Static functions cannot override instance functions.

Calling Overriding Functions

If a function of a type overrides a function of its supertype and the function is called in the program, the compiler selects the version of the function to be executed based on the type to which the runtime object points.

In the following example, the f function is defined in the C1 class. The subclass C2 of C1 overrides f. In addition, the a and b variables of the C1 type are defined, the object myC1 of C1 is assigned to a, and the object myC2 of C2 is assigned to b. When a and b are used to call f, the corresponding function is selected based on the actual type at runtime.

open class C1 {
    public open func f(): Unit {
        return
    }
}
class C2 <: C1 {
    public override func f(): Unit {
        return
    }
}

var myC1 = C1()
var myC2 = C2()

// Assign the object of the superclass C1 to the variable of the C1 type.    
var a: C1 = myC1
// Assign the object of the superclass C2 to the variable of the C1 type.
var b: C1 = myC2

// Invokes f of C1 based on the object type of at runtime
var c = a.f()
// Invokes f of C2 based on the object type of at runtime
var d = b.f()

Overloading

For details about the definition and calling of function overloading, see chapter [Function Overloading].

Overloading is not allowed between static member functions and instance member functions of classes or interfaces. If a static member function and an instance member function of a class or interface (such as a member function defined by the class or interface and inherited from the superclass or superinterface) have the same name, a compilation error is reported.

open class Base {}
class Sub <: Base {}
open class C{
    static func foo(a: Base) {        
    }
}
open class B <: C {
    func foo(a: Sub) {   // Error
        C.foo(Sub()) 
    }  
}

class A <: B {
    // Static and instance functions cannot be overloaded.
    static func foo(a: Sub) {}  // Error
}

During overloading resolution, the functions defined in a type and its subtype are treated in the same scope priority.

Hiding

Members of a type cannot hide members of its supertype. Otherwise, a compilation error is reported.

In the following example, both the C1 and C2 classes have the instance variable x with the same name. As a result, an error is reported during compilation.

open class C1 {
	let x = 1
}
class C2 <: C1 {
	let x = 2 // error
}

Redefinition

Redefining a Function

When you define a non-abstract static function for a type with the same name as that of its supertype, the optional redef can be used as the modifier to redefine the function of the supertype. Comply with the following rules when redefining functions:

• The name of the function must be the same as that of the function to be redefined.

• The parameter list of the function must be the same as that of the function to be redefined.

  The same parameter list means that the functions have the same parameter types and number of parameters.

• The return type of the function is the same as or its subtype of that of the function to be redefined.

• If the function to be redefined is a generic function, the type variable constraints of the redefining function must be looser or the same as those of the function to be redefined.

• If functions in multiple parent scopes are redefined by the same function, the redefinition rule for each function is determined by the other rules above.

Example:

• If the f function has the same parameter list and return types for the C1 and C2 classes, the redefinition requirements are met.

• If f1 has the same parameter list for the C1 and C2 classes, and the return type in C1 is Father, and the return type in C2 is Child, the redefinition requirements are met because Child is a subtype of Father.

open class Father {}
class Child <: Father {}

open class C1 {
    public static func f() {}
    public static func f1(): Father { Father() }
}

interface I {
    static func f() {}
}

class C2 <: C1 & I {
    public redef static func f() {}                  // OK.
    public redef static func f1(): Child { Child() } // OK.
}

Example: If the f and g functions in the Base class are generic functions, and the subclasses E and F meet the requirements that a redefining function has looser or the same type variable constraints as the function to be redefined, the compilation is successful. If the subclass D does not meet the requirements, an error is reported during the compilation.

// C <: B <: A
open class Base {
    static func f<T>(a: T): T where T <: B {...}
    static func g<T>(): T where T <: B {...}
}

class D <: Base  {
    redef static func f<T>(a: T): T where T <: C {...} // Error, stricter constraint
    redef static func g<T>(): T where T <: C {...} // Error, stricter constraint
}

class E <: Base  {
    redef static func f<T>(a: T): T where T <: A {...} // OK, looser constraint
    redef static func g<T>(): T where T <: A {...} // OK, looser constraint
}

class F <: Base  {
    redef static func f<T>(a: T): T where T <: B {...} // OK, same constraint
    redef static func g<T>(): T where T <: B {...} // OK, same constraint
}

The redef modifier cannot be used for a static initializer (because static initializers cannot be explicitly called). Otherwise, the compiler reports an error.

Calling a Redefined Function

If a function of a type redefines that of its supertype and the function is called in a program, the compiler selects which version of the function to execute based on the type.

In the following example, the f function defined in the C1 class is redefined in its subclass C2. When C1 and C2 are used to call f, the corresponding function is selected based on their types during compilation.

open class C1 {
    static func f(): Unit {
        return
    }
}
class C2 <: C1 {
    redef static func f(): Unit {
        return
    }
}

// Invokes f of C1
var c = C1.f()
// Invokes f of C2
var d = C2.f()

Access Control Level Restriction

Access modifiers within types are ranked at different levels based on their access scopes as follows:

• public > protected > default > private

In this context, the behavior across access levels is specified as follows:

• When a class inherits another class, if an instance member function of the subclass overrides that of the superclass, or a static member function of the subclass redefines that of the superclass, the access level of the subclass member function cannot be lower than that of the superclass member function.

• When a type implements an interface, if a member function of the type implements an abstract function in the interface, the access level of the member function of the type cannot be lower than that of the abstract function.

The following is a code example of access level restriction:

open class A {
    protected open func f() {}
}
interface I {
    func m() {} // public by default
}
class C <: A & I {
    private override func f() {} // Error: the access control of override function is lower than the overriden function
    protected func m() {} // Error: the access control of function which implements abstract function is lower than the abstract function
}

Access Modifiers of a Non-top-level Member

The semantics of different access modifiers for non-top-level members are as follows:

• private: visible only to the current type or extended definition.
• internal: visible only in the current package and its subclasses (including nested subclasses).
• protected: visible in the current module and the subclasses of the current class.
• public: visible in and out of the module.

The access modifier of a type member can be different from that of the type itself. The default modifier for a type member except interface is internal. (Default modifiers specify the modifier semantics when modifiers are omitted. These default modifiers can also be explicitly written.) The member functions and properties in interfaces cannot write access modifiers. Their access level is public.

Restrictions on the Use of Generics in Classes and Interfaces

Duplicate Function Signatures Due to Instantiation Types

When you define a generic class, the following definitions of the C1 class and member functions are valid because functions can be overloaded.

open class C1<T> {
    public func c1(a: Int32) {}  // ok
    public func c1(a: T) {}  // ok
}

interface I1<T> {
    func i1(a: Int32): Unit // ok
    func i1(a: T): Unit // ok
}

var a = C1<Int32>() // error
class C2 <: C1<Int32> {...} // error
var b: I1<Int32> // error
class C3 <: I1<Int32> {...} // error

However, when the C1<T> class needs to be instantiated as the C1<Int32> class, the signatures of the two functions are the same. In this case, an error is reported where the C1<Int32> type is used. Similarly, when the I1<Int32> interface needs to be instantiated, the two function signatures declared in the interface are duplicate. In this case, an error is reported.

Generic Member Functions of Classes and Interfaces

In Cangjie, generic parameters cannot be declared for non-static abstract functions and functions modified by the open keyword in classes.

interface Bar {
    func bar<T>(a: T): Unit // error
}

abstract class Foo {
	func foo<T>(a: T): Unit // error
    public open func goo<T>(a: T) { } // error
}

class Boo {
    public open func Boo<T>(a: T) { } // error
}

For more information, see [Generics].

Properties

A property is a special syntax. It does not store values like a field. Instead, it provides a getter and an optional setter to indirectly retrieve and set values.

By using properties, data operations can be encapsulated into access functions. The use of properties is the same as that of common fields, which means that you can perform data operations without being aware of the underlying implementation. In this way, mechanisms such as access control, data monitoring, tracing and debugging, and data binding can be implemented easily.

Properties have the same syntax as fields and can be used as expressions or assigned values.

The following is a simple example where b is a typical property that encapsulates external access to a.

class Foo {
    private var a = 0
    mut prop b: Int64 {
        get() {
            print("get")
            a
        }
        set(value) {
            print("set")
            a = value
        }
    }
}

main() {
    var x = Foo()
    let y = x.b + 1 // get
    x.b = y // set
}

Property Syntax

The syntax rules of properties are as follows:

propertyDefinition
    : propertyModifier* 'prop' identifier ':' type propertyBody?
    ;

propertyBody
    : '{' propertyMemberDeclaration+ '}'
    ;

propertyMemberDeclaration
    : 'get' '(' ')' block end*
    | 'set' '(' identifier ')' block end*
    ;

propertyModifier
    : 'public'
    | 'private'
    | 'protected'
    | 'internal'
    | 'static'
    | 'open'
    | 'override'
    | 'redef'
    | 'mut'
    ;

Properties without the mut modifier require a getter implementation. Properties declared by the mut modifier require separate getter and setter implementations.

In particular, you cannot define properties modified by mut or implement interfaces that have mut properties within extensions or definition bodies of the numeric, Bool, Unit, Nothing, Rune, String, Range, Function, Enum, and Tuple types.

In the following example, a is a property not declared by mut, and b is a property declared by mut.

class Foo {
    prop a: Int64 {
        get() {
            0
        }
    }
    mut prop b: Int64 {
        get() {
            0
        }
        set(v) {}
    }
}

Properties not declared by mut do not have setters. Like fields declared by let, they cannot be assigned values.

class A {
	prop i: Int64 {
		get() {
			0
		}
	}
}
main() {
    var x = A()
    x.i = 1 // error
}

Specifically, when a struct instance is declared by let, you cannot assign values to properties in the struct, just like fields declared by let.

struct A {
	var i1 = 0
    mut prop i2: Int64 {
        get() {
            i1
        }
        set(value) {
            i1 = value
        }
    }
}
main() {
    let x = A()
    x.i1 = 2 // error
    x.i2 = 2 // error
}

Properties differ from fields in that they cannot have initial values assigned and must have their types declared.

Property Definition

Properties can be defined in interfaces, classes, structs, enums, and extends.

class A {
    prop i: Int64 {
        get() {
            0
        }
    }
}

struct B {
    prop i: Int64 {
        get() {
            0
        }
    }
}

enum C {
    prop i: Int64 {
        get() {
            0
        }
    }
}

extend A {
    prop s: String {
        get() {
            ""
        }
    }
}

You can declare an abstract property in an interface and abstract class, and its definition body can be omitted. When an abstract property is implemented in an implementation type, its name, type, and mut modifier must remain unchanged.

interface I {
    prop a: Int64
}

class A <: I {
    public prop a: Int64 {
        get() {
            0
        }
    }
}

Just as abstract functions in an interface can have default implementations, abstract properties in an interface can also have default implementations.

When an abstract property has a default implementation, the implementation type is not required to provide its own implementation (as long as it complies with the usage rules of the default implementation).

interface I {
    prop a: Int64 { // ok
        get() {
            0
        }
    }
}
class A <: I {} // ok

Properties are classified into instance member properties and static member properties. Instance member properties can be accessed only by instances. You can use this expression in the getter or setter implementation of the property to access other instance members and static members. You cannot access instance members in the implementation of static member properties.

class A {
    var x = 0
    mut prop X: Int64 {
        get() {
            x + y
        }
        set(v) {
            x = v + y
        }
    }
    static var y = 0
    static mut prop Y: Int64 {
        get() {
            y
        }
        set(v) {
            y = v
        }
    }
}

Properties do not support overloading or overriding, and they cannot have the same name as other members at the same level.

open class A {
	var i = 0
	prop i: Int64 { // error
		get() {
			0
		}
	}
}
class B <: A {
    prop i: Int64 { // error
		get() {
			0
		}
	}
}

Property Implementation

The getter and setter of a property correspond to two different functions.

1. The getter function has the type ()->T, where T is the type of the property. When the property is used as an expression, the getter function is executed.
2. The setter function has the type (T)->Unit, where T is the type of the property, and the parameter name must be explicitly specified. The setter function is executed when the property is assigned a value.

The implementation rules of properties are the same as those of functions. Properties can contain declarations and expressions, return can be omitted, and the return value must comply with the return type.

class Foo {
    mut prop a: Int64 {
        get() { // () -> Int64
            "123" // error
        }
        set(v) { // (Int64) -> Unit
            123
        }
    }
}

The behavior of accessing a property is consistent both inside and outside the property. Therefore, recursive access to a property may cause an infinite loop, which is the same as that of a function.

class Foo {
    prop i: Int64 {
        get() {
            i // dead loop
        }
    }
}

Note that the setter of struct is a mut function. Therefore, you can modify the values of other fields in the setter, and this is restricted by the mut function.

Modifiers for Properties

Similar to functions, properties can be modified using modifiers. However, only the entire property can be modified. The getter or setter cannot be modified independently.

class Foo {
	public mut prop a: Int64 { // ok
        get() {
            0
        }
        set(v) {}
    }
    mut prop b: Int64 {
        public get() { // error
            0
        }
        public set(v) {} // error
    }
}

Access control modifiers private, protected, and public can be used for properties.

class Foo {
    private prop a: Int64 { // ok
        get() { 0 }
    }
    protected prop b: Int64 { // ok
        get() { 0 }
    }
    public static prop c: Int64 { // ok
        get() { 0 }
    }
}

Like an instance function, an instance property can be modified using open and override.

For properties modified by open, a subtype can use override to override the implementation of the supertype (override is optional).

open class A {
    public open mut prop i: Int64 {
        get() { 0 }
        set(v) {}
    }
}
class B <: A {
    override mut prop i: Int64 {
        get() { 1 }
        set(v) {}
    }
}

Static properties, like static functions, can be modified using redef (redef is optional), allowing a subtype to re-implement the static properties from the supertype.

open class A {
    static mut prop i: Int64 {
        get() { 0 }
        set(v) {}
    }
}
class B <: A {
    redef static mut prop i: Int64 {
        get() { 1 }
        set(v) {}
    }
}

When a subtype uses override or redef on properties that are declared by let, it must re-implement the getter.

When a subtype uses override or redef on properties that are declared by the mut modifier in the supertype, it is allowed to re-implement only the getter or the setter, or both.

open class A {
    public open mut prop i1: Int64 {
        get() { 0 }
        set(v) {}
    }
    static mut prop i2: Int64 {
        get() { 0 }
        set(v) {}
    }
}

// case 1
class B <: A {
    public override mut prop i1: Int64 {
        get() { 1 } // ok
    }
    redef static mut prop i2: Int64 {
        get() { 1 } // ok
    }
}

// case 2
class B <: A {
    public override mut prop i1: Int64 {
        set(v) {} // ok
    }
    redef static mut prop i2: Int64 {
        set(v) {} // ok
    }
}

// case 3
class B <: A {
    override mut prop i1: Int64 {} // error
    redef static mut prop i2: Int64 {} // error
}

When a subtype uses override or redef on properties, it must retain the same mut modifier and the same type as that in the supertype.

class P {}
class S {}

open class A {
    open prop i1: P {
        get() { P() }
    }
    static prop i2: P {
        get() { P() }
    }
}

// case 1
class B <: A {
    override mut prop i1: P { // error
        set(v) {}
    }
    redef static mut prop i2: P { // error
        set(v) {}
    }
}
// case 2
class B <: A {
    override prop i1: S { // error
        get() { S() }
    }
    redef static prop i2: S { // error
        get() { S() }
    }
}

When a subtype uses override on a supertype's property, it can use super to call the instance property of the supertype.

open class A {
    open prop v: Int64 {
        get() { 1 }
    }
}
class B <: A {
    override prop v: Int64 {
        get() { super.v + 1 }
    }
}

Extensions

Extensions can be used to add new functionalities to any type that is visible to the current package, except functions, tuples, and interfaces.

You can add the following functionalities:

• Instance member function
• Static member function
• Operator overloading
• Instance member property
• Static member property
• Implementation interface

Extensions can add a functionality after a type is defined, but cannot damage the encapsulation of the original type. Therefore, the following functionalities are prohibited:

1. Extensions cannot add fields.
2. Extensions cannot add abstract members.
3. Extensions cannot add open members.
4. Extensions cannot use override or redef on existing members.
5. Extensions cannot access private members of the original type.

Extension Syntax

A simple extension example is as follows:

extend String {
    func printSize() {
        print(this.size)
    }
}

"123".printSize() // 3

The syntax of extension definition is as follows:

extendDefinition
    : 'extend' extendType
      ('<:' superInterfaces)? genericConstraints?
      extendBody
    ;

extendType
    : (typeParameters)? (identifier NL* DOT  NL*)* identifier (NL* typeArguments)?
    | INT8
    | INT16
    | INT32
    | INT64
    | INTNATIVE
    | UINT8
    | UINT16
    | UINT32
    | UINT64
    | UINTNATIVE
    | FLOAT16
    | FLOAT32
    | FLOAT64
    | CHAR
    | BOOLEAN
    | NOTHING
    | UNIT
    ;

extendBody
    : '{' extendMemberDeclaration* '}'
    ;

extendMemberDeclaration
    : (functionDefinition
    | operatorFunctionDefinition
    | propertyDefinition
    | macroExpression
    ) end*
    ;

The extend keyword is used to define an extension. The extension definition includes the extend keyword, optional generic parameters, the type being extended, optional implemented interfaces, optional generic constraints, and the body of the extension. {} cannot be omitted in the definition of an extension body.

Extensions can be defined only at the top level.

Extensions are classified into direct extensions and interface extensions. Direct extensions do not require the declaration of an additional interface.

Direct Extensions

Direct extensions do not require the declaration of an additional interface and can be used to directly add new functionalities to existing types.

class Foo {}

extend Foo {
    func f() {}
}

main() {
    let a = Foo()
    a.f() // call extension function
}

Interface Extensions

Interface extensions can be used to add new functionalities to existing types and implement interfaces to enhance abstraction flexibility. When using interface extension, you must declare the interface being implemented.

interface I {
    func f(): Unit
}

class Foo {}

extend Foo <: I {
    public func f() {}
}

Using interface extension functionalities to implement interface I for a type is equivalent to implementing interface I during type definition, but the scope is subject to extension import and export limitations, as detailed in [Importing and Exporting Extensions].

func g(i: I) {
    i.f()
}

main() {
    let a = Foo()
    g(a)
}

You can implement multiple interfaces within the same extension, separating them with &. The order of the interfaces does not matter.

interface I1 {
    func f1(): Unit
}

interface I2 {
    func f2(): Unit
}

interface I3 {
    func f3(): Unit
}

class Foo {}

extend Foo <: I1 & I2 & I3 {
    public func f1() {}
    public func f2() {}
    public func f3() {}
}

If the type being extended has already implemented an interface, it cannot be re-implemented through an extension, including any interfaces implemented through extensions.

interface I {
    func f(): Unit
}

class Foo <: I {
    func f(): Unit {}
}
extend Foo <: I {} // error, can not repeat the implementation of the interface

class Bar {}
extend Bar <: I {
    func f(): Unit {}
}
extend Bar <: I {} // error, already implemented through the extension can not repeat the implementation

If the type being extended has directly implemented a non-generic interface, it cannot re-implement that interface through an extension. If the type has directly implemented a generic interface, it cannot re-implement that interface with the same type parameters through an extension.

interface I1 {}

class Foo <: I1 {}

extend Foo <: I1 {} // error

interface I2<T> {}

class Goo<T> <: I2<Int32> {}

extend<T> Goo<T> <: I2<Int32> {} // error

extend<T> Goo<T> <: I2<T> {} // ok

If the type being extended already contains the functions required by the interface, the interface extension cannot re-implement these functions, nor does it use the default implementations from the interface.

class Foo {
    public func f() {}
}

interface I {
    func f(): Unit
}

extend Foo <: I {} // ok

extend Foo {
    public func g(): Unit {
        print("In extend!")
    }
}

interface I2 {
    func g(): Unit {
        print("In interface!")
    }
}

extend Foo <: I2 {} // ok, default implementation of g in I2 is no longer used

Orphan extensions are prohibited. An orphan extension is an interface extension that is defined neither in the same package as the interface (including all interfaces in the interface inheritance chain) nor in the same package as the type being extended.

That is, interface extension allows only the following two cases:

1. The interface extension and the type definition are in the same package.
2. The interfaces implemented by the interface extension, along with all interfaces in the inheritance chain that have not been implemented by the type being extended, must all be in the same package.

In other cases, interface extension cannot be defined.

// package pkg1
public class Foo {}
public class Goo {}

// package pkg2
public interface Bar {}
extend Goo <: Bar {}

// package pkg3
import pkg1.Foo
import pkg2.Bar

extend Foo <: Bar {} // error

interface Sub <: Bar {}

extend Foo <: Sub {} // error

extend Goo <: Sub {} // ok, 'Goo' has implemented the interface 'Bar' on the inheritance chain in pkg2.

Members of Extensions

The members of extensions include static member functions, instance member functions, static member properties, instance member properties, and operator overloading functions.

Functions

Extensions can add functions to the type being extended. These functions can be generic and support generic constraints, overloading, default parameters, and named parameters. However, these functions cannot be abstract.

For example:

interface I {}
extend Int64 {
    func f<T>(a: T, b!: Int64 = 0) where T <: I {}
    func f(a: String, b: String) {}
}

Modifiers

Function definitions within an extension support the use of private, internal, protected, or public modifiers.

Functions modified by private can be used within the extension and are not visible externally.

Member functions modified by protected can be accessed in this module (restricted by export rules). When the type being extended is class, the functions can also be accessed within the subclass of that class.

The accessibility modifier of a function within an extension is internal by default.

// file1 in package p1
package p1

public open class Foo {}

extend Foo {
    private func f1() {}   // ok
    public func f2() {}    // ok
    protected func f3() {} // ok
    func f4() {}           // visible in the package
}

main() {
    let a = Foo()
    a.f1() // error, can not access private function
    a.f2() // ok
    a.f3() // ok
    a.f4() // ok
}

// file2 in package p2
package p2

import p1.*

class Bar <: Foo {
    func f() {
        f1() // error, can not access private function
        f2() // ok
        f3() // ok
        f4() // error, can not access default function
    }
}

Functions in an extension can be modified using static.

class Foo {}

extend Foo {
    static func f() {}
}

Extensions of the struct type can define the mut function.

struct Foo {
    var i = 0
}

extend Foo {
    mut func f() { // ok
        i += 1
    }
}

The function definition in the extension cannot be modified by open, override, or redef.

class Foo {
    public open func f() {}
    static func h() {}
}

extend Foo {
    public override func f() {} // error
    public open func g() {} // error
    redef static func h() {} // error
}

Properties

Extensions can add properties to the type being extended. These properties cannot be abstract.

For example:

extend Int64 {
    mut prop i: Int64 {
        get() {
            0
        }
        set(value) {}
    }
}

Modifiers

Property definitions within an extension support the use of private, internal, protected, or public modifiers.

Properties modified by private can be used within the extension and are not visible externally.

Properties modified by protected can be accessed in this module (restricted by export rules). When the type being extended is class, the functions can also be accessed within the subclass of that class.

The accessibility modifier of a property within an extension is internal by default.

// file1 in package p1
package p1

public open class Foo {}

extend Foo {
    private prop v1: Int64 {   // ok
        get() { 0 }
    }
    public prop v2: Int64 {    // ok
        get() { 0 }
    }
    protected prop v3: Int64 { // ok
        get() { 0 }
    }
    prop v4: Int64 {           // visible in the package
        get() { 0 }
    }
}

main() {
    let a = Foo()
    a.v1 // error, can not access private property
    a.v2 // ok
    a.v3 // ok
    a.v4 // ok
}

// file2 in package p2
package p2

import p1.*

class Bar <: Foo {
    func f() {
        v1 // error, can not access private function
        v2 // ok
        v3 // ok
        v4 // error, can not access default function
    }
}

Properties in an extension can be modified using static.

class Foo {}

extend Foo {
    static prop i: Int64 {
        get() { 0 }
    }
}

The property definition in the extension cannot be modified by open, override, or redef.

class Foo {
    open prop v1: Int64 {
        get() { 0 }
    }
    static prop v2: Int64 {
        get() { 0 }
    }
}

extend Foo {
    override prop v1: Int64 { // error
        get() { 0 }
    }
    open prop v3: Int64 { // error
        get() { 0 }
    }
    redef static prop v2: Int64 { // error
        get() { 0 }
    }
}

Generic extensions

When the type being extended is a generic type, there are two syntaxes available for extending its functionalities.

One is the non-generic extension described above. For generic types, a non-generic extension can be applied to specific instantiated generic types.

Any fully instantiated generic type is allowed after extend. The functionalities added for these types can be used only when the types are fully matched.

extend Array<String> {} // ok
extend Array<Int> {} // ok

In the extension, the type parameters of the generic type must comply with the constraints defined for the generic type. Otherwise, a compilation error is reported.

class Foo<T> where T <: ToString {}

extend Foo<Int64> {} // ok

class Bar {}
extend Foo<Bar> {} // error

The other is to introduce a generic extension of a generic parameter after extend. Generic extensions can be used to extend generic types that are not instantiated or partially instantiated.

Generic parameters can be declared after extend, and they must be directly or indirectly used in the extended generic type. The functionalities added for these types can be used only when the types and constraints are fully matched.

extend<T> Array<T> {} // ok

The generic variant introduced by the generic extension must be used in the type being extended. Otherwise, an error is reported, indicating that the generic variant is not used.

extend<T> Array<T> {} // ok
extend<T> Array<Option<T>> {} // ok
extend<T> Array<Int64> {} // error
extend<T> Int64 <: Equatable<T> { // error
    ...
}

Regardless of generic extensions or non-generic extensions, extensions for generic types cannot redefine members or re-implement interfaces.

When a generic variant of a generic extension is directly used in the type parameter of the type being extended, the corresponding generic variant implicitly introduces the generic constraint defined by the type being extended.

class Foo<T> where T <: ToString {}

extend<T> Foo<T> {} // T <: ToString

Generic parameters introduced by generic extension cannot be used for type being extended or interface being implemented. Otherwise, a compilation error is reported.

extend<T> T {} // error
extend<T> Unit <: T {} // error

Additional generic constraints can be used in the generic extension. Members or interfaces added in this way can be used only when instances of this type meet the generic constraints of the extension. Otherwise, an error is reported.

class Foo<T> {
    var item: T
    init(it: T) {
        item = it
    }
}

interface Eq<T> {
    func equals(other: T): Bool
}

extend<T> Foo<T> <: Eq<Foo<T>> where T <: Eq<T> {
    public func equals(other: Foo<T>) {
        item.equals(other.item)
    }
}

class A {}
class B <: Eq<B> {
    public func equals(other: B) { true }
}

main() {
    let a = Foo(A())
    a.equals(a) // error, A has not implement Eq
    let b = Foo(B())
    b.equals(b) // ok, B has implement Eq
}

A generic type cannot re-implement the same interface. For the same generic type, whether fully instantiated or not, re-implementing the same interface is not allowed. Otherwise, a compilation error is reported.

interface I {}
extend Array<String> <: I {} // error, can not repeatedly implement the same interface
extend<T> Array<T> <: I {} // error, can not repeatedly implement the same interface

interface Bar<T> {}
extend Array<String> <: Bar<String> {} // error, can not repeatedly implement the same interface
extend<T> Array<T> <: Bar<T> {} // error, can not repeatedly implement the same interface

For the same generic type, whether fully instantiated or not, defining members with the same type or signature is not allowed. Otherwise, a compilation error is reported.

// case 1
extend Array<String> {
    func f() {} // error, cannot be repeatedly defined
}
extend<T> Array<T> {
    func f() {} // error, cannot be repeatedly defined
}
// case 2
extend Array<String> {
    func g(a: String) {} // error, cannot be repeatedly defined
}
extend<T> Array<T> {
    func g(a: T) {} // error, cannot be repeatedly defined
}
// case 3
extend<T> Array<T> where T <: Int {
    func g(a: T) {} // error, cannot be repeatedly defined
}
extend<V> Array<V> where V <: String {
    func g(a: V) {} // error, cannot be repeatedly defined
}
// case 4
extend Array<Int>  {
    func g(a: Int) {} // ok
}
extend Array<String>  {
    func g(a: String) {} //ok
}

Access and Hiding in Extensions

Instance members of an extension can use this, whose meaning remains consistent with that in the type definition. You can also omit this when accessing members.

However, instance members of an extension cannot use super.

class A {
    var v = 0
}

extend A {
    func f() {
        print(this.v) // ok
        print(v) // ok
    }
}

The extension cannot access the private member of the type being extended. The members modified by other modifiers comply with the visibility principle.

class A {
    private var v1 = 0
    protected var v2 = 0
}

extend A {
    func f() {
        print(v1) // error
        print(v2) // ok
    }
}

Extensions cannot hide any members of the type being extended.

class A {
    func f() {}
}

extend A {
    func f() {} // error
}

Extensions also cannot hide any members of the type being extended added by other extensions.