Cangjie Programming Language Documentation

Cangjie programming language is a general programming language for full-scene application development, balancing development efficiency and runtime performance, and providing a good programming experience.

Introduction to Cangjie Language

Cangjie is a general-purpose programming language designed for full-scenario application development, balancing development efficiency with runtime performance while providing an excellent programming experience. Its key features include:

• Multi-Backend Support: Cangjie supports two backends: CJNative and CJVM. The CJNative backend compiles code into native binaries that run directly at the operating system level, while the CJVM backend compiles code into bytecode that runs on a VM (Virtual Machine). This documentation is adapted for the CJNative backend.
• Concise and Efficient Syntax: Cangjie offers a series of concise and efficient syntax features aimed at reducing redundant coding and improving development efficiency. Examples include interpolated strings, primary constructors, Flow expressions, match statements, and re-exports, allowing developers to express logic with minimal code.
• Multi-Paradigm Programming: Cangjie supports functional, imperative, and object-oriented programming paradigms. It incorporates advanced functional language features such as higher-order functions, algebraic data types, pattern matching, and generics, alongside object-oriented language features like encapsulation, interfaces, inheritance, and subtype polymorphism for modular development. It also includes imperative language features such as value types and global functions for simplicity and efficiency. Developers can choose the paradigm that best suits their preferences or application scenarios.
• Type Safety: Cangjie is a statically and strongly typed language, enabling early detection of program errors through compile-time type checking, reducing runtime risks, and facilitating code maintenance. Additionally, the Cangjie compiler provides robust type inference capabilities, minimizing the need for type annotations and enhancing development efficiency.
• Memory Safety: Cangjie supports automatic memory management and performs runtime checks for array bounds, overflow, and other operations to ensure memory safety during execution.
• Efficient Concurrency: Cangjie provides lightweight user-mode threads (native coroutines) and an easy-to-use concurrency programming mechanism, ensuring efficient development and execution in concurrent scenarios.
• Language Ecosystem Compatibility: Cangjie supports interoperability with languages like C and adopts a convenient declarative programming paradigm, enabling efficient reuse and compatibility with libraries from other languages.
• Easy Domain-Specific Extensibility: Cangjie offers metaprogramming capabilities based on lexical macros, allowing code transformation at compile time. It also includes features such as trailing lambda, attributes, operator overloading, and optional keywords, enabling developers to deeply customize syntax and semantics. This facilitates the construction of Embedded Domain-Specific Languages (EDSLs).
• Enhanced UI Development: UI development is a critical aspect of building end-side applications. Leveraging Cangjie’s metaprogramming and trailing lambda features, users can create declarative UI development frameworks to improve efficiency and experience in UI development.
• Rich Built-in Libraries: Cangjie provides a comprehensive set of built-in libraries covering data structures, common algorithms, mathematical computations, regular expressions, system interactions, file operations, network communication, database access, logging, compression/decompression, encoding/decoding, encryption/decryption, and serialization.

Installing the Cangjie Toolchain

When developing Cangjie programs, one essential tool is the Cangjie compiler, which can compile Cangjie source code into executable binary files. However, modern programming languages come with more than just compilers. In fact, Cangjie provides developers with a comprehensive suite of development tools, including compilers, debuggers, project managers, static analysis tools, formatting tools, and coverage statistics tools, all designed for a seamless “out-of-the-box” experience.

Currently, the Cangjie toolchain has been adapted for certain versions of Linux, macOS, and Windows platforms. However, full functional testing has only been conducted on select Linux distributions. For details, please refer to the appendix section Support and Installation of Linux Version Toolchain. On platforms that have not undergone full functional testing, the completeness of the Cangjie toolchain’s functionality is not guaranteed. Additionally, the current Windows version of the Cangjie compiler is implemented based on MinGW and may lack some features compared to the Linux version.

Linux / macOS

Environment Preparation

Linux

The system requirements for the Linux version of the Cangjie toolchain are as follows:

For Ubuntu 18.04, additional dependency packages must be installed:

$ apt-get install binutils libc-dev libc++-dev libgcc-7-dev

For dependency installation commands for other Linux distributions, please refer to the appendix section Support and Installation of Linux Version Toolchain.

Additionally, the Cangjie toolchain depends on the OpenSSL 3 component, which may not be available in the default repositories of the above distributions. Therefore, it must be manually installed. For installation instructions, please refer to the appendix section Support and Installation of Linux Version Toolchain.

macOS

The macOS version of the Cangjie toolchain supports macOS 12.0 and later.

Before using the macOS version, the following dependency package must be installed by executing the following command:

$ brew install libffi

Installation Guide

First, visit the official Cangjie release channel to download the installation package for your platform’s architecture:

• cangjie-sdk-linux-x64-x.y.z.tar.gz: For x86_64 architecture Linux systems
• cangjie-sdk-linux-aarch64-x.y.z.tar.gz: For aarch64 architecture Linux systems
• cangjie-sdk-mac-x64-x.y.z.tar.gz: For x86_64 architecture macOS systems
• cangjie-sdk-mac-aarch64-x.y.z.tar.gz: For aarch64/arm64 architecture macOS systems

Assuming you have selected cangjie-sdk-linux-x64-x.y.z.tar.gz, after downloading it locally, execute the following command to extract it:

tar xvf cangjie-sdk-linux-x64-x.y.z.tar.gz

After extraction, you will see a directory named cangjie in the current working path, which contains all components of the Cangjie toolchain. Execute the following command to complete the installation and configuration:

source cangjie/envsetup.sh

To verify the installation, execute the following command:

cjc -v

Here, cjc is the executable filename of the Cangjie compiler. If the command line displays the Cangjie compiler version information, the toolchain has been successfully installed. Note that the envsetup.sh script only configures the toolchain-related environment variables for the current shell session. To use the toolchain in a new shell session, you must re-execute the envsetup.sh script.

To make the Cangjie toolchain environment variables automatically effective upon shell startup, add the following command to the end of your shell initialization file (e.g., $HOME/.bashrc or $HOME/.zshrc, depending on your shell type):

# Assuming the Cangjie package is extracted to /home/user/cangjie
source /home/user/cangjie/envsetup.sh  # The absolute path to envsetup.sh

After configuration, the Cangjie compilation toolchain will be directly available upon shell startup.

Uninstallation and Update

On Linux and macOS platforms, to uninstall the Cangjie toolchain, simply delete the installation directory and remove the environment variables (the simplest way is to open a new shell session):

$ rm -rf <path>/<to>/cangjie

To update the Cangjie toolchain, first uninstall the current version, then follow the above instructions to reinstall the latest version.

Windows

This section uses Windows 10 as an example to introduce the installation method for the Cangjie toolchain.

Installation Guide

On Windows, Cangjie provides two formats of installation packages: exe and zip. Visit the official Cangjie release channel to download the appropriate Windows version for your platform’s architecture.

• If you choose the exe format installation package (e.g., cangjie-sdk-windows-x64-x.y.z.exe), simply execute the file and follow the installation wizard to complete the installation.

• If you choose the zip format installation package (e.g., cangjie-sdk-windows-x64-x.y.z.zip), extract it to an appropriate directory. The package provides three different installation scripts: envsetup.bat, envsetup.ps1, and envsetup.sh. Choose one based on your usage habits and environment configuration:

  • For Windows Command Prompt (CMD), execute:

    path\to\cangjie\envsetup.bat
    

  • For PowerShell, execute:

    . path\to\cangjie\envsetup.ps1
    

  • For MSYS shell, bash, etc., execute:

    source path/to/cangjie/envsetup.sh
    

To verify the installation, execute cjc -v in the same command environment. If the Cangjie compiler version information is displayed, the toolchain has been successfully installed.

Important Note: Similar to Linux, the environment variables configured by the envsetup script are only effective for the current command-line session. To make the Cangjie toolchain automatically available upon command prompt or terminal startup, configure the system as follows:

• For bash environments, follow these steps:

  Add the following command to the end of your $HOME/.bashrc initialization file ($HOME is the path to the current user’s directory):

  # Assuming the Cangjie package is extracted to /home/user/cangjie
  source /home/user/cangjie/envsetup.sh  # The absolute path to envsetup.sh
  

  After configuration, the Cangjie compilation toolchain will be directly available upon bash startup.

• For Windows Command Prompt (CMD), PowerShell, or other environments, follow these steps:

  1. Search for “View advanced system settings” in the Windows search box and open the corresponding window.

  2. Click the “Environment Variables” button.

  3. Configure the CANGJIE_HOME variable as follows:

     1. In the “User variables” (for the current user) or “System variables” (for all users) section, check if the CANGJIE_HOME environment variable already exists. If not, click “New” and enter CANGJIE_HOME in the “Variable name” field. If it exists, the environment may already be configured for Cangjie. To overwrite the existing configuration, click “Edit” to enter the “Edit System Variable” window.

     2. In the “Variable value” field, enter the extraction path of the Cangjie installation package. If a path already exists, overwrite it with the new path. For example, if the package is extracted to D:\cangjie, enter D:\cangjie.

     3. After configuration, the “Edit User Variable” or “Edit System Variable” window should display CANGJIE_HOME as the variable name and D:\cangjie as the variable value. Click “OK” after confirming the path.

  4. Configure the Path variable as follows:

     1. In the “User variables” or “System variables” section, locate and select the Path variable, then click “Edit” to open the “Edit Environment Variable” window.

     2. Click “New” and enter the following paths one by one: %CANGJIE_HOME%\bin, %CANGJIE_HOME%\tools\bin, %CANGJIE_HOME%\tools\lib, %CANGJIE_HOME%\runtime\lib\windows_x86_64_cjnative (%CANGJIE_HOME% is the extraction path of the Cangjie package). For example, if the package is extracted to D:\cangjie, the new environment variables should be: D:\cangjie\bin, D:\cangjie\tools\bin, D:\cangjie\tools\lib, D:\cangjie\runtime\lib\windows_x86_64_cjnative.

     3. (For current user settings only) Click “New” and enter the current user directory path, appending .cjpm\bin to it. For example, if the user path is C:\Users\bob, enter C:\Users\bob\.cjpm\bin.

     4. After configuration, the “Edit Environment Variable” window should display the paths as follows. Click “OK” after confirming the paths:

        D:\cangjie\bin
        D:\cangjie\tools\bin
        D:\cangjie\tools\lib
        D:\cangjie\runtime\lib\windows_x86_64_cjnative
        C:\Users\bob\.cjpm\bin
        

  5. Click “OK” to exit the “Environment Variables” window.

  6. Click “OK” to complete the setup.

  Note: After configuration, you may need to restart the command-line window or the system for the changes to take effect.

  After configuration, the Cangjie compilation toolchain will be directly available upon Windows Command Prompt (CMD) or PowerShell startup.

Uninstallation and Update

• If you installed using the exe format package, run the unins000.exe executable in the Cangjie installation directory and follow the uninstallation wizard to complete the process.

• If you installed using the zip format package, delete the Cangjie toolchain installation directory and remove the above environment variable settings (if any) to complete the uninstallation.

To update the Cangjie toolchain, first uninstall the current version, then follow the above instructions to reinstall the latest version.

Running Your First Cangjie Program

Everything is ready—let’s start writing and running your first Cangjie program!

Compiling with cjc

First, create a new text file named hello.cj in an appropriate directory and write the following Cangjie code into it:

// hello.cj
main() {
    println("Hello, Cangjie")
}

In this code snippet, we use Cangjie’s comment syntax. Single-line comments can be written after the // symbol, while multi-line comments can be written between /* and */ symbols, which is identical to the comment syntax in languages like C/C++. Comment content does not affect program compilation and execution.

Next, execute the following command in this directory:

cjc hello.cj -o hello

Here, the Cangjie compiler will compile the source code in hello.cj into an executable file named hello for the current platform. When you run this file in a command-line environment, you’ll see the program output the following content:

Hello, Cangjie

Note:

The above compilation command is for Linux and macOS platforms. If you’re using Windows, simply modify the compilation command to cjc hello.cj -o hello.exe.

Compiling and Running with cjpm

In addition to using the cjc compiler directly, you can also use the Cangjie Project Manager (cjpm) to quickly create, manage, and run Cangjie projects.

Please follow the steps below to create your first Cangjie project:

1. create a new directory named hello_cjpm to store the project files, and then enter the directory.

2. use the cjpm init command to initialize a new Cangjie module.

cjpm init

After a successful execution, the command line will show cjpm init success. At this point, cjpm generates the default project structure in the current directory:

hello_cjpm
├── cjpm.toml // The configuration file for the project
└── src
    └── main.cj // The default source code file

The content of the default source file main.cj is as follows:

// main.cj
package hello_cjpm  // Declares that the current source file belongs to the hello_cjpm package

main(): Int64 {
    println("hello world")
    return 0
}

Alternatively, you can run cjpm init --path hello_cjpm. cjpm will automatically create the hello_cjpm directory and initialize the project inside it.

In the project root directory (where cjpm.toml is located), run the following command to compile and run the program:

cjpm run

cjpm will automatically handle dependency checks, compilation, and the execution of the program. The following output will be shown on the command line:

hello world

cjpm run finished

Identifiers

In the Cangjie programming language, developers can assign names to certain program elements, which are referred to as “identifiers.”

Before learning about identifiers, it is necessary to understand some concepts related to the Unicode character set. In the Unicode standard, the XID_Start and XID_Continue properties are used to mark characters that can serve as the starting and subsequent characters of a Unicode identifier, respectively. For detailed definitions, please refer to the Unicode Standard Documentation. Among them, XID_Start includes characters such as Chinese and English, while XID_Continue includes Chinese, English, Arabic numerals, and more. The Cangjie language uses Unicode Standard 15.0.0.

Identifiers in the Cangjie programming language are divided into two categories: regular identifiers and raw identifiers, each following different naming rules.

Regular identifiers cannot be the same as Cangjie keywords and are derived from the following two types of character sequences:

• A sequence starting with an XID_Start character, followed by any number of XID_Continue characters.
• A sequence starting with an _, followed by at least one XID_Continue character.

Cangjie recognizes all identifiers in their Normalization Form C (NFC) form. Two identifiers are considered the same if they are equal after NFC normalization.

For example, each of the following strings is a valid regular identifier:

abc
_abc
abc_
a1b2c3
a_b_c
a1_b2_c3
Cangjie
__こんにちは

Each of the following strings is an invalid regular identifier:

ab&c  // & is not an XID_Continue character
3abc  // Arabic numerals are not XID_Start characters, so they cannot be used as starting characters
_     // An underscore must be followed by at least one XID_Continue character
while // "while" is a Cangjie keyword and cannot be used as a regular identifier

Raw identifiers are regular identifiers or Cangjie keywords enclosed in a pair of backticks. They are primarily used in scenarios where Cangjie keywords need to be used as identifiers.

For example, each of the following strings is a valid raw identifier:

`abc`
`_abc`
`a1b2c3`
`if`
`while`
`à֮̅̕b`

Each of the following strings is an invalid raw identifier because the content inside the backticks is an invalid regular identifier:

`ab&c`
`3abc`

Program Structure

Typically, developers write Cangjie programs in text files with the .cj extension, which are also referred to as source code and source files. In the final stage of program development, this source code will be compiled into binary files of a specific format.

At the top-level scope of a Cangjie program, a series of variables, functions, and custom types (such as struct, class, enum, and interface) can be defined. Among these, variables and functions are called global variables and global functions, respectively. To compile a Cangjie program into an executable file, a main function must be defined at the top-level scope as the program entry point. This function can either take a parameter of type Array<String> or no parameters at all, and its return type can be an integer type or the Unit type.

Note:

When defining the main function, the func modifier is not required. Additionally, if command-line arguments are needed during program startup, a parameter of type Array<String> can be declared and used.

For example, in the following program, the top-level scope defines the global variable a, the global function b, the custom types C, D, and E, as well as the main function serving as the program entry point.

// example.cj
let a = 2023
func b() {}
struct C {}
class D {}
enum E { F | G }

main() {
    println(a)
}

In non-top-level scopes, the aforementioned custom types cannot be defined, but variables and functions can be defined, referred to as local variables and local functions. Specifically, variables and functions defined within custom types are called member variables and member functions.

Note:

enum and interface only support defining member functions and do not allow member variables.

For example, in the following program, the top-level scope defines the global function a and the custom type A. Within the function a, the local variable b and local function c are defined, while within the custom type A, the member variable b and member function c are defined.

// example.cj
func a() {
    let b = 2023
    func c() {
        println(b)
    }
    c()
}

class A {
    let b = 2024
    public func c() {
        println(b)
    }
}

main() {
    a()
    A().c()
}

Running the above program will output:

2023
2024

Variables

In the Cangjie programming language, a variable consists of a corresponding variable name, data (value), and several attributes. Developers access the data associated with a variable through its name, but such access operations must comply with the constraints of the relevant attributes (such as data type, mutability, and visibility).

The specific form of variable definition is:

modifier variable_name: variable_type = initial_value

Here, modifiers are used to set various attributes of the variable and can be one or more. Commonly used modifiers include:

• Mutability modifiers: let and var, corresponding to immutable and mutable attributes, respectively. Mutability determines whether a variable’s value can be changed after initialization, thus dividing Cangjie variables into immutable and mutable types.
• const modifier: const is a special variable modifier used to declare constants. It requires initialization at declaration and prohibits any changes to its value afterward. This is similar to the let modifier in terms of immutability but imposes stricter usage restrictions.
• Visibility modifiers: private and public, among others, which affect the reference scope of global variables and member variables. For details, refer to the relevant sections in subsequent chapters.
• Static modifiers: static, which affect the storage and referencing of member variables. For details, refer to the relevant sections in subsequent chapters.

All variables support the assignment operator (=), regardless of type. Variables modified by let can only be assigned once (i.e., initialized), while those modified by var can be assigned multiple times.

When defining a Cangjie variable, a mutability modifier is mandatory. Additional modifiers can be added as needed.

• Variable name must be a valid Cangjie identifier.
• Variable type specifies the type of data held by the variable. When the initial value has a clear type, the variable type annotation can be omitted, allowing the compiler to infer the type automatically.
• Initial value is a Cangjie expression used to initialize the variable. If the variable type is annotated, the initial value type must match the variable type. Global variables or static member variables must be initialized at definition. Local variables or instance member variables can omit the initial value but must have a type annotation. They must be initialized before being referenced; otherwise, a compilation error will occur.

For example, the following program defines three Int64 variables (the immutable variable a, the mutable variable b, and the const variable c). It then modifies the value of b, assigns b’s value to a, and prints the values of a, b, and c using the println function.

main() {
    let a: Int64
    var b: Int64 = 14
    const c: Int64 = 13
    b = 12
    a = b // A variable modified by let can only be assigned once, that is, initialized
    println("${a}, ${b}, ${c}")
}

Compiling and running this program will output:

12, 12, 13

Attempting to modify an immutable variable will result in a compilation error, for example:

main() {
    let pi: Float64 = 3.14159
    pi = 2.71828 // Error, cannot assign to immutable value
}

When the initial value has a clear type, the variable type annotation can be omitted, for example:

main() {
    let a: Int64 = 2023
    let b = a
    println("a - b = ${a - b}")
}

Here, the type of variable b can be automatically inferred as Int64 from its initial value a, so this program can be compiled and run normally, outputting:

a - b = 0

When defining local variables, initialization can be omitted, but the variable must be assigned a value before being referenced, for example:

main() {
    let text: String
    text = "仓颉造字"
    println(text)
}

Compiling and running this program will output:

仓颉造字

Global variables and static member variables must be initialized at definition; otherwise, a compilation error will occur, for example:

let global: Int64 // Error, variable in top-level scope must be initialized

main(): Unit{

}

class Player {
    static let score: Int32 // Error, static variable 'score' needs to be initialized when declaring
}

Note that when the compiler cannot determine whether certain scenarios will definitely initialize a variable or whether an immutable variable is being reinitialized, it will conservatively report a compilation error, as shown in the following example:

func calc(a: Int32){
    println(a)
    return a * a
}
main() {
    let a: String
    if(calc(32) == 0){
      a = "1"
    }
    a = "2" // Error, cannot assign to immutable value
}

Additionally, for try-catch scenarios, the compiler assumes that the try block is always fully executed and always throws an exception, leading to related errors, as shown in the following example:

main() {
    let a: String
    try {
        a = "1"
    } catch (_) {
        a = "2" // Error, cannot assign to immutable value
    }
}

const Variables

const variables are a special type of variable modified by the keyword const. They are evaluated at compile time and cannot be changed during runtime. For example, the following defines the gravitational constant G:

const G = 6.674e-11

const variables can omit type annotations but cannot omit initialization expressions. They can be global variables, local variables, or static member variables. However, const variables cannot be defined in extensions. They can access all instance members of their corresponding types and call all non-mut instance member functions.

The following example defines a struct to record a planet’s mass and radius, along with a const member function gravity to calculate the gravitational force exerted by the planet on an object of mass m at distance r:

struct Planet {
    const Planet(let mass: Float64, let radius: Float64) {}

    const func gravity(m: Float64, r: Float64) {
        G * mass * m / r**2
    }
}

main() {
    const myMass = 71.0
    const earth = Planet(5.972e24, 6.378e6)
    println(earth.gravity(myMass, earth.radius))
}

Compiling and executing this will output the gravitational force exerted by Earth on a 71 kg adult standing on its surface:

695.657257

After initialization, all members of a const variable’s type instance are const (deep const, including members of members) and thus cannot be used as lvalues.

main() {
    const myMass = 71.0
    myMass = 70.0 // Error, cannot assign to immutable value
}

Value-Type and Reference-Type Variables

From the compiler’s implementation perspective, any variable is always associated with a value (typically via a memory address/register). However, for some variables, the value itself is directly used, which are called value-type variables. For others, the value serves as an index to access the data it points to, which are called reference-type variables. Value-type variables are usually allocated on the thread stack, with each variable having its own data copy. Reference-type variables are usually allocated on the process heap, with multiple variables potentially referencing the same data object. Operations on one variable may affect others.

From the language perspective, value-type variables exclusively bind to their data/storage space, while reference-type variables share their data/storage space with other reference-type variables.

Based on these principles, there are behavioral differences between value-type and reference-type variables, with the following points worth noting:

1. Assigning to a value-type variable typically involves a copy operation, and the originally bound data/storage space is overwritten. Assigning to a reference-type variable only changes the reference relationship, leaving the originally bound data/storage space unaffected.
2. Variables defined with let cannot be reassigned after initialization. For reference types, this only restricts the reference relationship from changing; the referenced data can still be modified.

In the Cangjie programming language, class and Array types are reference types, while other basic data types and struct types are value types.

For example, the following program demonstrates the behavioral differences between struct and class type variables:

struct Copy {
    var data = 2012
}

class Share {
    var data = 2012
}

main() {
    let c1 = Copy()
    var c2 = c1
    c2.data = 2023
    println("${c1.data}, ${c2.data}")

    let s1 = Share()
    let s2 = s1
    s2.data = 2023
    println("${s1.data}, ${s2.data}")
}

Running the above program will output:

2012, 2023
2023, 2023

From this, we can observe that for value-type Copy variables, assignment always obtains a copy of the Copy instance, such as c2 = c1. Subsequent modifications to c2 members do not affect c1. For reference-type Share variables, assignment establishes a reference relationship between the variable and the instance, such as s2 = s1. Subsequent modifications to s2 members will affect s1.

If we change var c2 = c1 to let c2 = c1 in the above program, the compilation will report an error, for example:

struct Copy {
    var data = 2012
}

main() {
    let c1 = Copy()
    let c2 = c1
    c2.data = 2023 // Error, cannot assign to immutable value
}

Scope

Earlier, we briefly introduced how to name elements in Cangjie programs. In practice, besides variables, names can also be assigned to functions and custom types, and these names are used to access the corresponding program elements.

However, in practical applications, some special cases need to be considered:

• When the program scale is large, those short names are prone to duplication, leading to naming conflicts.
• Considering runtime scenarios, in some code segments, certain program elements are invalid, and referencing them will cause runtime errors. For example, some variables become invalid after their scope is exited.
• In certain logical constructs, to express containment relationships between elements, sub-elements should not be accessed directly by name but through their parent element names indirectly.

To address these issues, modern programming languages introduce the concept and design of “scope,” limiting the binding relationship between names and program elements to a specific range. Scopes can be parallel, unrelated, nested, or contain each other. A scope clearly defines which program elements can be accessed by which names, with the following specific rules:

1. The binding relationship between program elements and names defined in the current scope is valid within the current scope and its inner scopes, allowing direct access to the corresponding program elements via these names.
2. The binding relationship between program elements and names defined in an inner scope is invalid in outer scopes.
3. Inner scopes can redefine binding relationships using names from outer scopes. According to rule 1, the naming in the inner scope effectively shadows the same-name definition in the outer scope. In this case, the inner scope is said to have a higher level than the outer scope.

In the Cangjie programming language, a pair of curly braces {} enclosing a segment of Cangjie code creates a new scope. Within this scope, further curly braces {} can enclose more Cangjie code, resulting in nested scopes. These scopes all adhere to the above rules. Specifically, in a Cangjie source file, code not enclosed by any curly braces {} belongs to the “top-level scope,” the “outermost” scope in the current file, which, according to the above rules, has the lowest scope level.

Note:

Cangjie does not allow standalone curly braces {}. Curly braces must depend on other syntactic structures such as if, match, function bodies, class bodies, or struct bodies.

For example, in the following Cangjie source file named test.cj, the name element is defined in the top-level scope, bound to the string “Cangjie.” Within the main and if blocks, the name element is also defined, corresponding to the integer 9 and the integer 2023, respectively. According to the scope rules, at line 4, element has the value “Cangjie”; at line 8, element has the value 2023; and at line 10, element has the value 9.

// test.cj
let element = "Cangjie"
main() {
    println(element)
    let element = 9
    if (element > 0) {
        let element = 2023
        println(element)
    }
    println(element)
}

Running the above program will output:

Cangjie
2023
9

Expressions

In some traditional programming languages, an expression consists of one or more operands combined by zero or more operators. An expression always implies a computation process, so each expression will have a computation result. For expressions containing only operands without operators, the computation result is the operand itself. For expressions containing operators, the computation result is the value obtained by performing the operations defined by the operators on the operands. Expressions defined in this way are also called arithmetic expressions. For operator precedence, refer to the Operators chapter.

In the Cangjie programming language, the traditional definition of expressions is simplified and extended—any language element that can be evaluated is considered an expression. Therefore, Cangjie not only has traditional arithmetic expressions but also conditional expressions, loop expressions, and try expressions, all of which can be evaluated and used as values, such as initial values for variable definitions and function arguments. Additionally, because Cangjie is a strongly typed programming language, Cangjie expressions not only can be evaluated but also have a definite type.

Note:

To clearly distinguish between different program statements or expressions, Cangjie uses semicolons (;) as separators. If a statement occupies a line by itself, the semicolon can be omitted. However, if multiple statements exist on the same line, they must be separated by semicolons.

Various expressions in the Cangjie programming language will be introduced in subsequent chapters. This section covers the most commonly used conditional expressions, loop expressions, and some control transfer expressions (break, continue).

The execution flow of any program involves only three basic structures—sequential structure, branching structure, and looping structure. In fact, branching and looping structures are obtained by certain instructions causing jumps in the current sequential execution flow, enabling the program to express more complex logic. In Cangjie, the language elements used to control the execution flow are conditional expressions and loop expressions.

In the Cangjie programming language, the conditional expression is the if expression, whose value and type depend on the usage context. There are three types of loop expressions: for-in expressions, while expressions, and do-while expressions, all of which have the type Unit and the value ().

In Cangjie programs, a group of expressions enclosed by a pair of curly braces {} is called a “code block,” which serves as a sequential execution flow in the program. The expressions within the block are executed in the order they are written. If a code block contains at least one expression, the value and type of the block are defined to be equal to the value and type of its last expression. If the code block contains no expressions, such an empty block is defined to have the type Unit and the value ().

Note:

A code block itself is not an expression and cannot be used alone. It must be attached to functions, conditional expressions, loop expressions, etc., for execution and evaluation.

if Expression

The basic form of the if expression is:

if (condition) {
  branch1
} else {
  branch2
}

Here, “condition” can be a Boolean-type expression, a “let pattern” (syntactic sugar), or multiple “let patterns” and Boolean-type expressions connected directly by logical AND or OR operations. For examples involving “let patterns,” refer to Examples of “Conditions” Involving let Patterns.

When the expression and pattern match successfully, the pattern match evaluates to true, and the if branch’s corresponding code block is executed. Otherwise, it evaluates to false, and the else branch’s code block is executed. The else branch is optional.

“Branch1” and “branch2” are two code blocks. The if expression executes according to the following rules:

1. Evaluate the “condition” expression. If the value is true, proceed to step 2; if false, proceed to step 3.
2. Execute “branch1,” then proceed to step 4.
3. Execute “branch2,” then proceed to step 4.
4. Continue executing the code following the if expression.

In some scenarios, only the actions to take when the condition is true may be of interest, so the else and its corresponding code block can be omitted.

The following program demonstrates the basic usage of the if expression:

import std.random.Random

main() {
    let number: Int8 = Random().nextInt8()
    println(number)
    if (number % 2 == 0) {
        println("Even")
    } else {
        println("Odd")
    }
}

In this program, a random integer is generated using the random package from the Cangjie standard library. The if expression checks whether this integer is divisible by 2 and prints “Even” or “Odd” in the respective branches.

The Cangjie programming language is strongly typed. The condition in an if expression must be of Boolean type; integers, floating-point numbers, etc., cannot be used. Unlike C and similar languages, Cangjie does not use whether the condition evaluates to zero as the basis for branching. For example, the following program will result in a compilation error (additional incorrect expression examples are provided in Incorrect Expression Examples for comparison):

main() {
    let number = 1
    if (number) { // Compilation error: type mismatch
        println("Non-zero")
    }
}

In many scenarios, when one condition fails, another or multiple conditions may need to be checked before executing corresponding actions. Cangjie allows new if expressions to follow else, enabling multi-level conditional checks and branching. For example:

import std.random.Random

main() {
    let speed = Random().nextFloat64() * 20.0
    println("${speed} km/s")
    if (speed > 16.7) {
        println("Third cosmic velocity: Magpie Bridge Rendezvous")
    } else if (speed > 11.2) {
        println("Second cosmic velocity: Chang'e Flies to the Moon")
    } else if (speed > 7.9) {
        println("First cosmic velocity: Soaring Through Clouds")
    } else {
        println("Stay grounded, gaze at the stars")
    }
}

The value and type of an if expression depend on its usage form and context:

• When an if expression with an else branch is evaluated, its type is determined based on the evaluation context:

  • If the context explicitly requires a value of type T, the types of all branch code blocks in the if expression must be subtypes of T. The if expression’s type is then determined as T. If the subtype constraint is not satisfied, a compilation error occurs. For example, in the following code, since the type Int64 of variable b does not satisfy the subtype constraint with the types of the branch code blocks, a compilation error occurs:

    var a = 10
    var b: Int64 = if(a == 10) { // Error, mismatched types
        "this is 10"
    }else {
        "this is not 10"
    }
    

  • If the context does not have explicit type requirements, the if expression’s type is the least common supertype of all branch code block types. If no least common supertype exists, a compilation error occurs. For example, in the following code, since string and numeric types have no least common supertype, a compilation error occurs:

    var a = 10
    var b = if(a == 10) { // Error, types Struct-String and Int64 of the two branches of this 'if' expression mismatch
        "this is 10"
    }else {
        20
    }
    

  If compilation succeeds, the if expression’s value is the value of the executed branch’s code block.

• If an if expression with an else branch is not evaluated, in such scenarios, developers typically only want to perform different operations in different branches without concerning themselves with the values and types of the last expressions in each branch. To avoid the above type-checking rules affecting this mental model, Cangjie stipulates that in such scenarios, the if expression’s type is Unit, its value is (), and the branches do not participate in the above type checks.

• For if expressions without an else branch, since the if branch may not be executed, such if expressions are defined to have the type Unit and the value ().

For example, the following program uses an if expression evaluation to simulate a simple analog-to-digital conversion process:

main() {
    let zero: Int8 = 0
    let one: Int8 = 1
    let voltage = 5.0
    let bit = if (voltage < 2.5) {
        zero
    } else {
        one
    }
}

In the above program, the if expression is used as the initial value for a variable definition. Since the variable bit is not explicitly typed and its type must be inferred from the initial value, the if expression’s type is determined as the least common supertype of the two branch code block types. As explained earlier regarding “code blocks,” both branch code block types are Int8, so the if expression’s type is determined as Int8, and its value is the value of the executed branch (the else branch’s code block). Thus, the variable bit has the type Int8 and the value 1.

Examples of “Conditions” Involving let Patterns

“let patterns” are syntactic sugar. A “let pattern” has the form let pattern <- expression, where:

• pattern: A pattern used to match the value type and content of expression.
• <-: The pattern-matching operator.
• expression: An expression whose value is evaluated and then matched against the pattern. The precedence of the expression must not be lower than the .. operator, but parentheses can be used to change precedence. For operator precedence, refer to Operators.

Here are examples of “conditions” involving logical AND or OR operations between two “let patterns” or between a “let pattern” and other expressions.

main() {
    let a = Some(3)
    let c = if (let Some(b) <- a) {
            1 // Pattern match succeeds, c = 1
        } else {
            2
        }
    let d = Some(1)

    if (let Some(e) <- a && let Some(f) <- d) { // Both patterns match; condition evaluates to true
        println("${e} ${f}") // prints 3 1
    }

    if (let Some(f) <- d && f > 3) { // Pattern matches; f = 1, f > 3 check fails; jumps to else branch
        println("${f}")
    } else {
        println("d is None or value of d is less or equal to 3") // prints this line
    }

    if (let Some(_) <- a || let Some(_) <- d) { // Enum patterns connected by ||, no variable binding; correct
        println("at least one of a and d is Some") // prints this line
    } else {
        println("both a and d are None")
    }

    let g = 3
    if (let Some(_) <- a || g > 1) {
        println("this") // prints this line
    } else {
        println("that")
    }
}

In “let patterns,” the precedence of the expression part must not be lower than the .. operator. Here are corresponding incorrect and correct examples. For details on the Option type, refer to later sections.

if (let Some(a) <- fun() as Option<Int64>) {}   // Parsing error: `as` has lower precedence than `..`
if (let Some(a) <- (fun() as Option<Int64>)) {} // Correct
if (let Some(a) <- b && a + b > 3) {}           // Correct, parsed as (let Some(a) <- b) && (a + b > 3)
if (let m <- 0..generateSomeInt()) {}           // Correct

Incorrect Expression Examples

Here are examples of incorrect “conditions.”

if (let Some(a) <- b || a > 1) {} // Conditions connected by `||` cannot use enum patterns that bind variables
if (let Some(a) <- b && a + 1) {} // Right side of `&&` is neither a let pattern nor a Boolean-type expression
if (a > 3 && let Some(a) <- b) {} // a is bound by Some(a) pattern; cannot use it on the left side of the binding pattern
if (let Some(a) <- b && a > 3) {
    println("${a} > 3")
} else {
    println("${a} < 3") // a can only be used in the if branch, not the else branch
}
if (let Some(a) <- b where a > 3) {} // Use `&&` for condition checks, not `where`

while Expression

The basic form of the while expression is:

while (condition) {
  loop_body
}

Here, “condition” is the same as in the if expression, and “loop_body” is a code block. The while expression executes according to the following rules:

1. Evaluate the “condition” expression. If the value is true, proceed to step 2; if false, proceed to step 3.
2. Execute “loop_body,” then proceed to step 1.
3. End the loop and continue executing the code following the while expression.

For example, the following program uses a while expression to approximate the square root of 2 using the bisection method:

main() {
    var root = 0.0
    var min = 1.0
    var max = 2.0
    var error = 1.0
    let tolerance = 0.1 ** 10

    while (error ** 2 > tolerance) {
        root = (min + max) / 2.0
        error = root ** 2 - 2.0
        if (error > 0.0) {
            max = root
        } else {
            min = root
        }
    }
    println("Square root of 2 ≈ ${root}")
}

Running this program will output:

Square root of 2 ≈ 1.414215

do-while Expression

The basic form of the do-while expression is:

do {
  loop_body
} while (condition)

Here, “condition” is a Boolean-type expression, and “loop_body” is a code block. The do-while expression executes according to the following rules:

1. Execute “loop_body,” then proceed to step 2.
2. Evaluate the “condition” expression. If the value is true, proceed to step 1; if false, proceed to step 3.
3. End the loop and continue executing the code following the do-while expression.

For example, the following program uses a do-while expression to approximate the value of π using the Monte Carlo method:

import std.random.Random

main() {
    let random = Random()
    var totalPoints = 0
    var hitPoints = 0

    do {
        // Randomly sample points within the square ((0, 0), (1, 1))
        let x = random.nextFloat64()
        let y = random.nextFloat64()
        // Determine if the point falls within the inscribed circle
        if ((x - 0.5) ** 2 + (y - 0.5) ** 2 < 0.25) {
            hitPoints++
        }
        totalPoints++
    } while (totalPoints < 1000000)

    let pi = 4.0 * Float64(hitPoints) / Float64(totalPoints)
    println("Approximate value of pi: ${pi}")
}

Running the above program will output:

Approximate value of pi: 3.141872

Note:

Since the algorithm involves random numbers, the output may vary each time the program is run, but it will always approximate 3.14.

for-in Expression

The for-in expression can iterate over instances of types that implement the iterator interface Iterable<T>. The basic form of the for-in expression is:

for (iterationVariable in sequence) {
  loopBody
}

Here, “loopBody” is a code block. The “iterationVariable” is a single identifier or a tuple composed of multiple identifiers, used to bind the data pointed to by the iterator in each iteration. It can be used as a local variable within the “loopBody”. The “sequence” is an expression that is evaluated only once, and the iteration is performed on the value of this expression. Its type must implement the iterator interface Iterable<T>. The for-in expression executes according to the following rules:

1. Evaluate the “sequence” expression, use its value as the iteration target, and initialize the iterator of the iteration target.
2. Update the iterator. If the iterator terminates, proceed to step 4; otherwise, proceed to step 3.
3. Bind the current data pointed to by the iterator to the “iterationVariable” and execute the “loopBody”, then return to step 2.
4. Terminate the loop and continue executing the code following the for-in expression.

Note:

Built-in types such as ranges and arrays in Cangjie already implement the Iterable<T> interface.

For example, the following program uses a for-in expression to iterate over the array noumenonArray composed of Chinese earthly branch characters, outputting the Heavenly Stems and Earthly Branches for each month of the lunar year 2024:

main() {
    let metaArray = [r'甲', r'乙', r'丙', r'丁', r'戊', r'己', r'庚', r'辛', r'壬', r'癸']
    let noumenonArray = [r'寅', r'卯', r'辰', r'巳', r'午', r'未', r'申', r'酉', r'戌', r'亥', r'子', r'丑']
    let year = 2024

    // Heavenly stem index corresponding to the year
    let metaOfYear = ((year % 10) + 10 - 4) % 10
    // Heavenly stem index for the first month of this year
    var index = (2 * metaOfYear + 3) % 10 - 1

    println("Heavenly Stems and Earthly Branches for Lunar Year 2024:")
    for (noumenon in noumenonArray) {
        print("${metaArray[index]}${noumenon} ")
        index = (index + 1) % 10
    }
}

Here, characters prefixed with r represent character literals. Running the above program will output:

Heavenly Stems and Earthly Branches for Lunar Year 2024:
丙寅 丁卯 戊辰 己巳 庚午 辛未 壬申 癸酉 甲戌 乙亥 丙子 丁丑

Iterating Over Ranges

The for-in expression can iterate over range type instances, for example:

main() {
    var sum = 0
    for (i in 1..=100) {
        sum += i
    }
    println(sum)
}

Running the above program will output:

5050

For detailed information about range types, refer to the basic data type Range Type.

Iterating Over Sequences of Tuples

If the elements of a sequence are of tuple type, the “iterationVariable” in the for-in expression can be written as a tuple to destructure the sequence elements, for example:

main() {
    let array = [(1, 2), (3, 4), (5, 6)]
    for ((x, y) in array) {
        println("${x}, ${y}")
    }
}

Running the above program will output:

1, 2
3, 4
5, 6

Iteration Variables Cannot Be Modified

Within the loop body of a for-in expression, the iteration variable cannot be modified. For example, the following program will result in a compilation error:

main() {
    for (i in 0..5) {
        i = i * 10 // Error: Cannot assign to an initialized `let` constant
        println(i)
    }
}

Using Wildcard _ as Iteration Variable

In some scenarios, you only need to perform certain operations in a loop without using the iteration variable. In such cases, you can use the wildcard _ in place of the iteration variable, for example:

main() {
    var number = 2
    for (_ in 0..5) {
        number *= number
    }
    println(number)
}

Running the above program will output:

4294967296

Note:

In such scenarios, if a regular identifier is used to define the iteration variable, the compilation will output an “unused variable” warning. Using the wildcard _ avoids this warning.

where Condition

In some iteration scenarios, you may need to skip specific values of the iteration variable and proceed to the next iteration. While this can be achieved using if and continue expressions within the loop body, Cangjie provides a more concise way—you can use the where keyword followed by a Boolean expression after the “sequence”. Before executing the loop body each time, this expression will be evaluated. If the value is true, the loop body will execute; otherwise, it will proceed directly to the next iteration. For example:

main() {
    for (i in 0..8 where i % 2 == 1) { // Loop body executes only when i is odd
        println(i)
    }
}

Running the above program will output:

1
3
5
7

break and continue Expressions

In loop structures, sometimes you need to terminate the loop early or skip the current iteration based on specific conditions. To facilitate this, Cangjie introduces the break and continue expressions. They can appear within the loop body of a loop expression. break terminates the current loop expression and proceeds to execute the code following the loop expression, while continue skips the remaining part of the current iteration and proceeds to the next iteration. Both break and continue expressions are of type Nothing.

For example, the following program uses a for-in expression and a break expression to find the first number divisible by 5 in a given integer array:

main() {
    let numbers = [12, 18, 25, 36, 49, 55]
    for (number in numbers) {
        if (number % 5 == 0) {
            println(number)
            break
        }
    }
}

When the for-in iteration reaches the third number 25 in the numbers array, since 25 is divisible by 5, the if branch containing println and break will execute. The break will terminate the for-in loop, and subsequent numbers in numbers will not be traversed. Therefore, running the above program will output:

25

The following program uses a for-in expression and a continue expression to print the odd numbers in a given integer array:

main() {
    let numbers = [12, 18, 25, 36, 49, 55]
    for (number in numbers) {
        if (number % 2 == 0) {
            continue
        }
        println(number)
    }
}

During iteration, when number is even, continue will be executed, skipping the remaining part of the current iteration (including println) and proceeding to the next iteration. Therefore, running the above program will output:

25
49
55

Functions

In Cangjie, the keyword func is used to denote the start of a function definition. Following func are the function name, parameter list, optional return type, and function body. The function name can be any valid identifier. The parameter list is enclosed in parentheses (with multiple parameters separated by commas), a colon separates the parameter list and the return type (if present), and the function body is enclosed in curly braces.

Example of a function definition:

func add(a: Int64, b: Int64): Int64 {
    return a + b
}

In the above example, a function named add is defined. Its parameter list consists of two Int64 parameters, a and b, and its return type is Int64. The function body adds a and b together and returns the result.

For more details, refer to the Defining Functions module.

Basic Operators

Operators are symbols that perform specific mathematical or logical operations. For example, the mathematical operator plus (+) can add two numbers (e.g., let i = 1 + 2), and the logical operator AND (&&) can be used to combine and ensure multiple conditional judgments are satisfied (e.g., if (i > 0 && i < 10)).

The Cangjie programming language not only supports various commonly used operators but also improves some of them to reduce common coding errors. For instance, the type of an assignment expression (an expression containing an assignment operator) is Unit, and its value is (). If you write if(a = 3) instead of if(a == 3), the return value of the assignment expression is not of Boolean type, resulting in a compilation error. This helps avoid the issue of mistakenly using the assignment operator (=) instead of the equality operator (==). The results of arithmetic operators (+, -, *, /, %, etc.) are checked to prevent value overflow, thereby avoiding abnormal results when saving variables that exceed their type’s capacity.

The Cangjie programming language also provides range operators, such as a..b or a..=b, which conveniently express a range of values.

This chapter only describes the basic operators in the Cangjie programming language. For other operators, refer to the Operators section in the appendix. For information on how to overload operators for custom types, see the Operator Overloading chapter.

Assignment Operator

Used to modify the value of the left operand to the value of the right operand, requiring that the type of the right operand be a subtype of the left operand’s type. When evaluating an assignment expression, the expression on the right side of = is always evaluated first, followed by the expression on the left side of =, and finally, the assignment is performed.

main(): Int64 {
    var a = 1
    var b = 1
    a = (b = 0) // Compilation error: the type of the assignment expression is Unit, and its value is ()
    if (a = 5) { // Compilation error: the type of the assignment expression is Unit, and its value is ()
    }
    a = b = 0 // Syntax error: chained use of assignments is not supported

    return 0
}

A multiple assignment expression is a special type of assignment expression. The left side of the equals sign in a multiple assignment expression must be a tuple (Tuple), and the elements in this tuple must all be lvalues. The right side of the expression must also be of tuple type, and each element in the right tuple must be a subtype of the corresponding lvalue’s type on the left. Notably, when _ appears in the left tuple, it indicates that the evaluation result of the corresponding position in the right tuple should be ignored (meaning the type check for this position will always pass). A multiple assignment expression can assign the values of the right tuple to the corresponding lvalues in the left tuple in one go, eliminating the need for individual assignments.

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
}

Arithmetic Operators

The Cangjie programming language supports the following arithmetic operators: unary minus (-), addition (+), subtraction (-), multiplication (*), division (/), remainder (%), and exponentiation (**). Except for the unary minus, which is a unary prefix operator, all other operators are binary infix operators.

The operand of the unary minus (-) can only be a numeric-type expression. The value of a unary prefix minus expression is equal to the negative of its operand, and its type is the same as the operand’s type:

    let num1: Int64 = 8
    let num2 = -num1 // num2 = -8, its data type is "Int64".
    let num3 = -(-num1) // num3 = 8, its data type is "Int64".

For the binary operators *, /, %, +, and -, the types of the two operands must be the same. The % operator only supports integer operands; *, /, +, and - can operate on any numeric type.

Note:

• When the operands of division (/) are integers, non-integer values are rounded toward 0 to become integers.
• The value of the integer remainder operation a % b is defined as a - b * (a / b).
• The addition operator can also be used for string concatenation.

    let a = 2 + 3    // a = 5
    let b = 3 - 1    // b = 2
    let c = 3 * 4    // c = 12
    let d = 7 / 3    // d = 2
    let e = 7 / -3   // e = -2, when encountering "-", it has higher precedence.
    let f = -7 / 3   // f = -2
    let g = -7 / -3  // g = 2, when encountering "-", it has higher precedence.
    let h = 4 % 3    // h = 1
    let i = 4 % -3   // i = 1, when encountering "-", it has higher precedence.
    let j = -4 % 3   // j = -1
    let k = -4 % -3  // k = -1, when encountering "-", it has higher precedence.

    let s1 = "abc"
    var s2 = "ABC"
    let r1 = s1 + s2 // r1 = "abcABC"

** represents exponentiation (e.g., x**y calculates the base x raised to the power of y). The left operand of ** can only be of type Int64 or Float64.

Note:

When the left operand is of type Int64, the right operand can only be of type UInt64, and the expression’s type is Int64. When the left operand is of type Float64, the right operand can be of type Int64 or Float64, and the expression’s type is 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

Compound Assignment Operators

The Cangjie programming language also provides compound assignment operators: **=, *=, /=, %=, +=, -=, <<=, >>=, &=, ^=, |=, &&=, and ||=. Simple examples are as follows:

    var a: Int64 = 10
    a += 2   // a = 12
    a -= 2   // a = 10
    a **= 2  // a = 100
    a *= 2   // a = 200
    a /= 10  // a = 20
    a %= 6   // a = 2
    a <<= 2  // a = 8

When evaluating a compound assignment expression, the lvalue of the left expression is always evaluated first, then the rvalue is taken from this lvalue, and this rvalue is computed with the right expression (short-circuit rules are followed if applicable), and finally, the assignment is performed. Since a compound assignment expression is also an assignment expression, compound assignment operators are non-associative. Compound assignment expressions also require the two operands to be of the same type.

func foo(p: Point): Point {
    p.x += 10
    return p
}

open class Point {
    var x: Int64 = 0
    public init (a: Int64) {
        x = a
    }
}

main() {
    var a = Point(9)    // a.x == 9
    var b = 2

    foo(a).x += (b + b) // a.x == 23
    println(a.x)
}

The above example demonstrates the evaluation order of compound assignment expressions. First, the value of foo(a).x is evaluated, resulting in a.x being 19; then, the value of b + b is computed and added to a.x.

Relational Operators

Relational operators include six types: equality (==), inequality (!=), less than (<), less than or equal to (<=), greater than (>), and greater than or equal to (>=). Relational operators are all binary operators and require the two operands to be of the same type. The type of a relational expression is Bool, meaning its value can only be true or false.

Examples of relational expressions:

main(): Int64 {
    3 < 4        // true
    3 <= 3       // true
    3 > 4        // false
    3 >= 3       // true
    3.14 == 3.15 // false
    3.14 != 3.15 // true
    return 0
}

For tuple types, a tuple type supports equality (==) and inequality (!=) operations only if all its elements support these operations; otherwise, the tuple type does not support == and != (using them will result in a compilation error). Two instances of the same tuple type are equal if and only if all elements at the same positions (indices) are equal (meaning their lengths are equal).

    var isTrue: Bool = (1, 3) == (0, 2) // false
    isTrue = (1, "123") == (1.0, 2)      // Compilation error: the types of the two operands are inconsistent
    isTrue = (1, _) == (1.0, _)          // Compilation error: wildcards cannot be used as tuple elements for matching

Coalescing Operator

The coalescing operator is denoted by ??, which is a binary infix operator. The coalescing operator is used for destructuring Option types.

For the expression e1 ?? e2, when the value of e1 is Option<T>.Some(v), the value of e1 ?? e2 is equal to the value of v (in this case, e2 is not evaluated, satisfying “short-circuit evaluation”); when the value of e1 is Option<T>.None, the value of e1 ?? e2 is equal to the value of e2.

Examples of 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}") // 100
    print("${r2}") // 0
    return 0
}

Range Operators

There are two types of range operators: .. and ..=, used to create “left-closed right-open” and “left-closed right-closed” range instances, respectively. For more details, refer to the Range Type.

Logical Operators

The Cangjie programming language supports three logical operators: logical NOT (!), logical AND (&&), and logical OR (||).

Logical NOT (!) is a unary operator that negates the Boolean value of its operand: !false equals true, and !true equals false.

    var a: Bool = true     // a = true
    var b: Bool = !a       // b = false
    var c: Bool = !false   // c = true

Logical AND (&&) and logical OR (||) are both binary operators. For the expression expr1 && expr2, its value is true only if both expr1 and expr2 are true; for the expression expr1 || expr2, its value is false only if both expr1 and expr2 are false.

    var a: Bool = true && true    // a = true
    var b: Bool = true && false   // b = false
    var c: Bool = false && false  // c = false
    var d: Bool = false && true   // d = false

    a = true || true              // a = true
    b = true || false             // b = true
    c = false || false            // c = false
    d = false || true             // d = true

Logical AND (&&) and logical OR (||) use short-circuit evaluation: when evaluating expr1 && expr2, if expr1=false, expr2 is not evaluated, and the entire expression’s value is false; when evaluating expr1 || expr2, if expr1=true, expr2 is not evaluated, and the entire expression’s value is true.

func isEven(a: Int64): Bool {
    if((a % 2) == 0) {
         println("${a} is an even number")
         true
    } else {
        println("${a} is not an even number")
        false
    }
}


main() {
    var a: Bool = isEven(2) && isEven(20)
    var b: Bool = isEven(3) && isEven(30) // isEven(3) returns false, b is false, isEven(30) is not evaluated

    a = isEven(4) || isEven(40)  // isEven(4) returns true, a is true, isEven(40) is not evaluated
    b = isEven(5) || isEven(50)
}

Bitwise Operators

The Cangjie programming language supports one unary prefix bitwise operator: bitwise NOT (!), and five binary infix bitwise operators: left shift (<<), right shift (>>), bitwise AND (&), bitwise XOR (^), and bitwise OR (|). The operands of bitwise operators can only be integer types. Bitwise operations are performed by treating operands as binary sequences and applying logical operations (0 as false, 1 as true) or shift operations on each bit.

For shift operators, the operands must be integer types (but the two operands can be different integer types, e.g., the left operand is Int8, and the right operand is Int16). Additionally, the right operand cannot be negative for both left and right shifts (such errors detected at compile time will result in compilation errors; if they occur at runtime, an exception is thrown). For unsigned numbers, the shift and padding rules are: left shifts pad the low bits with 0 and discard the high bits, while right shifts pad the high bits with 0 and discard the low bits. For signed numbers, the shift and padding rules are:

1. Positive numbers follow the same padding rules as unsigned numbers;
2. Negative numbers pad the low bits with 0 for left shifts and discard the high bits;
3. Negative numbers pad the high bits with 1 for right shifts and discard the low bits.

Moreover, if the number of bits to shift (right operand) is equal to or exceeds the operand’s width, it is considered a shift overflow. If detected at compile time, it results in an error; otherwise, a runtime exception is thrown.

    var a = !10                 // -11, conforms to shift and padding rules
    a = !20                     // -21, conforms to shift and padding rules
    a = 10 << 1                 // 20, conforms to shift and padding rules
    // a = 1000 << -1           // Compilation error: shift operation overflow (right operand cannot be negative)
    // a = 1000 << 100000000000 // Compilation error: shift operation overflow (shift out of bounds)
    a = 10 << 1 << 1            // 40, conforms to shift and padding rules
    a = 10 >> 1                 // 5, conforms to shift and padding rules
    a = 10 & 15                 // 10
    a = 10 ^ 15                 // 5
    a = 10 | 15                 // 15
    a = (1 ^ (8 & 15)) | 24     // 25

Increment and Decrement Operators

The increment (++) and decrement (--) operators perform operations to increase or decrease a value by 1 and can only be used as postfix operators. The increment (++) and decrement (--) operators are non-associative.

For the expression expr++ (or expr--), the following rules apply:

1. The type of expr must be an integer type;
2. Since expr++ (or expr--) is syntactic sugar for expr += 1 (or expr -= 1), expr must also be assignable;
3. The type of expr++ (or expr--) is Unit.

Examples of increment and decrement expressions:

    var i: Int32 = 5
    i++              // i = 6
    i--              // i = 5
    i--++            // Syntax error
    var j = 0
    j = i--          // Semantic error

Integer Types

Integer types are divided into signed integer types and unsigned integer types.

Signed integer types include Int8, Int16, Int32, Int64, and IntNative, which are used to represent signed integer values with encoding lengths of 8-bit, 16-bit, 32-bit, 64-bit, and platform-dependent sizes, respectively.

Unsigned integer types include UInt8, UInt16, UInt32, UInt64, and UIntNative, which are used to represent unsigned integer values with encoding lengths of 8-bit, 16-bit, 32-bit, 64-bit, and platform-dependent sizes, respectively.

For a signed integer type with an encoding length of N, its representable range is: $-2^{N-1} \sim 2^{N-1}-1$; for an unsigned integer type with an encoding length of N, its representable range is: $0 \sim 2^{N}-1$. The following table lists the representable ranges of all integer types:

The choice of which integer type to use in a program depends on the nature and range of the integers to be processed. When Int64 is suitable, it is preferred because its representable range is sufficiently large, and integer literals default to Int64 type in the absence of type context, avoiding unnecessary type conversions. Additionally, the Cangjie programming language provides IntNative and UIntNative as signed and unsigned integer types, respectively, with bit widths consistent with the current system. This means their sizes depend on the platform they run on, allowing them to automatically adapt to the system’s bit width in cross-platform development.

Integer Literals

Integer literals can be represented in 4 radix forms: binary (with 0b or 0B prefix), octal (with 0o or 0O prefix), decimal (no prefix), and hexadecimal (with 0x or 0X prefix). For example, the decimal number 24 can be represented as 0b00011000 (or 0B00011000) in binary, 0o30 (or 0O30) in octal, and 0x18 (or 0X18) in hexadecimal.

In any radix representation, underscores _ can be used as separators to improve readability, such as 0b0001_1000.

If the value of an integer literal exceeds the representable range of the required integer type in the context, the compiler will report an error.

let x: Int8 = 128          // Error, 128 out of the range of Int8
let y: UInt8 = 256         // Error, 256 out of the range of UInt8
let z: Int32 = 0x8000_0000 // Error, 0x8000_0000 out of the range of Int32

When using integer literals, suffixes can be added to explicitly specify the type of the literal. The correspondence between suffixes and types is as follows:

Integer literals with suffixes can be used in the following ways:

var x = 100i8  // x is 100 with type Int8
var y = 0x10u64 // y is 16 with type UInt64
var z = 0o432i32  // z is 282 with type Int32

Character Byte Literals

The Cangjie programming language supports character byte literals to facilitate the representation of UInt8 values using ASCII codes. A character byte literal consists of the character b, a pair of single quotes, and an ASCII character, for example:

var a = b'x'                    // a is 120 with type UInt8
var b = b'\n'                   // b is 10 with type UInt8
var c = b'\u{78}'               // c is 120 with type UInt8
c = b'\u{90}' - b'\u{66}' + c   // c is 162 with type UInt8

b'x' represents a literal value of type UInt8 with a value of 120. Additionally, the escape form b'\u{78}' can be used to represent a literal value of type UInt8 with a hexadecimal value of 0x78 or a decimal value of 120. Note that the \u escape sequence can contain at most two hexadecimal digits, and the value must be less than 256 (in decimal).

Operations Supported by Integer Types

Integer types natively support the following operators: arithmetic operators, bitwise operators, relational operators, increment and decrement operators, and compound assignment operators. The precedence of these operators can be found in the Operators section of the appendix.

Conversions are allowed between integer types, as well as between integer and floating-point types. Integer types can also be converted to character types. For specific syntax and rules on type conversions, refer to Numeric Type Conversions.

Note:

The operations mentioned in this chapter refer to those supported natively, without operator overloading.

Floating-Point Types

Floating-point types include Float16, Float32, and Float64, which are used to represent floating-point numbers (numbers with fractional parts, such as 3.14159, 8.24, and 0.1) with encoding lengths of 16-bit, 32-bit, and 64-bit, respectively. Float16, Float32, and Float64 correspond to the half-precision format (binary16), single-precision format (binary32), and double-precision format (binary64) in IEEE 754.

The precision (number of significant digits) of Float64 is approximately 15 digits, Float32 has a precision of about 6 digits, and Float16 has a precision of about 3 digits. The choice of floating-point type depends on the nature and range of the floating-point numbers to be processed in the code. When multiple floating-point types are suitable, the higher-precision type is preferred because lower-precision types are prone to accumulated calculation errors and have a limited range of precisely representable integers.

Floating-Point Literals

Floating-point literals can be represented in two radix forms: decimal and hexadecimal. In decimal notation, a floating-point literal must contain at least an integer part or a fractional part, and if there is no fractional part, it must include an exponent part (prefixed with e or E, with a base of 10). In hexadecimal notation, a floating-point literal must contain at least an integer part or fractional part (prefixed with 0x or 0X) and must include an exponent part (prefixed with p or P, with a base of 2).

The following examples demonstrate the use of floating-point literals:

let a: Float32 = 3.14       // a is 3.140000 with type Float32
let b: Float32 = 2e3        // b is 2000.000000 with type Float32
let c: Float32 = 2.4e-1     // c is 0.240000 with type Float32
let d: Float64 = .123e2     // d is 12.300000 with type Float64
let e: Float64 = 0x1.1p0    // e is 1.062500 with type Float64
let f: Float64 = 0x1p2      // f is 4.000000 with type Float64
let g: Float64 = 0x.2p4     // g is 2.000000 with type Float64

When using decimal floating-point literals, the type can be explicitly specified by adding a suffix. The correspondence between suffixes and types is as follows:

Floating-point literals with suffixes can be used as shown below:

let a = 3.14f32   // a is 3.140000 with type Float32
let b = 2e3f32    // b is 2000.000000 with type Float32
let c = 2.4e-1f64 // c is 0.240000 with type Float64
let d = .123e2f64 // d is 12.300000 with type Float64

Supported Operations for Floating-Point Types

Floating-point types natively support the following operators: arithmetic operators, relational operators, and compound assignment operators. Floating-point types do not support increment and decrement operators.

Floating-point types can be converted between each other, as well as between floating-point types and integer types. For specific type conversion syntax and rules, refer to Numeric Type Conversions.

Boolean Type

The Boolean type is denoted by Bool and is used to represent logical true and false values.

Boolean Literals

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

The following example demonstrates the use of Boolean literals:

let a: Bool = true
let b: Bool = false

Supported Operations for Boolean Type

Boolean types support the following operators: logical operators (logical NOT !, logical AND &&, logical OR ||), partial relational operators (== and !=), and partial compound assignment operators (&&= and ||=).

Character Type

The character type is represented using Rune, which can represent all characters in the Unicode character set.

Character Type Literals

Character type literals come in three forms: single characters, escape sequences, and universal characters. A Rune literal starts with the character r, followed by a character enclosed in either single or double quotes.

Single character literals examples:

let a: Rune = r'a'
let b: Rune = r"b"

Escape sequences are character sequences that reinterpret the following character. An escape sequence starts with the escape symbol \, followed by the character to be escaped. Examples:

let slash: Rune = r'\\'
let newLine: Rune = r'\n'
let tab: Rune = r'\t'

Universal characters start with \u, followed by 1 to 8 hexadecimal digits enclosed in curly braces, representing the corresponding Unicode character. Examples:

main() {
    let he: Rune = r'\u{4f60}'
    let llo: Rune = r'\u{597d}'
    print(he)
    print(llo)
}

Compiling and executing the above code will output:

你好

Supported Operations for Character Type

Character types support the following operators: relational operators, namely less than (<), greater than (>), less than or equal to (<=), greater than or equal to (>=), equal to (==), and not equal to (!=). These comparisons are based on the Unicode values of the characters.

Rune can be converted to UInt32, and integer types can be converted to Rune. For specific type conversion syntax and rules, please refer to Rune to UInt32 and Integer Type to Rune Conversion.

String Type

The string type is denoted by String and is used to represent textual data, composed of a sequence of Unicode characters.

String Literals

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

Single-line string literals are defined within a pair of single or double quotes. The content within the quotes can consist of any number of arbitrary characters (except for unescaped quotes used to define the string literal and standalone \ characters). Single-line string literals must be written on the same line and cannot span multiple lines. Examples:

let s1: String = ""
let s2 = 'Hello Cangjie Lang'
let s3 = "\"Hello Cangjie Lang\""
let s4 = 'Hello Cangjie Lang\n'

Multi-line string literals must begin and end with three double quotes (""") or three single quotes ('''). The content of the literal starts from the first line after the opening three quotes and continues until the first occurrence of non-escaped three quotes. The content can include any number of arbitrary characters (except for standalone \ characters). Unlike single-line string literals, multi-line string literals can span multiple lines. Examples:

let s1: String = """
    """
let s2 = '''
    Hello,
    Cangjie Lang'''

Multi-line raw string literals begin with one or more hash symbols (#) followed by a single quote (') or double quote ("), followed by any number of valid characters until the same quote and the same number of hash symbols as the opening are encountered. If the matching quote and the same number of hash symbols are not found before the end of the file, a compilation error occurs. Like multi-line string literals, raw multi-line string literals can span multiple lines. The difference is that escape rules do not apply to raw multi-line string literals; the content remains as-is (escape characters are not interpreted, e.g., \n in s2 below is not a newline character but the string \n composed of \ and n). Examples:

let s1: String = #""#
let s2 = ##'#'\n'## // Output: #'\n
let s3 = ###"
    Hello,
    Cangjie
    Lang"### // Line breaks and indentation in this variable are preserved

For assignment operations of the form left = right, if the left operand is of type Byte (an alias for the built-in type UInt8) and the right operand is a string literal representing an ASCII character, the string will be coerced into the Byte type before assignment. If the left operand is of type Rune and the right operand is a single-character string literal, the string will be coerced into the Rune type before assignment.

main() {
    var b: Byte = "0"
    print(b)
    b = "1"
    print(b)
    var r: Rune = "0"
    print(r)
    r = "1"
    print(r)
}

Compiling and executing the above code yields the following output:

484901

Interpolated Strings

An interpolated string is a string literal (not applicable to multi-line raw string literals) containing one or more interpolated expressions. By embedding expressions within the string, it effectively avoids the need for string concatenation. Interpolated strings are commonly used in the println function to output non-string variable values, e.g., println("${x}").

Interpolated expressions must be enclosed in curly braces {} and prefixed with $. The {} can contain one or more declarations or expressions.

When an interpolated string is evaluated, each interpolated expression is replaced by the value of the last item within {}, and the entire interpolated string remains a string.

Below is a simple example of interpolated strings:

main() {
    let fruit = "apples"
    let count = 10
    let s = "There are ${count * count} ${fruit}"
    println(s)

    let r = 2.4
    let area = "The area of a circle with radius ${r} is ${let PI = 3.141592; PI * r * r}"
    println(area)
}

Compiling and executing the above code yields the following output:

There are 100 apples
The area of a circle with radius 2.400000 is 18.095570

Operations Supported by String Type

The string type supports comparison using relational operators and concatenation using +. The following example demonstrates string equality checks and concatenation:

main() {
    let s1 = "abc"
    var s2 = "ABC"
    let r1 = s1 == s2
    println("The result of 'abc' == 'ABC' is: ${r1}")
    let r2 = s1 + s2
    println("The result of 'abc' + 'ABC' is: ${r2}")
}

Compiling and executing the above code yields the following output:

The result of 'abc' == 'ABC' is: false
The result of 'abc' + 'ABC' is: abcABC

Strings also support other common operations, such as splitting and replacing. Below are some examples:

main() {
    var s1 = "abc"
    var s2 = "ABCabc"
    var s3 = "abcyyabcqqabcbc"
    let r1 = s2.contains(s1)    // Checks if s2 contains the string s1
    println(r1)                 // true
    let r2 = s3.split(s1)       // Splits the original string s3 using s1 as the delimiter
    println(r2[1])              // yy
    s1 = s2
    println(s1)                 // ABCabc
}

Tuple Type

A tuple (Tuple) can combine multiple different types into a new type. The tuple type is denoted as (T1, T2, ..., TN), where T1 to TN can be any type, and different types are connected by commas (,). A tuple must be at least binary. For example, (Int64, Float64) represents a binary tuple type, and (Int64, Float64, String) represents a ternary tuple type.

The length of a tuple is fixed, meaning once an instance of a tuple type is defined, its length cannot be changed.

The tuple type is immutable, meaning once an instance of a tuple type is defined, its content (i.e., individual elements) cannot be updated. However, the entire tuple can be overwritten or replaced, for example:

let tuple1 = (8, false)
var tuple2 = (true, 9, 20)
tuple2 = tuple1         // Error, mismatched types
tuple2[0] = false       // Error, 'tuple element' can not be assigned

var tuple3 = (9, true)
tuple3 = tuple1
println(tuple3[0])      // 8
println(tuple3[1])      // false

Tuple Type Literals

The literal of a tuple type is denoted as (e1, e2, ..., eN), where e1 to eN are expressions, and multiple expressions are separated by commas. In the following example, a variable x of type (Int64, Float64) and a variable y of type (Int64, Float64, String) are defined, and tuple type literals are used to assign initial values to them:

let x: (Int64, Float64) = (3, 3.141592)
let y: (Int64, Float64, String) = (3, 3.141592, "PI")

Tuples support accessing elements at specific positions via t[index], where t is a tuple and index is a subscript. The index must be an integer literal starting from 0 and less than the number of tuple elements; otherwise, a compilation error will occur. In the following example, pi[0] and pi[1] are used to access the first and second elements of the binary tuple pi, respectively.

main() {
    var pi = (3.14, "PI")
    println(pi[0])
    println(pi[1])
}

Compiling and executing the above code will output:

3.140000
PI

In assignment expressions, tuples can be used for multiple assignments. Refer to the Assignment Operators section.

Type Parameters of Tuple Types

Explicit type parameter names can be marked for tuple types. In the following example, name and price are type parameter names.

func getFruitPrice(): (name: String, price: Int64) {
    return ("banana", 10)
}

main() {
    let tmp = getFruitPrice()
    var a = tmp[0]
    var b = tmp[1]
    b++
    println("b = ${b}, tmp[1] = ${tmp[1]}")
}

Compiling and executing the above code will output:

b = 11, tmp[1] = 10

For a tuple type, type parameter names must either all be written or all be omitted. Alternating between named and unnamed parameters is not allowed, and the parameter names themselves cannot be used as variables or to access elements in the tuple.

let a: (name: String, Int64) = ("banana", 5) // Error, in a parameter type list, either all parameters must be named, or none of them
let b: (name: String, price: Int64) = ("banana", 5) // OK
b.name // Error, undeclared identifier 'name'

Array Types

Array

The Array type can be used to construct an ordered sequence of data with a single element type.

Cangjie uses Array<T> to represent the Array type, where T denotes the element type of the Array, and T can be any type.

var a: Array<Int64> = [0, 0, 0, 0] // Array whose element type is Int64
var b: Array<String> = ["a1", "a2", "a3"] // Array whose element type is String

Arrays with different element types are considered distinct types, so they cannot be assigned to each other.

Thus, the following example is invalid:

b = a // Type mismatch

An Array can be easily initialized using literals by enclosing a comma-separated list of values in square brackets.

The compiler automatically infers the type of the Array literal based on context.

let a: Array<String> = [] // Created an empty Array whose element type is String
let b = [1, 2, 3, 3, 2, 1] // Created a Array whose element type is Int64, containing elements 1, 2, 3, 3, 2, 1

An Array can also be constructed using a constructor with a specified element type. Here, repeat is a named parameter in the Array constructor.

Note that when initializing an Array with the repeat parameter, the constructor does not copy repeat. If repeat is a reference type, every element in the constructed Array will point to the same reference.

let a = Array<Int64>() // Created an empty Array whose element type is Int64
let c = Array<Int64>(3, repeat: 0) // Created an Array whose element type is Int64, length is 3 and all elements are initialized as 0
let d = Array<Int64>(3, {i => i + 1}) // Created an Array whose element type is Int64, length is 3 and all elements are initialized by the initialization function

In the example let d = Array<Int64>(3, {i => i + 1}), a lambda expression is used as the initialization function to initialize each element in the Array, i.e., {i => i + 1}.

Accessing Array Members

To access all elements of an Array, you can use a for-in loop to iterate through them.

Arrays are ordered by insertion, so the traversal order is always consistent.

main() {
    let arr = [0, 1, 2]
    for (i in arr) {
        println("The element is ${i}")
    }
}

Compiling and executing the above code will output:

The element is 0
The element is 1
The element is 2

To determine the number of elements in an Array, use the size property.

main() {
    let arr = [0, 1, 2]
    if (arr.size == 0) {
        println("This is an empty array")
    } else {
        println("The size of array is ${arr.size}")
    }
}

Compiling and executing the above code will output:

The size of array is 3

To access a single element at a specific position, use subscript syntax (the subscript must be of type Int64). The first element of a non-empty Array always starts at position 0. You can access any element from 0 up to the last position (Array.size - 1). Negative indices or indices greater than or equal to size are invalid. If the compiler detects an invalid index, it will report an error at compile time; otherwise, it will throw an exception at runtime.

main() {
    let arr = [0, 1, 2]
    let a = arr[0] // a == 0
    let b = arr[1] // b == 1
    let c = arr[-1] // array size is '3', but access index is '-1', which would overflow
}

To retrieve a segment of an Array, you can pass a Range type value to the subscript, which will return a sub-Array corresponding to the specified range.

let arr1 = [0, 1, 2, 3, 4, 5, 6]
let arr2 = arr1[0..5] // arr2 contains the elements 0, 1, 2, 3, 4

When a Range literal is used in subscript syntax, the start or end can be omitted.

If start is omitted, the Range starts from 0; if end is omitted, the Range extends to the last element.

let arr1 = [0, 1, 2, 3, 4, 5, 6]
let arr2 = arr1[..3] // arr2 contains elements 0, 1, 2
let arr3 = arr1[2..] // arr3 contains elements 2, 3, 4, 5, 6

Modifying Arrays

Arrays are fixed-length Collection types, so they do not provide member functions for adding or removing elements.

However, Arrays allow modification of their elements using subscript syntax.

main() {
    let arr = [0, 1, 2, 3, 4, 5]
    arr[0] = 3
    println("The first element is ${arr[0]}")
}

Compiling and executing the above code will output:

The first element is 3

Although Arrays are struct types, they internally hold references to elements. Thus, when used as expressions, they do not create copies. All references to the same Array instance share the same element data.

Therefore, modifications to an Array’s elements affect all references to that instance.

let arr1 = [0, 1, 2]
let arr2 = arr1
arr2[0] = 3
// arr1 contains elements 3, 1, 2
// arr2 contains elements 3, 1, 2

VArray

In addition to the reference-type Array, Cangjie introduces a value-type array VArray<T, $N>, where T is the element type and $N is a fixed syntax. The $ followed by an Int64 literal denotes the length of the value-type array. Note that VArray<T, $N> cannot omit <T, $N>, and when using type aliases, the VArray keyword and its generic parameters cannot be split.

Compared to frequently using reference-type Arrays, value-type VArrays reduce heap memory allocation and garbage collection pressure. However, due to the overhead of copying during value-type passing and assignment, it is not recommended to use large VArrays in performance-sensitive scenarios. For characteristics of value types and reference types, refer to Value Types and Reference Type Variables.

type varr1 = VArray<Int64, $3> // OK
type varr2 = VArray // Error

Note:

Due to runtime backend limitations, the element type T of VArray<T, $N> or its members cannot contain reference types, enum types, lambda expressions (except CFunc), or uninstantiated generic types.

A VArray can be initialized using an array literal, where the left-hand side a must specify the instantiated type of VArray:

var a: VArray<Int64, $3> = [1, 2, 3]

It also has two constructors:

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

Additionally, VArray<T, $N> provides two member methods:

• The [] operator method for subscript access and modification:

  var a: VArray<Int64, $3> = [1, 2, 3]
  let i = a[1] // i is 2
  a[2] = 4 // a is [1, 2, 4]
  

  The subscript must be of type Int64.

• The size member to get the length of the VArray:

  var a: VArray<Int64, $3> = [1, 2, 3]
  let s = a.size // s is 3
  

  The size property is of type Int64.

Furthermore, VArray supports interoperability between Cangjie and C. For details, refer to Arrays.

Range Type

The range type is used to represent sequences with a fixed step size. It is a generic type denoted as Range<T>. When T is instantiated with different types, the type must support relational operators and be capable of addition with values of type Int64, resulting in different range types. For example, the most commonly used Range<Int64> represents integer ranges.

Each instance of a range type contains three values: start, end, and step. Here, start and end represent the initial and terminal values of the sequence, respectively, while step denotes the difference between consecutive elements (i.e., the step size). The types of start and end are the same (i.e., the type with which T is instantiated), whereas step is of type Int64 and cannot be equal to 0.

The following example demonstrates how to instantiate range types (for details on range type definitions and their properties, refer to the Cangjie Programming Language Library API):

// Range<T>(start: T, end: T, step: Int64, hasStart: Bool, hasEnd: Bool, isClosed: Bool)
let r1 = Range<Int64>(0, 10, 1, true, true, true) // r1 contains 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
let r2 = Range<Int64>(0, 10, 1, true, true, false) // r2 contains 0, 1, 2, 3, 4, 5, 6, 7, 8, 9
let r3 = Range<Int64>(10, 0, -2, true, true, false) // r3 contains 10, 8, 6, 4, 2

Range Type Literals

Range literals come in two forms: “left-closed right-open” and “left-closed right-closed” ranges.

• The “left-closed right-open” range is formatted as start..end : step, representing a range that starts at start, increments by step, and ends before end (excluding end).
• The “left-closed right-closed” range is formatted as start..=end : step, representing a range that starts at start, increments by step, and includes end (including end).

The following example defines several range-type variables:

let n = 10
let r1 = 0..10 : 1   // r1 contains 0, 1, 2, 3, 4, 5, 6, 7, 8, 9
let r2 = 0..=n : 1   // r2 contains 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
let r3 = n..0 : -2   // r3 contains 10, 8, 6, 4, 2
let r4 = 10..=0 : -2 // r4 contains 10, 8, 6, 4, 2, 0

In range literals, step can be omitted, in which case it defaults to 1. However, the value of step cannot be 0. Additionally, a range may be empty (i.e., a sequence containing no elements), as shown below:

let r5 = 0..10   // the step of r5 is 1, and r5 contains 0, 1, 2, 3, 4, 5, 6, 7, 8, 9
let r6 = 0..10 : 0 // Error, step cannot be 0

let r7 = 10..0 : 1 // r7 to r10 are empty ranges
let r8 = 0..10 : -1
let r9 = 10..=0 : 1
let r10 = 0..=10 : -1

Note:

• For the expression start..end : step, when step > 0 and start >= end, or when step < 0 and start <= end, start..end : step is an empty range.
• For the expression start..=end : step, when step > 0 and start > end, or when step < 0 and start < end, start..=end : step is an empty range.

The Unit Type

For expressions that only concern side effects without caring about values, their type is Unit. For example, the print function, assignment expressions, compound assignment expressions, increment and decrement expressions, and loop expressions all have the Unit type.

The Unit type has only one value, which is also its literal: (). Apart from assignment, equality checks, and inequality checks, the Unit type does not support other operations.

The Nothing Type

Nothing is a special type that contains no values, and the Nothing type is a subtype of all types (including the Unit type).

The break, continue, return, and throw expressions are of type Nothing. When program execution reaches these expressions, the code following them will not be executed. return can only be used within a function body, while break and continue can only be used within loop bodies. Refer to the following example:

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
    }
}

Since function parameters and their default values do not belong to the function body, the return expression in the following example lacks an enclosing function body—it neither belongs to the outer function f (because the inner function definition g has already started) nor is it within the inner function g’s body (for related content on this use case, refer to Nested Functions):

func f() {
    func g(x!: Int64 = return) { // Error, return must be used inside a function body
        0
    }
    1
}

Note:

Currently, the compiler does not allow explicit use of the Nothing type in places where types are required.

Defining Functions

In Cangjie, the keyword func is used to denote the start of a function definition. Following func are the function name, parameter list, optional return type, and function body in sequence. The function name can be any valid identifier. The parameter list is enclosed in parentheses (with multiple parameters separated by commas), a colon separates the parameter list from the return type (if present), and the function body is enclosed in curly braces.

Example of a function definition:

func add(a: Int64, b: Int64): Int64 {
    return a + b
}

The above example defines a function named add with a parameter list consisting of two Int64 parameters a and b, a return type of Int64, and a function body that returns the sum of a and b.

The following sections provide further details on the parameter list, return type, and function body in function definitions.

Parameter List

A function can have zero or more parameters, all defined in the parameter list. Parameters in the parameter list can be categorized into two types based on whether parameter names are required during function calls: non-named parameters and named parameters.

Non-named parameters are defined as p: T, where p is the parameter name and T is the type of parameter p, connected by a colon. For example, the parameters a and b in the add function above are non-named parameters.

Named parameters are defined as p!: T, differing from non-named parameters by the addition of ! after the parameter name p. The non-named parameters in the add function can be modified to named parameters as shown below:

func add(a!: Int64, b!: Int64): Int64 {
    return a + b
}

Named parameters can also have default values, specified via p!: T = e, where the default value of parameter p is set to the value of expression e. For example, the default values of the two parameters in the add function can be set to 1:

func add(a!: Int64 = 1, b!: Int64 = 1): Int64 {
    return a + b
}

Note:

Only named parameters can have default values; non-named parameters cannot.

A parameter list can include both non-named and named parameters. However, non-named parameters must be defined before named parameters, meaning no non-named parameters can appear after named parameters. For example, the following parameter list definition for the add function is invalid:

func add(a!: Int64, b: Int64): Int64 { // Error, named parameter 'a' must be defined after non-named parameter 'b'
    return a + b
}

The primary difference between non-named and named parameters lies in their behavior during function calls. For details, refer to the Calling Functions section below.

Function parameters are immutable variables and cannot be assigned values within the function definition.

func add(a: Int64, b: Int64): Int64 {
    a = a + b // Error
    return a
}

The scope of function parameters extends from their definition to the end of the function body:

func add(a: Int64, b: Int64): Int64 {
    var a_ = a // OK
    var b = b  // Error, redefinition of declaration 'b'
    return a
}

Return Type

The return type of a function is the type of the value obtained when the function is called. In function definitions, the return type is optional: it can be explicitly defined (placed between the parameter list and the function body) or omitted, leaving it to the compiler to infer.

When the return type is explicitly defined, the type of the function body (see the Function Body section below for how the function body type is determined) and the types of all return e expressions in the function body must be subtypes of the return type. For example, in the add function above, the return type is explicitly defined as Int64. If the function body is modified to return (a, b), a type mismatch error will occur:

// Error, the type of the expression after return does not match the return type of the function
func add(a: Int64, b: Int64): Int64 {
    return (a, b)
}

If the return type is not explicitly defined in the function definition, the compiler infers it based on the type of the function body and all return expressions in the function body. For example, in the following add function, the return type is omitted, but the compiler can infer it as Int64 from return a + b:

func add(a: Int64, b: Int64) {
    return a + b
}

Note:

The return type of a function cannot always be inferred. If type inference fails, the compiler will report an error.

When the return type is specified as Unit, the compiler automatically inserts return () at all possible return points in the function body, ensuring the return type is always Unit.

Function Body

The function body defines the operations executed when the function is called. It typically consists of a series of variable definitions and expressions and can also include nested function definitions. For example, the function body of the add function below first defines a variable r of type Int64 (initialized to 0), assigns the value of a + b to r, and finally returns r:

func add(a: Int64, b: Int64) {
    var r = 0
    r = a + b
    return r
}

A return expression can be used anywhere in the function body to terminate the function’s execution and return a value. There are two forms of return expressions: return and return expr (where expr is an expression).

For return expr, the type of expr must match the function’s return type. For example, the following example will error because the type of 100 (Int64) does not match the return type of function foo (String):

// Error, cannot convert an integer literal to type 'Struct-String'
func foo(): String {
    return 100
}

For return, it is equivalent to return (), so the function’s return type must be Unit.

func add(a: Int64, b: Int64) {
    var r = 0
    r = a + b
    return r
}

func foo(): Unit {
    add(1, 2)
    return
}

Note:

The return expression as a whole has the type Nothing, regardless of the expression that follows it.

Variables defined within the function body are a type of local variable (e.g., variable r in the example above). Their scope extends from their definition to the end of the function body.

For a local variable, it is allowed to define a variable with the same name in an outer scope. Within the local variable’s scope, the local variable will “shadow” the variable of the same name in the outer scope. For example:

let r = 0
func add(a: Int64, b: Int64) {
    var r = 0
    r = a + b
    return r
}

In the example above, a global variable r of type Int64 is defined before the add function, and a local variable r with the same name is defined within the function body. Within the function body, all references to r (e.g., r = a + b) will refer to the local variable r, meaning the local variable r “shadows” the global variable r within the function body.

As mentioned in the Return Type section, the function body also has a type. The type of the function body is the type of the last “item” in the function body: if the last item is an expression, the function body’s type is the type of that expression; if the last item is a variable definition, function declaration, or the function body is empty, the function body’s type is Unit. For example:

func add(a: Int64, b: Int64): Int64 {
    a + b
}

In the example above, since the last “item” in the function body is an expression of type Int64 (i.e., a + b), the function body’s type is also Int64, matching the function’s return type. Similarly, in the following example, the last item in the function body is a call to the print function, so the function body’s type is Unit, which also matches the function’s return type:

func foo(): Unit {
    let s = "Hello"
    print(s)
}

Function Invocation

A function is invoked in the form f(arg1, arg2, ..., argn), where f is the name of the function to be called, and arg1 through argn are the n arguments (called actual parameters) passed during invocation. Each actual parameter’s type must be a subtype of the corresponding parameter’s type. The number of actual parameters can range from zero to multiple. When there are zero parameters, the invocation takes the form f().

Depending on whether the parameters in the function definition are positional or named, the way arguments are passed during invocation differs:

• For positional parameters, the corresponding argument is an expression.
• For named parameters, the argument must be passed in the form p: e, where p is the name of the named parameter and e is the expression (i.e., the value passed to parameter p).

Example of positional parameter invocation:

func add(a: Int64, b: Int64) {
    return a + b
}

main() {
    let x = 1
    let y = 2
    let r = add(x, y)
    println("The sum of x and y is ${r}")
}

Execution result:

The sum of x and y is 3

Example of named parameter invocation:

func add(a: Int64, b!: Int64) {
    return a + b
}

main() {
    let x = 1
    let y = 2
    let r = add(x, b: y)
    println("The sum of x and y is ${r}")
}

Execution result:

The sum of x and y is 3

For functions with multiple named parameters, the order of passing arguments during invocation can differ from the parameter order in the definition. For example, in the following case, parameter b can appear before a when invoking the add function:

func add(a!: Int64, b!: Int64) {
    return a + b
}

main() {
    let x = 1
    let y = 2
    let r = add(b: y, a: x)
    println("The sum of x and y is ${r}")
}

Execution result:

The sum of x and y is 3

For named parameters with default values, if no argument is passed during invocation, the parameter will use its default value. For example, in the following case, when invoking the add function, no argument is passed for parameter b, so its value defaults to 2 as defined:

func add(a: Int64, b!: Int64 = 2) {
    return a + b
}

main() {
    let x = 1
    let r = add(x)
    println("The sum of x and y is ${r}")
}

Execution result:

The sum of x and y is 3

For named parameters with default values, new arguments can also be passed during invocation. In this case, the parameter’s value will be the new argument’s value, overriding the default. For example, in the following case, when invoking the add function, a new argument value 20 is passed for parameter b, so its value becomes 20:

func add(a: Int64, b!: Int64 = 2) {
    return a + b
}

main() {
    let x = 1
    let r = add(x, b: 20)
    println("The sum of x and y is ${r}")
}

Execution result:

The sum of x and y is 21

Function Types

In the Cangjie programming language, functions are first-class citizens, meaning they can be passed as arguments to other functions, returned as values from functions, or assigned to variables. Therefore, functions themselves have types, referred to as function types.

A function type consists of the function’s parameter types and return type, connected by ->. Parameter types are enclosed in parentheses (), which can contain zero or more parameters. If there are multiple parameters, their types are separated by commas (,).

For example:

func hello(): Unit {
    println("Hello!")
}

The above example defines a function named hello with the type () -> Unit, indicating that this function takes no parameters and returns Unit.

Here are some additional examples:

• Example: A function named display with type (Int64) -> Unit, indicating it takes one parameter of type Int64 and returns Unit.

  func display(a: Int64): Unit {
      println(a)
  }
  

• Example: A function named add with type (Int64, Int64) -> Int64, indicating it takes two parameters of type Int64 and returns Int64.

  func add(a: Int64, b: Int64): Int64 {
      a + b
  }
  

• Example: A function named returnTuple with type (Int64, Int64) -> (Int64, Int64), taking two Int64 parameters and returning a tuple type (Int64, Int64).

  func returnTuple(a: Int64, b: Int64): (Int64, Int64) {
      (a, b)
  }
  

Type Parameters in Function Types

Function types can have explicit type parameter names. In the following example, name and price are type parameter names.

func showFruitPrice(name: String, price: Int64) {
    println("fruit: ${name} price: ${price} yuan")
}

main() {
    let fruitPriceHandler: (name: String, price: Int64) -> Unit
    fruitPriceHandler = showFruitPrice
    fruitPriceHandler("banana", 10)
}

Note that for a function type, you must either consistently include type parameter names or omit them entirely; mixing them is not allowed.

let handler: (name: String, Int64) -> Int64   // Error

Function Types as Parameter Types

Example: A function named printAdd with type ((Int64, Int64) -> Int64, Int64, Int64) -> Unit, indicating it takes three parameters: a function type (Int64, Int64) -> Int64 and two Int64 values, returning Unit.

func printAdd(add: (Int64, Int64) -> Int64, a: Int64, b: Int64): Unit {
    println(add(a, b))
}

Function Types as Return Types

Function types can also serve as the return type of another function.

In the following example, the function returnAdd has type () -> (Int64, Int64) -> Int64, meaning it takes no parameters and returns a function of type (Int64, Int64) -> Int64. Note that -> is right-associative.

func add(a: Int64, b: Int64): Int64 {
    a + b
}

func returnAdd(): (Int64, Int64) -> Int64 {
    add
}

main() {
    var a = returnAdd()
    println(a(1,2))
}

Function Types as Variable Types

Function names themselves are expressions, and their types correspond to their function types.

func add(p1: Int64, p2: Int64): Int64 {
    p1 + p2
}

let f: (Int64, Int64) -> Int64 = add

In the above example, the function add has type (Int64, Int64) -> Int64. The variable f is declared with the same type and initialized with add.

If a function is overloaded in the current scope (see Function Overloading), using the function name directly as an expression may cause ambiguity. In such cases, the compiler will report an error:

func add(i: Int64, j: Int64) {
    i + j
}

func add(i: Float64, j: Float64) {
    i + j
}

main() {
    var f = add   // Error, ambiguous function 'add'
    var plus: (Int64, Int64) -> Int64 = add  // OK
}

Nested Functions

Functions defined at the top level of a source file are called global functions. Functions defined within the body of another function are called nested functions.

Scope of Usage:

• The scope of a nested function is limited to its enclosing outer function. Nested functions can access variables and parameters of the outer function, but the outer function cannot directly access the internal variables of nested functions.
• Nested functions can be called by the outer function or returned by the outer function.

Lifecycle:

• The lifecycle of a nested function is closely tied to its outer function. Each time the outer function is called, the nested function is created; when the outer function completes execution, the nested function is typically destroyed unless it is externally referenced through return values or closures.

Usage Rules and Considerations:

• Use nested functions only within their corresponding outer functions.
• Avoid excessive nesting. This can complicate code structure, making it difficult to understand and maintain. Therefore, avoid excessive nesting that leads to code confusion.
• Be mindful of closure usage. If a nested function is returned and used as a closure, note that the closure may capture variables from the outer function, causing these variables to remain occupied even after the outer function completes, thereby affecting memory management.

Example: The function foo defines a nested function nestAdd inside it. The nested function nestAdd can be called within foo, or it can be returned as a value to be called outside foo:

func foo() {
    func nestAdd(a: Int64, b: Int64) {
        a + b + 3
    }

    println(nestAdd(1, 2))  // 6

    return nestAdd
}

main() {
    let f = foo()
    let x = f(1, 2)
    println("result: ${x}")
}

The program will output:

6
result: 6

Lambda Expressions

Definition of Lambda Expressions

A lambda expression is an anonymous function (i.e., a function without a name) designed to quickly define concise function logic in programs without explicitly declaring a function name. This concept originates from lambda calculus in mathematics and has been introduced into various programming languages (such as C++, Python, C#, etc.) to simplify code and enhance flexibility. The Cangjie programming language also incorporates lambda expressions, and their usage will be detailed in this section.

The syntax of a lambda expression is as follows: { p1: T1, ..., pn: Tn => expressions | declarations }.

Here, the part before => is the parameter list, where multiple parameters are separated by ,, and each parameter name and type are separated by :. The part before => can also be empty (parameterless). The part after => is the lambda expression body, which consists of a sequence of expressions or declarations. The scope of lambda expression parameter names is the same as that of functions, limited to the lambda expression body, and their scope level is equivalent to variables defined within the lambda expression body.

let f1 = { a: Int64, b: Int64 => a + b }

var display = { =>   // Parameterless lambda expression.
    println("Hello")
    println("World")
}

Lambda expressions, whether they have parameters or not, cannot omit =>, unless they are used as trailing lambdas. For example:

var display = { => println("Hello") }

func f2(lam: () -> Unit) {}
let f2Res = f2 { println("World") } // OK to omit the =>

Type annotations for parameters in lambda expressions can be omitted. In the following cases, if parameter types are omitted, the compiler will attempt type inference. If the compiler cannot infer the type, a compilation error will occur:

• When a lambda expression is assigned to a variable, its parameter types are inferred from the variable type;
• When a lambda expression is used as an argument in a function call, its parameter types are inferred from the function’s parameter types.

// The parameter types are inferred from the type of the variable sum1
var sum1: (Int64, Int64) -> Int64 = { a, b => a + b }

var sum2: (Int64, Int64) -> Int64 = { a: Int64, b => a + b }

func f(a1: (Int64) -> Int64): Int64 {
    a1(1)
}

main(): Int64 {
    // The parameter type of lambda is inferred from the type of function f
    f({ a2 => a2 + 10 })
}

Lambda expressions do not support explicit return type declarations. Their return type is always inferred from the context, and an error is reported if inference fails.

• If the context explicitly specifies the return type of the lambda expression, its return type is the context-specified type.

  • When a lambda expression is assigned to a variable, its return type is inferred from the variable type:

    let f: () -> Unit = { => println(10) }
    

  • When a lambda expression is used as an argument, its return type is inferred from the parameter type of the function call:

    func f(a1: (Int64) -> Int64): Int64 {
      a1(1)
    }
    
    main(): Int64 {
      f({ a2: Int64 => a2 + 10 })
    }
    

  • When a lambda expression is used as a return value, its return type is inferred from the return type of the enclosing function:

    func f(): (Int64) -> Int64 {
      { a: Int64 => a }
    }
    

• If the context does not explicitly specify the type, similar to deriving the return type of a function, the compiler will infer the return type of the lambda expression based on the types of all return xxx expressions in the lambda body and the type of the lambda body itself.

  • The content to the right of => follows the same rules as a regular function body, with the return type being Int64:

    let sum1 = { a: Int64, b: Int64 => a + b }
    

  • If the right side of => is empty, the return type is Unit:

    let f = { => }
    

Lambda Expression Invocation

Lambda expressions support immediate invocation. For example:

let r1 = { a: Int64, b: Int64 => a + b }(1, 2) // r1 = 3
let r2 = { => 123 }()                          // r2 = 123

Lambda expressions can also be assigned to a variable and invoked using the variable name. For example:

func f() {
    var g = { x: Int64 => println("x = ${x}") }
    g(2)
}

Closures

A function or lambda that captures variables from its static scope is referred to as a closure. The combination of the function/lambda and the captured variables forms a closure, enabling it to operate correctly even when outside the scope where it was defined.

Variable capture occurs in a function or lambda definition when accessing the following types of variables:

• Accessing a local variable defined outside the current function in the default parameter values;

• Accessing a local variable defined outside the current function or lambda within the function or lambda;

• Accessing instance member variables or this in a non-member function or lambda defined within a class/struct.

The following scenarios do not constitute variable capture:

• Accessing local variables defined within the current function or lambda;

• Accessing formal parameters of the current function or lambda;

• Accessing global variables and static member variables;

• Accessing instance member variables within instance member functions or properties. Since instance member functions or properties receive this as a parameter, all instance member variables are accessed via this within them.

Variable capture occurs at the time of closure definition, thus adhering to the following rules:

• The captured variable must be visible at the time of closure definition, otherwise a compilation error occurs;

• The captured variable must be fully initialized at the time of closure definition, otherwise a compilation error occurs.

Example 1: The closure add captures the locally declared variable num with let. Later, it is returned via the function and invoked outside the scope where num was defined, yet it can still access num normally.

func returnAddNum(): (Int64) -> Int64 {
    let num: Int64 = 10

    func add(a: Int64) {
        return a + num
    }
    add
}

main() {
    let f = returnAddNum()
    println(f(10))
}

The program outputs:

20

Example 2: Captured variables must be visible at the time of closure definition.

func f() {
    let x = 99
    func f1() {
        println(x)
    }
    let f2 = { =>
        println(y)  // Error, cannot capture 'y' which is not defined yet
    }
    let y = 88
    f1()            // Print 99
    f2()
}

Example 3: Captured variables must be initialized before the closure definition.

func f() {
    let x: Int64
    func f1() {
        println(x) // Error, x is not initialized yet
    }
    x = 99
    f1()
}

Example 4: If the captured variable is a reference type, the value of its mutable instance member variables can be modified.

class C {
    public var num: Int64 = 0
}

func returnIncrementer(): () -> Unit {
    let c: C = C()

    func incrementer() {
        c.num++
    }

    incrementer
}

main() {
    let f = returnIncrementer()
    f() // c.num increases by 1
}

Example 5: To prevent closures capturing variables declared with var from escaping, such closures can only be invoked and cannot be used as first-class citizens. This includes prohibiting assignment to variables, use as arguments or return values, and direct use of the closure name as an expression. A closure is considered escaping if it can be invoked outside the function after the function has completed execution.

func f() {
    var x = 1
    let y = 2

    func g() {
        println(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

    g               // Error, g cannot be used as a return value
}

Example 6: Note that capture is transitive. If a function f invokes a function g that captures a var variable, and the var variable captured by g is not defined within f, then f also captures the var variable. In this case, f cannot be used as a first-class citizen either.

Example 6.1: g captures the var-declared variable x, f invokes g, and the x captured by g is not defined within f. Thus, f also 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
}

Example 6.2: g captures the var-declared variable x, and f invokes g. However, the x captured by g is defined within f, and f does not capture any other var-declared variables. Therefore, f can still be used as a first-class citizen:

func h(){
    func f() {
        var x = 1
        func g() { x } // captured a mutable variable

        g()
    }
    return f // OK
}

Example 7: Accessing static member variables and global variables does not constitute variable capture. Therefore, functions or lambdas accessing var-declared global variables or static member variables can still be used as first-class citizens.

class C {
    static public var a: Int32 = 0
    static public 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()
}

Function Call Syntactic Sugar

Trailing Lambda

Trailing lambda syntax can make function calls appear as if they were built-in language constructs, enhancing the language’s extensibility.

When the last parameter of a function is of function type, and the corresponding argument in the function call is a lambda, the trailing lambda syntax can be used by placing the lambda outside the parentheses at the end of the function call.

For example, the following defines a myIf function where the first parameter is of type Bool and the second is a function type. When the first parameter is true, it returns the value from calling the second parameter; otherwise, it returns 0. The myIf function can be called either as a regular function or using trailing lambda syntax.

func myIf(a: Bool, fn: () -> Int64) {
    if(a) {
        fn()
    } else {
        0
    }
}

func test() {
    myIf(true, { => 100 }) // General function call

    myIf(true) {        // Trailing closure call
        100
    }
}

When a function call has exactly one lambda argument, the () can be omitted, leaving only the lambda.

Example:

func f(fn: (Int64) -> Int64) { fn(1) }

func test() {
    f { i => i * i }
}

Flow Expressions

Flow operators include two types: the infix operator |> (called pipeline) representing data flow and the infix operator ~> (called composition) representing function composition.

Pipeline Expressions

When a series of transformations need to be applied to input data, pipeline expressions can simplify the description. The syntax for a pipeline expression is: e1 |> e2, which is equivalent to the following syntactic sugar: let v = e1; e2(v).

Here, e2 is an expression of function type, and the type of e1 must be a subtype of e2’s parameter type.

Example:

func inc(x: Array<Int64>): Array<Int64> { // Increasing the value of each element in the array by '1'
    let s = x.size
    var i = 0
    for (e in x where i < s) {
        x[i] = e + 1
        i++
    }
    x
}

func sum(y: Array<Int64>): Int64 { // Get the sum of elements in the array
    var s = 0
    for (j in y) {
        s += j
    }
    s
}

let arr: Array<Int64> = [1, 3, 5]
let res = arr |> inc |> sum // res = 12

Composition Expressions

composition expressions represent the composition of two single-parameter functions. The syntax for a composition expression is f ~> g, which is equivalent to { x => g(f(x)) }.

Here, both f and g must be expressions of function type with exactly one parameter.

For f and g to compose, the return type of f(x) must be a subtype of the parameter type of g(...).

Example 1:

func f(x: Int64): Float64 {
    Float64(x)
}
func g(x: Float64): Float64 {
    x
}

var fg = f ~> g // The same as { x: Int64 => g(f(x)) }

Example 2:

func f(x: Int64): Float64 {
    Float64(x)
}

let lambdaComp = {x: Int64 => x} ~> f // The same as { x: Int64 => f({x: Int64 => x}(x)) }

Example 3:

func h1<T>(x: T): T { x }
func h2<T>(x: T): T { x }
var hh = h1<Int64> ~> h2<Int64> // The same as { x: Int64 => h2<Int64>(h1<Int64>(x)) }

Note:

In the expression f ~> g, f is evaluated first, followed by g, and then the function composition is performed.

Additionally, flow operators cannot be directly used with functions that have non-default named parameters because such functions require named arguments to be explicitly provided. For example:

func f(a!: Int64): Unit {}

var a = 1 |> f  // Error

If needed, developers can pass named arguments to the f function via a lambda expression:

func f(a!: Int64): Unit {}

var x = 1 |>  { x: Int64 => f(a: x) } // OK

For the same reason, when f has default parameter values, using it directly with flow operators is also incorrect:

func f(a!: Int64 = 2): Unit {}

var a = 1 |> f // Error

However, when all named parameters have default values, the function can be called without providing named arguments, requiring only non-named parameters. Such functions can be used with flow operators:

func f(a: Int64, b!: Int64 = 2): Unit {}

var a = 1 |> f  // OK

Of course, if you want to pass other arguments to parameter b when calling f, you still need to use a lambda expression:

func f(a: Int64, b!: Int64 = 2): Unit {}

var a = 1 |> {x: Int64 => f(x,  b: 3)}  // OK

Variadic Parameters

Variadic parameters are a special function call syntactic sugar. When the last non-named parameter of a function is of type Array, the corresponding argument position can directly accept a sequence of parameters instead of an Array literal (the number of parameters can be zero or more). Example:

func sum(arr: Array<Int64>) {
    var total = 0
    for (x in arr) {
        total += x
    }
    return total
}

main() {
    println(sum())
    println(sum(1, 2, 3))
}

Program output:

0
6

Note that only the last non-named parameter can be a variadic parameter. Named parameters cannot use this syntactic sugar.

func length(arr!: Array<Int64>) {
    return arr.size
}

main() {
    println(length())        // Error, expected 1 argument, found 0
    println(length(1, 2, 3)) // Error, expected 1 argument, found 3
}

Variadic parameters can appear in global functions, static member functions, instance member functions, local functions, constructors, function variables, lambdas, function call operator overloads, and index operator overloads. They are not supported in other operator overloads, composition, or pipeline calls. Example:

class Counter {
    var total = 0
    init(data: Array<Int64>) { total = data.size }
    operator func ()(data: Array<Int64>) { total += data.size }
}

main() {
    let counter = Counter(1, 2)
    println(counter.total)
    counter(3, 4, 5)
    println(counter.total)
}

Program output:

2
5

Function overload resolution always prioritizes functions that can match without using variadic parameters. Only when no functions match will the compiler attempt to resolve using variadic parameters. Example:

func f<T>(x: T) where T <: ToString {
    println("item: ${x}")
}

func f(arr: Array<Int64>) {
    println("array: ${arr}")
}

main() {
    f()
    f(1)
    f(1, 2)
}

Program output:

array: []
item: 1
array: [1, 2]

When the compiler cannot resolve the ambiguity, it will report an error:

func f(arr: Array<Int64>) { arr.size }
func f(first: Int64, arr: Array<Int64>) { first + arr.size }

main() {
    println(f(1, 2, 3)) // Error
}

Function Overloading

Definition of Function Overloading

In the Cangjie programming language, when multiple function definitions share the same name within a scope, this phenomenon is called function overloading.

• Two functions constitute overloading if they share the same name but have different parameters (either differing in parameter count or having the same count but different parameter types). Example:

  // Scenario 1
  
  func f(a: Int64): Unit {}
  func f(a: Float64): Unit {}
  func f(a: Int64, b: Float64): Unit {}
  

• For two generic functions with the same name (see the Generic Functions chapter), if after renaming the generic type parameters of one function (to make the generic parameter order identical), their non-generic parts have different function parameters, they constitute overloading. Otherwise, these two generic functions result in a duplicate definition error (type argument constraints are not considered in this judgment). Example:

  // Scenario 2
  
  interface I1{}
  interface I2{}
  
  func f1<X, Y>(a: X, b: Y) {}
  func f1<Y, X>(a: X, b: Y) {} // OK: after rename generic type parameter, it will be 'func f1<X, Y>(a: Y, b: X)'
  
  func f2<T>(a: T) where T <: I1 {} // Error, not overloading
  func f2<T>(a: T) where T <: I2 {} // Error, not overloading
  

• Two constructors within the same class with different parameters constitute overloading. Example:

  // Scenario 3
  
  class C {
      var a: Int64
      var b: Float64
  
      public init(a: Int64, b: Float64) {
          this.a = a
          this.b = b
      }
  
      public init(a: Int64) {
          b = 0.0
          this.a = a
      }
  }
  

• The primary constructor and init constructor within the same class with different parameters constitute overloading (the primary constructor and init function are considered to share the same name). Example:

  // Scenario 4
  
  class C {
      C(var a!: Int64, var b!: Float64) {
          this.a = a
          this.b = b
      }
  
      public init(a: Int64) {
          b = 0.0
          this.a = a
      }
  }
  

• Two functions with the same name but different parameters defined in different scopes constitute overloading in a scope where both functions are visible. Example:

  // Scenario 5
  
  func f(a: Int64): Unit {}
  
  func g() {
      func f(a: Float64): Unit {}
  }
  

• If a subclass contains a function with the same name as its parent class but with different parameter types, this constitutes function overloading. Example:

  // Scenario 6
  open class Base {
      public func f(a: Int64): Unit {}
  }
  
  class Sub <: Base {
      public func f(a: Float64): Unit {}
  }
  

Only function declarations can introduce function overloading. The following scenarios do not constitute overloading, and two names that do not constitute overloading cannot be defined or declared in the same scope:

• Static member functions and instance member functions of class, interface, or struct types cannot overload each other.
• Constructors, static member functions, and instance member functions of enum types cannot overload each other.

In the following example, both variables are of function type with different parameter types, but since they are not function declarations, they cannot overload each other. The example will result in a compilation error (redefinition error):

main() {
    var f: (Int64) -> Unit
    var f: (Float64) -> Unit
}

In the following example, although variable f is of function type, variables and functions cannot share the same name. The example will result in a compilation error (redefinition error):

main() {
    var f: (Int64) -> Unit
    func f(a: Float64): Unit {} // Error, functions and variables cannot have the same name
}

In the following example, the static member function f and instance member function f have different parameter types, but since static and instance member functions within a class cannot overload each other, the example will result in a compilation error:

class C {
    public static func f(a: Int64): Unit {}
    public func f(a: Float64): Unit {}
}

Function Overload Resolution

When a function is called, all callable functions (those visible in the current scope and passing type checks) form a candidate set. To determine which function in the candidate set to select, function overload resolution follows these rules:

• Prefer functions in higher-scoped contexts. In nested expressions or functions, inner scopes have higher precedence.

  In the following example, when calling g(Sub()) within the inner function body, the candidate set includes both the g function defined inside inner and the g function defined outside inner. The resolution selects the higher-scoped g function inside inner.

  open class Base {}
  class Sub <: Base {}
  
  func outer() {
      func g(a: Sub) {
          print("1")
      }
  
      func inner() {
          func g(a: Base) {
              print("2")
          }
  
          g(Sub())   // Output: 2
      }
  }
  

• If multiple functions exist in the highest relative scope, select the most matching function (for functions f and g with given arguments, if f can always be called when g can be called but not vice versa, then f is considered more matching than g). If no unique most matching function exists, an error is reported.

  In the following example, two g functions are defined in the same scope, and the more matching g(a: Sub): Unit is selected.

  open class Base {}
  class Sub <: Base {}
  
  func outer() {
      func g(a: Sub) {
          print("1")
      }
      func g(a: Base) {
          print("2")
      }
  
      g(Sub())   // Output: 1
  
  }
  

• Subclasses and parent classes are considered the same scope. In the following example, one g function is defined in the parent class, and another g function is defined in the subclass. When calling s.g(Sub()), both g functions are resolved at the same scope level, and the more matching g(a: Sub): Unit from the parent class is selected.

  open class Base {
      public func g(a: Sub) {
          print("1")
      }
  }
  
  class Sub <: Base {
      public func g(a: Base) {
          print("2")
      }
  }
  
  func outer() {
      let s: Sub = Sub()
      s.g(Sub()) // Output: 1
  }
  

Operator Overloading

If you want to support operators that are not natively supported by a certain type, you can achieve this through operator overloading.

To overload an operator for a type, you can define a function with the operator’s name for that type. When an instance of this type uses the operator, the corresponding operator function will be automatically called.

The definition of an operator function is similar to that of a regular function, with the following differences:

• The operator modifier must be added before the func keyword when defining an operator function.
• The number of parameters in the operator function must match the requirements of the corresponding operator (see Appendix Operators for details).
• Operator functions can only be defined within class, interface, struct, enum, and extend.
• Operator functions have the semantics of instance member functions, so the static modifier is prohibited.
• Operator functions cannot be generic functions.

Additionally, it’s important to note that overloaded operators do not change their inherent precedence and associativity (see Appendix Operators for details).

Definition and Usage of Operator Overloading Functions

There are two ways to define operator functions:

1. For types that can directly contain function definitions (including struct, enum, class, and interface), operator functions can be defined directly within them to overload operators.
2. Use the extend approach to add operator functions, thereby overloading operators for these types. For types that cannot directly contain function definitions (i.e., types other than struct, class, enum, and interface) or types whose implementations cannot be modified (such as third-party defined struct, class, enum, and interface), this is the only available method (see Extensions).

The conventions for parameter types in operator functions are as follows:

1. For unary operators, the operator function takes no parameters, and there are no requirements on the return type.

2. For binary operators, the operator function takes exactly one parameter, and there are no requirements on the return type.

   The following example demonstrates the definition and usage of unary and binary operators:

   The - operator negates the x and y member variables of a Point instance and returns a new Point object. The + operator sums the x and y member variables of two Point instances and returns a new Point object.

   open class Point {
       var x: Int64 = 0
       var y: Int64 = 0
       public init (a: Int64, b: Int64) {
           x = a
           y = b
       }
   
       public operator func -(): Point {
           Point(-x, -y)
       }
       public operator func +(right: Point): Point {
           Point(this.x + right.x, this.y + right.y)
       }
   }
   

   Now, the unary - operator and binary + operator can be used directly on instances of Point:

   main() {
       let p1 = Point(8, 24)
       let p2 = -p1      // p2 = Point(-8, -24)
       let p3 = p1 + p2  // p3 = Point(0, 0)
   }
   

3. The index operator ([]) has two forms: value retrieval (let a = arr[i]) and value assignment (arr[i] = a). These are distinguished by the presence or absence of a special named parameter value. Overloading the index operator does not require overloading both forms simultaneously; you can overload only the assignment form or only the retrieval form.

   For the value retrieval form of the index operator [], the parameter sequence inside the brackets corresponds to the non-named parameters of the operator overload. There can be one or more parameters of any type. No other named parameters are allowed. The return type can be any type.

   class A {
       operator func [](arg1: Int64, arg2: String): Int64 {
           return 0
       }
   }
   
   func f() {
       let a = A()
       let b: Int64 = a[1, "2"]
       // b == 0
   }
   

   For the value assignment form of the index operator [], the parameter sequence inside the brackets corresponds to the non-named parameters of the operator overload. There can be one or more parameters of any type. The expression on the right side of = corresponds to the named parameter of the operator overload. There must be exactly one named parameter, and its name must be value. It cannot have a default value, and value can be of any type. The return type must be Unit.

   Note that value is just a special marker; you do not need to use named parameter syntax when calling the index operator for assignment.

   class A {
       operator func [](arg1: Int64, arg2: String, value!: Int64): Unit {
           return
       }
   }
   
   func f() {
       let a = A()
       a[1, "2"] = 0
   }
   

   Notably, immutable types (except enum) do not support overloading the assignment form of the index operator.

4. The function call operator (()) overload function can have input parameters and return values of any type. Example:

   open class A {
       public init() {}
   
       public operator func ()(): Unit {}
   }
   
   func test1() {
       let a = A() // OK, A() is call the constructor of A
       a()         // OK, a() is to call the operator () overloading function
   }
   

   You cannot use this or super to call the () operator overload function. Example:

   open class A {
       public init() {}
       public init(x: Int64) {
           this() // OK, this() calls the constructor of A
       }
   
       public operator func ()(): Unit {}
   
       public func foo() {
           this()  // Error, this() calls the constructor of A.
           super() // Error
       }
   }
   
   class B <: A {
       public init() {
           super() // OK, super()  calls the constuctor of the super class
       }
   
       public func goo() {
           super() // Error
       }
   }
   

   For enumeration types, when both the constructor form and the () operator overload function form are applicable, the constructor form takes precedence. Example:

   enum E {
       Y | X | X(Int64)
   
       public operator func ()(p: Int64) {}
       public operator func ()(p: Float64) {}
   }
   
   main() {
       let e = X(1)    // OK, X(1) is to call the constructor X(Int64)
       X(1.0)          // OK, X(1.0) is to call the operator () overloading function
       let e1 = X
       e1(1)           // OK, e1(1) is to call the operator () overloading function
       Y(1)            // OK, Y(1) is to call the operator () overloading function
   }
   

Overloadable Operators

The following table lists all overloadable operators (ordered by precedence from highest to lowest):

Important notes:

Note:

• If any binary operator other than relational operators (<, <=, >, >=, ==, and !=) is overloaded for a type, and the return type of the operator function matches the type of the left operand or is a subtype of it, then the type supports the corresponding compound assignment operator. If the return type does not match the left operand’s type and is not a subtype, using the corresponding compound assignment operator will result in a type mismatch error.

  open class MyClass {
      var x: Int64 = 0
      public init (a: Int64) {
          x = a
      }
  
      public operator func +(right: MyClass): Int64 { // The above rules are not met
          this.x + right.x
      }
  }
  
  main() {
      var a = MyClass(5)
      var b = MyClass(3)
      a += b; // Error, type incompatible in this compound assignment expression
  }
  

• The Cangjie programming language does not support custom operators. Defining operator functions other than those listed in the above table is not allowed.

• For a type T, if T already natively supports certain overloadable operators, attempting to redefine operator functions with the same signature via extension will result in a redefinition error. For example, overloading arithmetic operators, bitwise operators, or relational operators with the same signature for numeric types, overloading relational operators with the same signature for Rune, or overloading logical operators, equality, or inequality operators with the same signature for Bool will all trigger redefinition errors.

  extend Int64 {
      public operator func +(x: Int64, y: Int64): Int64 { // Error, invalid number of parameters for operator '+'
          x + y
      }
  }
  

const Functions and Constant Evaluation

Constant evaluation allows certain forms of expressions to be evaluated at compile time, reducing the computational load required during program execution. This chapter primarily introduces the usage methods and rules of constant evaluation.

const Context and const Expressions

A const context refers to the initialization expression of a const variable, where these expressions are always evaluated at compile time. Therefore, restrictions must be placed on the expressions allowed in const contexts to avoid side effects such as modifying global state or performing I/O operations, ensuring they can be evaluated at compile time.

A const expression possesses the capability to be evaluated at compile time. Expressions that satisfy the following rules are considered const expressions:

1. Literals of numeric types, Bool, Unit, Rune, and String types (excluding interpolated strings).
2. Array literals (not Array type, but VArray type can be used) and tuple literals where all elements are const expressions.
3. const variables, const function parameters, and local variables within const functions.
4. const functions, including functions declared with const, lambda expressions that meet const function requirements, and function expressions returned by these functions.
5. const function calls (including const constructors), where the function expression must be a const expression and all arguments must be const expressions.
6. enum constructor calls where all arguments are const expressions, and parameterless enum constructors.
7. Arithmetic expressions, relational expressions, and bitwise operation expressions of numeric types, Bool, Unit, Rune, and String types, where all operands must be const expressions.
8. if, match, try, throw, return, is, and as expressions, where all internal expressions must be const expressions.
9. Member access of const expressions (excluding property access) and index access of tuple.
10. const init and this and super expressions within const functions.
11. const instance member function calls of const expressions, where all arguments must be const expressions.

Note:

The current compiler implementation does not support using throw as a const expression.

const Functions

const functions are a special category of functions that possess the capability to be evaluated at compile time. When these functions are called in a const context, they are executed during compilation. In other non-const contexts, const functions behave like ordinary functions and are executed at runtime.

The following example demonstrates a const function that calculates the distance between two points on a plane. The distance function uses let to define two local variables, dx and dy:

struct Point {
    const Point(let x: Float64, let y: Float64) {}
}

const func distance(a: Point, b: Point) {
    let dx = a.x - b.x
    let dy = a.y - b.y
    (dx ** 2 + dy ** 2) ** 0.5
}

main() {
    const a = Point(3.0, 0.0)
    const b = Point(0.0, 4.0)
    const d = distance(a, b)
    println(d)
}

Compilation and execution output:

5.000000

Key points to note:

1. const function declarations must be marked with the const modifier.
2. Global const functions and static const functions can only access externally declared const variables, including const global variables and const static member variables. Other external variables are inaccessible. const init functions and const instance member functions can access not only const-declared external variables but also instance member variables of the current type.
3. All expressions within const functions must be const expressions, except for const init functions.
4. const functions can use let and const to declare new local variables but do not support var.
5. There are no special restrictions on the parameter types and return types of const functions. If the arguments of a function call do not meet the requirements of a const expression, the function call cannot be used as a const expression but can still be used as an ordinary expression.
6. const functions are not necessarily executed at compile time; for example, they can be called at runtime within non-const functions.
7. The overloading rules for const functions and non-const functions are consistent.
8. Numeric types, Bool, Unit, Rune, String types, and enum support defining const instance member functions.
9. For struct and class, const instance member functions can only be defined if const init is defined. const instance member functions in class cannot be open. const instance member functions in struct cannot be mut.

Additionally, interfaces can also define const functions, but they are subject to the following rules:

1. For const functions in an interface, the implementing type must also use const functions to satisfy the interface.
2. For non-const functions in an interface, the implementing type can use either const or non-const functions to satisfy the interface.
3. Similar to static functions in interfaces, const functions in interfaces can only be used by generic parameters or variables constrained by the interface when the interface is used as a generic constraint.

In the following example, two const functions are defined in interface I, class A implements interface I, and the generic function g has a type parameter upper-bounded by I.

interface I {
    const func f(): Int64
    const static func f2(): Int64
}

class A <: I {
    public const func f() { 0 }
    public const static func f2() { 1 }
    const init() {}
}

const func g<T>(i: T) where T <: I {
    return i.f() + T.f2()
}

main() {
    println(g(A()))
}

Compiling and executing the above code outputs:

1

const init

If a struct or class defines a const constructor, then instances of that struct/class can be used in const expressions.

1. If the current type is a class, it cannot have instance member variables declared with var; otherwise, defining const init is not allowed. If the current type has a superclass, the const init must call the superclass’s const init (either explicitly or implicitly by calling a parameterless const init). If the superclass does not have a const init, an error is raised.

   public class Foo {
       val a: Int64 = 9 // Error, expected declaration, found 'val'
       let b: String
       const init(b: String) {
           this.b = b
       }
   }
   

   open public class Boo {
       let boo: String
       const init(b: String) {
           this.boo = b
       }
   }
   
   public class Foo <: Boo {
       let c: String
       const init(c: String) { //Error, there is no non-parameter constructor in super class, please invoke super call explicitly
           this.c = c
       }
   }
   

2. If the instance member variables of the current type have initial values, those initial values must be const expressions; otherwise, defining const init is not allowed.

   var a = "4123"
   
   class Foo {
       let foo: String = a // Error, expected 'const' expression guaranteed to be evaluated at compile time
       const init() {}
   }
   

3. Within const init, assignment expressions (=) can be used to assign values to instance member variables, but no other assignment expressions (such as +=, -=) are allowed.

   var a = "4123"
   
   class Foo {
       let foo: String
       let boo: Int64
       const init() {
           foo = "aa" // OK
           boo += 10 // Error, variable 'boo' is used before initialization
       }
   }
   

The difference between const init and const functions is that const init allows assignment to instance member variables (using assignment expressions).

Defining struct Types

The definition of a struct type begins with the keyword struct, followed by the name of the struct, and then the struct body enclosed in a pair of curly braces. The struct body can define a series of member variables, member properties (see Properties), static initializers, constructors, and member functions.

struct Rectangle {
    let width: Int64
    let height: Int64

    public init(width: Int64, height: Int64) {
        this.width = width
        this.height = height
    }

    public func area() {
        width * height
    }
}

The above example defines a struct type named Rectangle, which has two member variables of type Int64: width and height, a constructor with two Int64 parameters (defined using the keyword init, where the function body typically initializes member variables), and a member function area (which returns the product of width and height).

Note:

struct can only be defined at the top-level scope of a source file.

struct Member Variables

struct member variables are divided into instance member variables and static member variables (modified with the static modifier). The difference in access is that instance member variables can only be accessed through struct instances (saying a is an instance of type T means a is a value of type T), while static member variables can only be accessed through the struct type name.

Instance member variables can be defined without an initial value (but the type must be annotated, as in the width and height in the example above), or they can be assigned an initial value, for example:

struct Rectangle {
    let width = 10
    let height = 20
}

struct Static Initializers

struct supports defining static initializers, which initialize static member variables through assignment expressions within the static initializer.

A static initializer begins with the keyword combination static init, followed by a parameterless parameter list and a function body, and cannot be modified by access modifiers. The function body must complete the initialization of all uninitialized static member variables; otherwise, a compilation error will occur.

struct Rectangle {
    static let degree: Int64
    static init() {
        degree = 180
    }
}

A struct can define at most one static initializer; otherwise, a redefinition error will occur.

struct Rectangle {
    static let degree: Int64
    static init() {
        degree = 180
    }
    static init() { // Error, redefinition with the previous static init function
        degree = 180
    }
}

struct Constructors

struct supports two types of constructors: ordinary constructors and primary constructors.

An ordinary constructor begins with the keyword init, followed by a parameter list and a function body. The function body must complete the initialization of all uninitialized instance member variables (if parameter names and member variable names cannot be distinguished, the member variable can be prefixed with this for clarification, where this represents the current instance of the struct); otherwise, a compilation error will occur.

struct Rectangle {
    let width: Int64
    let height: Int64

    public init(width: Int64, height: Int64) { // Error, 'height' is not initialized in the constructor
        this.width = width
    }
}

A struct can define multiple ordinary constructors, but they must constitute overloads (see Function Overloading); otherwise, a redefinition error will occur.

struct Rectangle {
    let width: Int64
    let height: Int64

    public init(width: Int64) {
        this.width = width
        this.height = width
    }

    public init(width: Int64, height: Int64) { // OK: overloading with the first init function
        this.width = width
        this.height = height
    }

    public init(height: Int64) { // Error, redefinition with the first init function
        this.width = height
        this.height = height
    }
}

In addition to defining ordinary constructors named init, a struct can also define (at most) one primary constructor. The primary constructor has the same name as the struct type, and its parameter list can include two types of parameters: ordinary parameters and member variable parameters (prefixed with let or var). Member variable parameters serve the dual purpose of defining member variables and acting as constructor parameters.

Using a primary constructor can often simplify the definition of a struct. For example, the above Rectangle with an init constructor can be simplified as follows:

struct Rectangle {
    public Rectangle(let width: Int64, let height: Int64) {}
}

The primary constructor’s parameter list can also include ordinary parameters, for example:

struct Rectangle {
    public Rectangle(name: String, let width: Int64, let height: Int64) {}
}

If a struct definition does not include any custom constructors (including primary constructors) and all instance member variables have initial values, an automatic parameterless constructor will be generated (calling this constructor creates an object where all instance member variables are initialized to their default values); otherwise, this parameterless constructor will not be generated. For example, for the following struct definition, the automatically generated parameterless constructor is shown in the comments:

struct Rectangle {
    let width: Int64 = 10
    let height: Int64 = 10
    /* Auto-generated memberwise constructor:
    public init() {
    }
    */
}

struct Member Functions

struct member functions are divided into instance member functions and static member functions (modified with the static modifier). The differences are:

• Instance member functions can only be accessed through struct instances, while static member functions can only be accessed through the struct type name.
• Static member functions cannot access instance member variables or call instance member functions, but instance member functions can access static member variables and call static member functions.

In the following example, area is an instance member function, and typeName is a static member function.

struct Rectangle {
    let width: Int64 = 10
    let height: Int64 = 20

    public func area() {
        this.width * this.height
    }

    public static func typeName(): String {
        "Rectangle"
    }
}

Instance member functions can access instance member variables via this, for example:

struct Rectangle {
    let width: Int64 = 1
    let height: Int64 = 1

    public func area() {
        this.width * this.height
    }
}

Access Modifiers for struct Members

struct members (including member variables, member properties, constructors, member functions, and operator functions (see Operator Overloading)) can be modified with four access modifiers: private, internal, protected, and public. The default modifier is internal.

• private: Visible only within the struct definition.
• internal: Visible only within the current package and sub-packages (including sub-packages of sub-packages, see Packages).
• protected: Visible within the current module (see Packages).
• public: Visible both inside and outside the module.

In the following example, width is a public member and can be accessed outside the class, height has the default access modifier and is only visible within the current package and sub-packages (other packages cannot access it).

package a
public struct Rectangle {
    public var width: Int64
    var height: Int64
    private var area: Int64

    public init(width: Int64, height: Int64, area: Int64) {
        this.width = width
        this.height = height
        this.area = area
    }
}

func samePkgFunc() {
    var r = Rectangle(10, 20, 40)
    r.width = 8               // OK: public 'width' can be accessed here
    r.height = 24             // OK: 'height' has no modifier and can be accessed here
    r.area = 30               // Error, private 'area' can't be accessed here
}

package b
import a.*

main() {
    r.width = 8     // OK: public 'width' can be accessed here
    r.height = 24   // Error, no modifier 'height' can't be accessed here
    r.area = 30     // Error, private 'area' can't be accessed here
}

Prohibiting Recursive structs

Recursive and mutually recursive struct definitions are illegal. For example:

struct R1 { // Error, 'R1' recursively references itself
    let other: R1
}
struct R2 { // Error, 'R2' and 'R3' are mutually recursive
    let other: R3
}
struct R3 { // Error, 'R2' and 'R3' are mutually recursive
    let other: R2
}

Creating struct Instances

After defining a struct type, you can create struct instances by calling the struct’s constructor. Outside the struct definition, you create an instance of the type by calling the constructor with the struct type name, and you can access instance member variables and instance member functions that satisfy visibility modifiers (such as public) through the instance. For example, in the following code, a variable r of type Rectangle is defined. You can access the values of width and height in r through r.width and r.height, respectively, and call the member function area of r through r.area().

struct Rectangle {
    public var width: Int64
    public var height: Int64

    public init(width: Int64, height: Int64) {
        this.width = width
        this.height = height
    }

    public func area() {
        width * height
    }
}
let r = Rectangle(10, 20)
let width = r.width   // width = 10
let height = r.height // height = 20
let a = r.area()      // a = 200

If you want to modify the values of member variables through a struct instance, you need to define the struct variable as mutable, and the member variable being modified must also be mutable (defined with var). Here’s an example:

struct Rectangle {
    public var width: Int64
    public var height: Int64

    public init(width: Int64, height: Int64) {
        this.width = width
        this.height = height
    }

    public func area() {
        width * height
    }
}

main() {
    var r = Rectangle(10, 20) // r.width = 10, r.height = 20
    r.width = 8               // r.width = 8
    r.height = 24             // r.height = 24
    let a = r.area()          // a = 192
}

During assignment or parameter passing, a struct instance is copied (for reference-type member variables, only the reference is copied, not the referenced object), generating a new instance. Modifying one instance does not affect the other. For example, in the following code, after assigning r1 to r2, modifying the width and height values of r1 does not affect the width and height values of r2.

struct Rectangle {
    public var width: Int64
    public var height: Int64

    public init(width: Int64, height: Int64) {
        this.width = width
        this.height = height
    }

    public func area() {
        width * height
    }
}

main() {
    var r1 = Rectangle(10, 20) // r1.width = 10, r1.height = 20
    var r2 = r1                // r2.width = 10, r2.height = 20
    r1.width = 8               // r1.width = 8
    r1.height = 24             // r1.height = 24
    let a1 = r1.area()         // a1 = 192
    let a2 = r2.area()         // a2 = 200
}

mut Functions

The struct type is a value type, and its instance member functions cannot modify the instance itself. For example, in the following case, the member function g cannot modify the value of member variable i.

struct Foo {
    var i = 0

    public func g() {
        i += 1  // Error, the value of a instance member variable cannot be modified in an instance member function
    }
}

A mut function is a special instance member function that can modify the struct instance itself. Inside a mut function, the semantics of this are special—this this has the capability to modify fields in-place.

Note:

mut functions can only be defined within interfaces, structs, and struct extensions (classes are reference types, and their instance member functions can modify instance member variables without requiring mut, so defining mut functions in classes is prohibited).

Definition of mut Functions

Compared to ordinary instance member functions, mut functions are distinguished by an additional mut keyword modifier.

For example, in the following case, adding the mut modifier before function g allows modification of member variable i within the function body.

struct Foo {
    var i = 0

    public mut func g() {
        i += 1  // OK
    }
}

mut can only modify instance member functions and cannot modify static member functions.

struct A {
    public mut func f(): Unit {} // OK
    public mut operator func +(rhs: A): A { // OK
        A()
    }
    public mut static func g(): Unit {} // Error, static member functions cannot be modified with 'mut'
}

In mut functions, this cannot be captured or used as an expression. Lambdas or nested functions within mut functions cannot capture instance member variables of the struct.

Example:

struct Foo {
    var i = 0

    public mut func f(): Foo {
        let f1 = { => this } // Error, 'this' in mut functions cannot be captured
        let f2 = { => this.i = 2 } // Error, instance member variables in mut functions cannot be captured
        let f3 = { => this.i } // Error, instance member variables in mut functions cannot be captured
        let f4 = { => i } // Error, instance member variables in mut functions cannot be captured
        this // Error, 'this' in mut functions cannot be used as expressions
    }
}

mut Functions in Interfaces

Instance member functions in interfaces can also be modified with mut.

When a struct type implements functions from an interface, it must maintain the same mut modifier. Types other than struct cannot use the mut modifier when implementing interface functions.

Example:

interface I {
    mut func f1(): Unit
    func f2(): Unit
}

struct A <: I {
    public mut func f1(): Unit {} // OK: as in the interface, the 'mut' modifier is used
    public func f2(): Unit {} // OK: as in the interface, the 'mut' modifier is not used
}

struct B <: I {
    public func f1(): Unit {} // Error, 'f1' is modified with 'mut' in interface, but not in struct
    public mut func f2(): Unit {} // Error, 'f2' is not modified with 'mut' in interface, but did in struct
}

class C <: I {
    public func f1(): Unit {} // OK
    public func f2(): Unit {} // OK
}

When a struct instance is assigned to an interface type, it follows copy semantics. Therefore, the mut function of the interface cannot modify the value of the struct instance.

Example:

interface I {
    mut func f(): Unit
}
struct Foo <: I {
    public var v = 0
    public mut func f(): Unit {
        v += 1
    }
}
main() {
    var a = Foo()
    var b: I = a  
    b.f()  // Calling 'f' via 'b' cannot modify the value of 'a'
    println(a.v) // 0
}

The program output is:

0

Usage Restrictions of mut Functions

Because struct is a value type, if a variable is of struct type and declared with let, the mut functions of that type cannot be accessed via this variable.

Example:

interface I {
    mut func f(): Unit
}
struct Foo <: I {
    public var i = 0
    public mut func f(): Unit {
        i += 1
    }
}
main() {
    let a = Foo()
    a.f() // Error, 'a' is of type struct and is declared with 'let', the 'mut' function cannot be accessed via 'a'
    var b = Foo()
    b.f() // OK
    let c: I = Foo()
    c.f() // OK, variable 'c' is of interface type I, not struct type, so access is permitted here.
}

To prevent escape, if a variable is of struct type, it cannot use mut functions as first-class citizens; it can only call these mut functions.

Example:

interface I {
    mut func f(): Unit
}

struct Foo <: I {
    var i = 0

    public mut func f(): Unit {
        i += 1
    }
}

main() {
    var a = Foo()
    var fn = a.f // Error, mut function 'f' of 'a' cannot be used as a first class citizen.
    var b: I = Foo()
    fn = b.f // OK
}

To prevent escape, non-mut instance member functions (including lambda expressions) cannot directly access mut functions of their containing type, but the reverse is allowed.

Example:

struct Foo {
    var i = 0

    public mut func f(): Unit {
        i += 1
        g() // OK
    }

    public func g(): Unit {
        f() // Error, mut functions cannot be invoked in non-mut functions
    }
}

interface I {
    mut func f(): Unit {
        g() // OK
    }

    func g(): Unit {
        f() // Error, mut functions cannot be invoked in non-mut functions
    }
}

Enum Types

This section introduces the enum type in Cangjie. The enum type provides a way to define a type by enumerating all its possible values.

Many programming languages have enum types (or enumerated types), but their usage and expressive power vary across languages. In Cangjie, the enum type can be understood as algebraic data types (Algebraic Data Types) in functional programming languages.

Definition of enum

When defining an enum, all its possible values must be explicitly listed. These values are called constructors (or constructors) of the enum.

An enum type definition starts with the keyword enum, followed by the name of the enum, and then the enum body enclosed in curly braces. The enum body defines several constructors, separated by | (the | before the first constructor is optional). Constructors can be named or unnamed (...).

Each enum must contain at least one named constructor. Named constructors can be parameterless (i.e., “no-argument constructors”) or carry several parameters (i.e., “parameterized constructors”). The following example defines an enum type named RGBColor with three constructors: Red, Green, and Blue, representing the red, green, and blue components in the RGB color model. Each constructor has a UInt8 parameter representing the brightness level of each color.

enum RGBColor {
    | Red(UInt8) | Green(UInt8) | Blue(UInt8)
}

Cangjie supports defining multiple constructors with the same name in the same enum, but these constructors must have different numbers of parameters (a parameterless constructor is considered to have 0 parameters). For example:

enum RGBColor {
    | Red | Green | Blue
    | Red(UInt8) | Green(UInt8) | Blue(UInt8)
}

Each enum can have at most one unnamed ... constructor, and ... must be the last constructor. An enum with a ... constructor is called a non-exhaustive enum. Since it has no name, this constructor cannot be directly matched. During destructuring, patterns that match all constructors must be used, such as the wildcard pattern _ or binding patterns. For details, refer to Definition of match expressions. For example:

enum T {
    | Red | Green | Blue | ...
}

enum supports recursive definitions. For example, the following example uses enum to define an expression type (Expr), which can only have three forms: a single number Num (with an Int64 parameter), an addition expression Add (with two Expr parameters), or a subtraction expression Sub (with two Expr parameters). For the Add and Sub constructors, their parameters recursively reference Expr itself.

enum Expr {
    | Num(Int64)
    | Add(Expr, Expr)
    | Sub(Expr, Expr)
}

Additionally, the enum body can define a series of member functions, operator functions (see Operator Overloading), and member properties (see Properties). However, constructors, member functions, and member properties must not share the same name. For example, the following example defines a function named printType in RGBColor, which outputs the string RGBColor:

enum RGBColor {
    | Red | Green | Blue

    public static func printType() {
        print("RGBColor")
    }
}

Note:

enum can only be defined at the top-level scope of a source file.

Usage of enum

After defining an enum type, you can create instances of this type (i.e., enum values). An enum value can only take one of the constructors defined in the enum type. enum does not have constructors; you can create an enum value using TypeName.Constructor or directly using the constructor (for parameterized constructors, arguments must be provided).

In the following example, RGBColor defines three constructors: two parameterless constructors (Red and Green) and one parameterized constructor (Blue(UInt8)). The main function defines three RGBColor variables r, g, and b. r is initialized with RGBColor.Red, g is initialized directly with Green, and b is initialized with Blue(100):

enum RGBColor {
    | Red | Green | Blue(UInt8)
}

main() {
    let r = RGBColor.Red
    let g = Green
    let b = Blue(100)
}

When the type name is omitted, the name of an enum constructor may conflict with type names, variable names, or function names. In such cases, the enum type name must be prefixed to use the constructor; otherwise, the system will choose the definition with the same name (type, variable, or function).

In the following example, only the constructor Blue(UInt8) can be used without the type name. Red and Green(UInt8) cannot be used directly due to name conflicts and must be prefixed with the type name RGBColor.

let Red = 1

func Green(g: UInt8) {
    return g
}

enum RGBColor {
    | Red | Green(UInt8) | Blue(UInt8)
}

let r1 = Red                 // Will choose 'let Red'
let r2 = RGBColor.Red        // OK: constructed by enum type name

let g1 = Green(100)          // Will choose 'func Green'
let g2 = RGBColor.Green(100) // OK: constructed by enum type name

let b = Blue(100)            // OK: can be uniquely identified as an enum constructor

In the following example, only the constructor Blue cannot be used directly due to a name conflict and must be prefixed with the type name RGBColor.

class Blue {}

enum RGBColor {
    | Red | Green(UInt8) | Blue(UInt8)
}

let r = Red                 // OK: constructed by enum type name

let g = Green(100)          // OK: constructed by enum type name

let b = Blue(100)           // Will choose constructor of 'class Blue' and report an error

The Option Type

The Option type is defined using an enum with two constructors: Some and None. The Some variant carries a parameter indicating a value is present, while None takes no parameters and represents the absence of a value. The Option type is used when you need to represent that a value of a certain type may or may not exist.

The Option type is defined as a generic enum as follows (note that the angle brackets contain a type parameter T. When T is instantiated with different types, different Option types are produced. For detailed information about generics, refer to Generics):

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

Here, the parameter type of the Some constructor is the type parameter T. When T is instantiated with different types, different Option types are obtained, such as Option<Int64>, Option<String>, etc.

There is also a shorthand notation for the Option type: prefixing the type name with ?. That is, for any type Ty, ?Ty is equivalent to Option<Ty>. For example, ?Int64 is equivalent to Option<Int64>, ?String is equivalent to Option<String>, and so on.

The following examples demonstrate how to define variables of the Option type:

let a: Option<Int64> = Some(100)
let b: ?Int64 = Some(100)
let c: Option<String> = Some("Hello")
let d: ?String = None

Additionally, although T and Option<T> are different types, when it is explicitly known that an Option<T> value is required in a certain context, you can directly pass a value of type T. The compiler will automatically wrap the T value into an Option<T> using the Some constructor (note: this is not a type conversion). For example, the following definitions are legal (equivalent to the definitions of variables a, b, and c in the previous example):

let a: Option<Int64> = 100
let b: ?Int64 = 100
let c: Option<String> = "100"

When there is no explicit type requirement in the context, you cannot use None directly to construct the desired type. In such cases, you should use the None<T> syntax to construct an Option<T> value, for example:

let a = None<Int64> // a: Option<Int64>
let b = None<Bool> // b: Option<Bool>

Finally, for usage of Option, refer to Using Option.

Pattern Overview

For match expressions containing matching values, the patterns supported after case determine the expressive power of the match expression. This section introduces the patterns supported by Cangjie in sequence, including: constant patterns, wildcard patterns, binding patterns, tuple patterns, type patterns, and enum patterns.

Constant Pattern

A constant pattern can be an integer literal, floating-point literal, character literal, boolean literal, string literal (string interpolation is not supported), or Unit literal.

When using a constant pattern in a match expression containing matching values (refer to match expression), the type of the value represented by the constant pattern must be the same as the type of the value to be matched. The matching succeeds if the value to be matched is equal to the value represented by the constant pattern.

In the following example, based on the value of score (assuming score can only take values between 0 and 100 divisible by 10), the grade of the exam score is output:

main() {
    let score = 90
    let level = match (score) {
        case 0 | 10 | 20 | 30 | 40 | 50 => "D"
        case 60 => "C"
        case 70 | 80 => "B"
        case 90 | 100 => "A" // Matched.
        case _ => "Not a valid score"
    }
    println(level)
}

Compiling and executing the above code outputs:

A

• When the target of pattern matching is a value with static type Rune, both Rune literals and single-character string literals can be used to represent constant patterns of Rune type literals.

  func translate(n: Rune) {
      match (n) {
          case "A" => 1
          case "B" => 2
          case "C" => 3
          case _ => -1
      }
  }
  
  main() {
      println(translate(r"C"))
  }
  

  Compiling and executing the above code outputs:

  3
  

• When the target of pattern matching is a value with static type Byte, a string literal representing an ASCII character can be used to represent constant patterns of Byte type literals.

  func translate(n: Byte) {
      match (n) {
          case "1" => 1
          case "2" => 2
          case "3" => 3
          case _ => -1
      }
  }
  
  main() {
      println(translate(51)) // UInt32(r'3') == 51
  }
  

  Compiling and executing the above code outputs:

  3
  

Wildcard Pattern

The wildcard pattern is represented by an underscore _ and can match any value. The wildcard pattern is typically used as the pattern in the last case to cover situations not matched by other cases. For example, in the constant pattern example matching score values, the last case uses _ to match invalid score values.

Binding Pattern

The binding pattern is represented by id, where id is a valid identifier. Compared to the wildcard pattern, the binding pattern can also match any value, but it binds the matched value to id, allowing access to the bound value via id after =>.

In the following example, the last case uses a binding pattern. Here, the variable n is an id identifier used to bind non-0 values:

main() {
    let x = -10
    let y = match (x) {
        case 0 => "zero"
        case n => "x is not zero and x = ${n}" // Matched.
    }
    println(y)
}

Compiling and executing the above code outputs:

x is not zero and x = -10

When using | to connect multiple patterns, binding patterns cannot be used, nor can they be nested within other patterns, otherwise an error will occur:

main() {
    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 '|'
    }
}

The binding pattern id is equivalent to defining a new immutable variable named id (its scope starts from the introduction point to the end of the case), so id cannot be modified after =>. For example, modifying n in the last case of the following example is not allowed.

main() {
    let x = -10
    let y = match (x) {
        case 0 => "zero"
        case n => n = n + 0 // Error, 'n' cannot be modified.
                  "x is not zero"
    }
    println(y)
}

For each case branch, the variable scope level after => is the same as the variable scope level introduced before => in the case. Introducing the same name again after => will trigger a redefinition error. For example:

main() {
    let x = -10
    let y = match (x) {
        case 0 => "zero"
        case n => let n = 0 // Error, redefinition
                  println(n)
                  "x is not zero"
    }
    println(y)
}

Note:

When the identifier of a pattern is an enum constructor, the pattern will be treated as an enum pattern for matching, not a binding pattern (for details on enum patterns, see the enum pattern section).

enum RGBColor {
    | Red | Green | Blue
}

main() {
    let x = Red
    let y = match (x) {
        case Red => "red" // The 'Red' is enum mode here.
        case _ => "not red"
    }
    println(y)
}

Compiling and executing the above code outputs:

red

Tuple Pattern

The tuple pattern is used to match tuple values. Its definition is similar to tuple literals: (p_1, p_2, ..., p_n), where p_1 to p_n (n ≥ 2) are patterns (which can be any pattern introduced in this section, with multiple patterns separated by commas) rather than expressions.

For example, (1, 2, 3) is a tuple pattern containing three constant patterns, and (x, y, _) is a tuple pattern containing two binding patterns and one wildcard pattern.

Given a tuple value tv and a tuple pattern tp, tp matches tv if and only if each position value in tv matches the corresponding position pattern in tp. For example, (1, 2, 3) can only match the tuple value (1, 2, 3), while (x, y, _) can match any triple tuple value.

The following example demonstrates the use of tuple patterns:

main() {
    let tv = ("Alice", 24)
    let s = match (tv) {
        case ("Bob", age) => "Bob is ${age} years old"
        case ("Alice", age) => "Alice is ${age} years old" // Matched, "Alice" is a constant pattern, and 'age' is a variable pattern.
        case (name, 100) => "${name} is 100 years old"
        case (_, _) => "someone"
    }
    println(s)
}

Compiling and executing the above code outputs:

Alice is 24 years old

The same tuple pattern cannot introduce multiple binding patterns with the same name. For example, case (x, x) in the last case of the following example is invalid.

main() {
    let tv = ("Alice", 24)
    let s = match (tv) {
        case ("Bob", age) => "Bob is ${age} years old"
        case ("Alice", age) => "Alice is ${age} years old"
        case (name, 100) => "${name} is 100 years old"
        case (x, x) => "someone" // Error, Cannot introduce a variable pattern with the same name, which will be a redefinition error.
    }
    println(s)
}

Type Pattern

The type pattern is used to determine whether the runtime type of a value is a subtype of a certain type. There are two forms of type patterns: _: Type (nesting a wildcard pattern _) and id: Type (nesting a binding pattern id). The difference is that the latter performs variable binding, while the former does not.

For a value v to be matched and a type pattern id: Type (or _: Type), first determine whether the runtime type of v is a subtype of Type. If true, the match is successful; otherwise, it fails. If the match succeeds, the type of v is converted to Type and bound to id (for _: Type, there is no binding operation).

Assume the following two classes, Base and Derived, where Derived is a subclass of Base. The parameterless constructor of Base sets the value of a to 10, and the parameterless constructor of Derived sets the value of a to 20:

open class Base {
    var a: Int64
    public init() {
        a = 10
    }
}

class Derived <: Base {
    public init() {
        a = 20
    }
}

The following code demonstrates a successful type pattern match:

func test1() {
    var d = Derived()
    var r = match (d) {
        case b: Base => b.a // Matched.
        case _ => 0
    }
    println("r = ${r}")
}

The following code demonstrates a failed type pattern match:

func test2() {
    var b = Base()
    var r = match (b) {
        case d: Derived => d.a  // Type pattern match failed.
        case _ => 0             // Matched.
    }
    println("r = ${r}")
}

main() {
    test1()
    test2()
}

Compiling and executing the above code yields the following output (the first line is the output of test1, and the second line is the output of test2):

r = 20
r = 0

Enum Pattern

The enum pattern is used to match instances of enum types. Its definition resembles the constructor of an enum: a no-argument constructor C or a parameterized constructor C(p_1, p_2, ..., p_n). The type prefix of the constructor can be omitted. The difference lies in the fact that p_1 to p_n (where n ≥ 1) here are patterns. For example, Some(1) is an enum pattern containing a constant pattern, while Some(x) is an enum pattern containing a binding pattern.

Given an enum instance ev and an enum pattern ep, ep is said to match ev if and only if the constructor name of ev is the same as that of ep, and each value in the parameter list of ev matches the corresponding pattern in ep. For example, Some("one") can only match the Some constructor of type Option<String>, i.e., Option<String>.Some("one"), while Some(x) can match any Some constructor of the Option type.

In the following example, the use of an enum pattern is demonstrated. Since the constructor of x is Year, it will match the first case:

enum TimeUnit {
    | Year(UInt64)
    | Month(UInt64)
}

main() {
    let x = Year(2)
    let s = match (x) {
        case Year(n) => "x has ${n * 12} months" // Matched.
        case TimeUnit.Month(n) => "x has ${n} months"
    }
    println(s)
}

Compiling and executing the above code yields the following output:

x has 24 months

When multiple enum patterns are connected using |, each pattern must be independent and cannot introduce new variables. This is because | represents an “or” relationship, and variable introduction requires explicit context, which cannot be shared across multiple patterns. The following example demonstrates a counterexample where the fifth and sixth case statements violate this rule:

enum TimeUnit {
    | Year(UInt64)
    | Month(UInt64)
}

main() {
    let x = Year(2)
    let s = match (x) {
        case Year(5) => "1:OK"
        case Month(m) => "2:OK"
        case Year(0) | Year(1) | Month(_) => "3:OK"
        case Year(_) => "4:OK"
        case Year(2) | Month(m) => "5:invalid" // Error, Variable cannot be introduced in patterns connected by '|'
        case Year(n: UInt64) | Month(n: UInt64) => "6:invalid" // Error, Variable cannot be introduced in patterns connected by '|'
    }
    println(s)
}

In the above example, the second case introduces a new variable m but does not connect it with other patterns using |, making it valid.

When using a match expression to match enum values, the patterns following case must cover all constructors of the enum type being matched. If not fully covered, the compiler will report an error:

enum RGBColor {
    | Red | Green | Blue
}

main() {
    let c = Green
    let cs = match (c) { // Error, Not all constructors of RGBColor are covered.
        case Red => "Red"
        case Green => "Green"
    }
    println(cs)
}

Full coverage can be achieved by adding case Blue or by using case _ at the end of the match expression to cover cases not handled by other case statements, as shown below:

enum RGBColor {
    | Red | Green | Blue
}

main() {
    let c = Blue
    let cs = match (c) {
        case Red => "Red"
        case Green => "Green"
        case _ => "Other" // Matched.
    }
    println(cs)
}

The execution result of the above code is:

Other

Nested Combination of Patterns

Tuple patterns and enum patterns can nest arbitrary patterns. The following code demonstrates the nested combination of different patterns:

enum TimeUnit {
    | Year(UInt64)
    | Month(UInt64)
}

enum Command {
    | SetTimeUnit(TimeUnit)
    | GetTimeUnit
    | Quit
}

main() {
    let command = (SetTimeUnit(Year(2022)), SetTimeUnit(Year(2024)))
    match (command) {
        case (SetTimeUnit(Year(year)), _) => println("Set year ${year}")
        case (_, SetTimeUnit(Month(month))) => println("Set month ${month}")
        case _ => ()
    }
}

Compiling and executing the above code yields the following output:

Set year 2022

Pattern Refutability

Patterns can be divided into two categories: refutable patterns and irrefutable patterns. Under the premise of type matching, when a pattern may fail to match the value being matched, it is called a refutable pattern; conversely, when a pattern can always match the value being matched, it is called an irrefutable pattern.

For the various patterns introduced above, the following rules apply:

Constant patterns are refutable patterns. For example, in the following example, both 1 in the first case and 2 in the second case may not equal the value of x.

func constPat(x: Int64) {
    match (x) {
        case 1 => "one"
        case 2 => "two"
        case _ => "_"
    }
}

Wildcard patterns are irrefutable patterns. For example, in the following example, no matter what the value of x is, _ will always match it.

func wildcardPat(x: Int64) {
    match (x) {
        case _ => "_"
    }
}

Binding patterns are irrefutable patterns. For example, in the following example, no matter what the value of x is, the binding pattern a will always match it.

func varPat(x: Int64) {
    match (x) {
        case a => "x = ${a}"
    }
}

Tuple patterns are irrefutable patterns if and only if every pattern they contain is an irrefutable pattern. For example, in the following example, both (1, 2) and (a, 2) may fail to match the value of x, so they are refutable patterns, whereas (a, b) can match any value of x, so it is an irrefutable pattern.

func tuplePat(x: (Int64, Int64)) {
    match (x) {
        case (1, 2) => "(1, 2)"
        case (a, 2) => "(${a}, 2)"
        case (a, b) => "(${a}, ${b})"
    }
}

Type patterns are refutable patterns. For example, in the following example (assuming Base is the parent class of Derived, and Base implements the interface I), the runtime type of x may be neither Base nor Derived, so both a: Derived and b: Base are refutable patterns.

interface I {}
open class Base <: I {}
class Derived <: Base {}

func typePat(x: I) {
    match (x) {
        case a: Derived => "Derived"
        case b: Base => "Base"
        case _ => "Other"
    }
}

Enum patterns are irrefutable patterns if and only if the corresponding enum type has only one parameterized constructor, and the other patterns contained in the enum pattern are also irrefutable patterns. For example, for the definitions of E1 and E2 in the following example, A(1) in the function enumPat1 is a refutable pattern, while A(a) is an irrefutable pattern; whereas in the function enumPat2, both B(b) and C(c) are refutable patterns.

enum E1 {
    A(Int64)
}

enum E2 {
    B(Int64) | C(Int64)
}

func enumPat1(x: E1) {
    match (x) {
        case A(1) => "A(1)"
        case A(a) => "A(${a})"
    }
}

func enumPat2(x: E2) {
    match (x) {
        case B(b) => "B(${b})"
        case C(c) => "C(${c})"
    }
}

Match Expressions

Definition of Match Expressions

Cangjie supports two types of match expressions: the first is a match expression containing a value to be matched, and the second is a match expression without a value to be matched.

Match Expression with Matching Value:

main() {
    let x = 0
    match (x) {
        case 1 => let r1 = "x = 1"
                  print(r1)
        case 0 => let r2 = "x = 0" // Matched.
                  print(r2)
        case _ => let r3 = "x != 1 and x != 0"
                  print(r3)
    }
}

The match expression starts with the keyword match, followed by the value to be matched, such as x in the example above. x can be any expression. This is followed by several case branches enclosed in curly braces. Each case branch starts with the keyword case, followed by a pattern or multiple patterns of the same kind connected by |. In the example above, 1, 0, and _ are all patterns. For details, see the Pattern Overview chapter. After the pattern comes =>, followed by the operation to be executed when the case branch matches successfully. This can be a series of expressions, variable definitions, or function definitions. The scope of newly defined variables or functions starts from their definition point and ends before the next case. For example, the variable definitions and print function calls in the example above.

In the example above, since the value of x is equal to 0, it matches the second case branch (here, a constant pattern is used, which matches whether the values are equal. For details, see the Constant Pattern chapter). Finally, it outputs x = 0.

Compile and execute the above code, and the output result is:

x = 0

The match expression requires that all matches must be exhaustive, meaning all possible values of the expression to be matched should be considered. When the match expression is not exhaustive, or the compiler cannot determine whether it is exhaustive, a compilation error will occur. In other words, the union of the value ranges covered by all case branches (including pattern guards) should include all possible values of the expression to be matched. A common way to ensure the exhaustiveness of the match expression is to use the wildcard pattern _ in the last case branch, as _ can match any value.

The exhaustiveness of the match expression ensures that there must be a case branch that matches the value to be matched. The following example will result in a compilation error because not all possible values of x are covered by the case branches:

func nonExhaustive(x: Int64) {
    match (x) {
        case 0 => print("x = 0")
        case 1 => print("x = 1")
        case 2 => print("x = 2")
    }
}

If the type of the matched value includes an enum type and the enum is a non-exhaustive enum, then when matching, a pattern that can match all constructors must be used, such as the wildcard pattern _ or a binding pattern.

enum T {
    | Red | Green | Blue | ...
}
func foo(a: T) {
    match (a) {
        case Red => 0
        case Green => 1
        case Blue => 2
        case _ => -1
    }
}

func bar(a: T) {
    match (a) {
        case Red => 0
        case k => -1 // simple binding pattern
    }
}

func baz(a: T) {
    match (a) {
        case Red => 0
        case k: T => -1 // binding pattern with nested type pattern
    }
}

After the pattern in the case branch, a pattern guard can be used to further judge the matching result. This is optional.

• pattern guard represents an additional condition that must be satisfied after the case matches successfully. It is expressed using where cond (syntax format), requiring the type of the expression cond to be Bool.

When the match expression is executed, the expression after match is sequentially matched with each pattern in the case. If there is a pattern guard, the expression after where must evaluate to true; if there are multiple patterns in the case connected by |, as long as the value to be matched matches one of the patterns, it is considered a successful match. Once a match is successful, the code after => is executed, and then the execution of the match expression is exited, meaning that subsequent case branches will not be matched. If the match is unsuccessful, it will continue to match with the patterns in subsequent case branches until a match is successful. The match expression guarantees that there must be a case branch that matches.

In the following example, an enum pattern is used. For details, see the Enum Pattern chapter. When the parameter value of the RGBColor constructor is greater than or equal to 0, their values are output; when the parameter value is less than 0, meaning the where cond of the first case is satisfied, their values are considered to be 0:

enum RGBColor {
    | Red(Int16) | Green(Int16) | Blue(Int16)
}
main() {
    let c = RGBColor.Green(-100)
    let cs = match (c) {
        case Red(r) where r < 0 => "Red = 0"
        case Red(r) => "Red = ${r}"
        case Green(g) where g < 0 => "Green = 0" // Matched.
        case Green(g) => "Green = ${g}"
        case Blue(b) where b < 0 => "Blue = 0"
        case Blue(b) => "Blue = ${b}"
    }
    print(cs)
}

Compile and execute the above code, and the output result is:

Green = 0

Match Expression Without Matching Value:

main() {
    let x = -1
    match {
        case x > 0 => print("x > 0")
        case x < 0 => print("x < 0") // Matched.
        case _ => print("x = 0")
    }
}

Compared to the match expression with a value to be matched, there is no expression to be matched after the keyword match, and what follows case is no longer a pattern, but an expression of type Bool (such as x > 0 and x < 0 in the above code) or _ (representing true). Of course, there is no pattern guard in the case either.

When the match expression without a matching value is executed, the expressions after case are evaluated in sequence until a case branch with an expression value of true is encountered. Once the expression value after a case equals true, the code after => in this case is executed, and then the execution of the match expression is exited (meaning that subsequent case branches will not be evaluated).

In the example above, since the value of x is -1, the expression in the second case branch (i.e., x < 0) evaluates to true, and print("x < 0") is executed.

Compile and execute the above code, and the output result is:

x < 0

Types of Match Expressions

For match expressions (whether with or without a matching value):

• When there is a clear type requirement in the context, the type of the code block after => in each case branch must be a subtype of the type required by the context;

• When there is no clear type requirement in the context, the type of the match expression is the least common parent type of the types of the code blocks after => in each case branch;

• When the value of the match expression is not used, its type is Unit, and there is no requirement for the least common parent type of the types of each branch.

The following examples illustrate these points.

let x = 2
let s: String = match (x) {
    case 0 => "x = 0"
    case 1 => "x = 1"
    case _ => "x != 0 and x != 1" // Matched.
}

In the example above, when defining the variable s, its type is explicitly annotated as String, which is a case where the context type information is clear. Therefore, the type of the code block after => in each case must be a subtype of String. Clearly, the string literals after => in the example meet this requirement.

Here is another example without context type information:

let x = 2
let s = match (x) {
    case 0 => "x = 0"
    case 1 => "x = 1"
    case _ => "x != 0 and x != 1" // Matched.
}

In the example above, when defining the variable s, its type is not explicitly annotated. Since the type of the code block after => in each case is String, the type of the match expression is String, and thus the type of s can be determined to be String.

Other Usage Scenarios of Patterns

Patterns can be used not only in match expressions but also in variable definitions and for in expressions. For example, the left side of an equals sign is a pattern, and the part between the for keyword and the in keyword is also a pattern. Additionally, conditions in if expressions and while expressions can utilize patterns. For specific examples, refer to the “Conditions Involving let-pattern” section.

However, not all patterns can be used in variable definitions and for in expressions. Only irrefutable patterns are permitted in these contexts. Therefore, only wildcard patterns, binding patterns, irrefutable tuple patterns, and irrefutable enum patterns are allowed.

1. Examples of using wildcard patterns in variable definitions and for in expressions:

   main() {
       let _ = 100
       for (_ in 1..5) {
           println("0")
       }
   }
   

   In the above example, a wildcard pattern is used in the variable definition, indicating the creation of a nameless variable (which consequently cannot be accessed later). The for in expression uses a wildcard pattern, meaning elements from 1..5 won’t be bound to any variable (thus their values cannot be accessed within the loop body). Compiling and executing this code yields:

   0
   0
   0
   0
   

2. Examples of using binding patterns in variable definitions and for in expressions:

   main() {
       let x = 100
       println("x = ${x}")
       for (i in 1..5) {
           println(i)
       }
   }
   

   Here, x in the variable definition and i in the for in expression are both binding patterns. Compiling and executing this code yields:

   x = 100
   1
   2
   3
   4
   

3. Examples of using irrefutable tuple patterns in variable definitions and for in expressions:

   main() {
       let (x, y) = (100, 200)
       println("x = ${x}")
       println("y = ${y}")
       for ((i, j) in [(1, 2), (3, 4), (5, 6)]) {
           println("Sum = ${i + j}")
       }
   }
   

   In this example, a tuple pattern is used in the variable definition to destructure (100, 200) and bind its components to x and y, effectively defining two variables. The for in expression employs a tuple pattern to sequentially extract tuple-type elements from [(1, 2), (3, 4), (5, 6)], destructure them, and bind their components to i and j, then output their sum in the loop body. Compiling and executing this code yields:

   x = 100
   y = 200
   Sum = 3
   Sum = 7
   Sum = 11
   

4. Examples of using irrefutable enum patterns in variable definitions and for in expressions:

   enum RedColor {
       Red(Int64)
   }
   main() {
       let Red(red) = Red(0)
       println("red = ${red}")
       for (Red(r) in [Red(10), Red(20), Red(30)]) {
           println("r = ${r}")
       }
   }
   

   Here, an enum pattern is used in the variable definition to destructure Red(0) and bind its constructor parameter (i.e., 0) to red. The for in expression uses an enum pattern to sequentially extract elements from [Red(10), Red(20), Red(30)], destructure them, and bind their constructor parameters to r, then output r in the loop body. Compiling and executing this code yields:

   red = 0
   r = 10
   r = 20
   r = 30
   

Classes

The class type is a classic concept in object-oriented programming. Cangjie also supports using class to implement object-oriented programming. The main differences between class and struct are: class is a reference type while struct is a value type, and they behave differently during assignment or parameter passing; class types can inherit from each other, but struct types cannot.

This section sequentially introduces how to define class types, how to create objects, and class inheritance.

Class Definition

A class type definition starts with the keyword class, followed by the class name, and then the class body enclosed in curly braces. The class body can define a series of member variables, member properties (see Properties), static initializers, constructors, member functions, and operator functions (details in Operator Overloading).

class Rectangle {
    let width: Int64
    let height: Int64

    public init(width: Int64, height: Int64) {
        this.width = width
        this.height = height
    }

    public func area() {
        width * height
    }
}

The above example defines a class type named Rectangle, which has two Int64 member variables width and height, a constructor with two Int64 parameters, and a member function area (returning the product of width and height).

Note:

class can only be defined at the top-level scope of a source file.

A class modified with abstract is an abstract class. Unlike regular classes, abstract classes can declare abstract functions (without function bodies) in addition to defining normal functions. The open modifier in abstract class definitions is optional, and the sealed modifier can also be used. The sealed modifier indicates that the abstract class can only be inherited within the same package (see Class Inheritance). The following example defines an abstract function foo in the abstract class AbRectangle.

abstract class AbRectangle {
    public func foo(): Unit
}

Note:

• Abstract classes cannot define private abstract functions;
• Instances of abstract classes cannot be created;
• Non-abstract subclasses of abstract classes must implement all abstract functions from the parent class.

Class Member Variables

Class member variables are divided into instance member variables and static member variables. Static member variables are modified with the static modifier, must have initial values if no static initializer is present, and can only be accessed via the type name, as shown in the following example:

class Rectangle {
    let width = 10
    static let height = 20
}

let l = Rectangle.height // l = 20

Instance member variables can be defined without initial values (but must have type annotations) or with initial values, and can only be accessed via objects (i.e., instances of the class), as shown in the following example:

class Rectangle {
    let width = 10
    let height: Int64
    init(h: Int64) {
        height = h
    }
}
let rec = Rectangle(20)
let l = rec.height // l = 20

Class Static Initializer

Classes support defining static initializers, where static member variables can be initialized via assignment expressions.

A static initializer starts with the keyword combination static init, followed by a parameterless parameter list and a function body, and cannot be modified with access modifiers. The function body must initialize all uninitialized static member variables; otherwise, a compilation error occurs.

class Rectangle {
    static let degree: Int64
    static init() {
        degree = 180
    }
}

A class can define at most one static initializer; otherwise, a redefinition error occurs.

class Rectangle {
    static let degree: Int64
    static init() {
        degree = 180
    }
    static init() { // Error, redefinition with the previous static init function
        degree = 180
    }
}

Class Constructors

Like struct, class also supports defining regular constructors and primary constructors.

A regular constructor starts with the keyword init, followed by a parameter list and a function body. The function body must initialize all uninitialized instance member variables; otherwise, a compilation error occurs.

class Rectangle {
    let width: Int64
    let height: Int64

    public init(width: Int64, height: Int64) { // Error, 'height' is not initialized in the constructor
        this.width = width
    }
}

A class can define multiple regular constructors, but they must constitute overloads (see Function Overloading); otherwise, a redefinition error occurs.

class Rectangle {
    let width: Int64
    let height: Int64

    public init(width: Int64) {
        this.width = width
        this.height = width
    }

    public init(width: Int64, height: Int64) { // OK: overloading with the first init function
        this.width = width
        this.height = height
    }

    public init(height: Int64) { // Error, redefinition with the first init function
        this.width = height
        this.height = height
    }
}

In addition to defining regular init constructors, a class can define (at most) one primary constructor. The primary constructor has the same name as the class type, and its parameter list can include two types of parameters: regular parameters and member variable parameters (prefixed with let or var). Member variable parameters serve the dual purpose of defining member variables and constructor parameters.

Using a primary constructor can often simplify class definitions. For example, the above Rectangle with an init constructor can be simplified as follows:

class Rectangle {
    public Rectangle(let width: Int64, let height: Int64) {}
}

The primary constructor’s parameter list can also include regular parameters, for example:

class Rectangle {
    public Rectangle(name: String, let width: Int64, let height: Int64) {}
}

When creating an instance of a class, the constructor is called, and the following sequence of expressions in the class is executed:

1. First, initialize variables defined outside the primary constructor that have default values;
2. If the constructor body does not explicitly call a parent class constructor or another constructor of the same class, the parent class’s parameterless constructor super() is called. If the parent class has no parameterless constructor, an error occurs;
3. Execute the code in the constructor body.

func foo(x: Int64): Int64 {
    println("I'm foo, got ${x}")
    x
}

open class A {
    init() {
        println("I'm A")
    }
}

class B <: A {
    var x = foo(0)
    init() {
        x = foo(1)
        println("init B finished")
    }
}

main() {
    B()
    0
}

In the above example, when calling B’s constructor, the variable x with a default value is initialized first, causing foo(0) to be called; then the parent class’s parameterless constructor is called, causing A’s constructor to be invoked; finally, the code in the constructor body is executed, causing foo(1) to be called and a string to be printed. Thus, the output of the example is:

I'm foo, got 0
I'm A
I'm foo, got 1
init B finished

If a class definition contains no custom constructors (including primary constructors) and all instance member variables have initial values, a parameterless constructor is automatically generated (calling this constructor creates an object where all instance member variables have their initial values); otherwise, this parameterless constructor is not generated. For example, the following class definition will have an auto-generated parameterless constructor:

class Rectangle {
    let width = 10
    let height = 20

    /* Auto-generated parameterless constructor:
    public init() {

    }
    */
}

// Invoke the auto-generated parameterless constructor
let r = Rectangle() // r.width = 10，r.height = 20

Class Finalizer

Classes support defining finalizers, which are triggered when an instance of the class is garbage-collected. The finalizer’s function name is fixed as ~init and is typically used to release system resources. The following example uses unsafe (details in Unsafe Section):

class C {
    var p: CString

    init(s: String) {
        p = unsafe { LibC.mallocCString(s) }
        println(s)
    }
    ~init() {
        unsafe { LibC.free(p) }
    }
}

There are some restrictions on using finalizers that developers should note:

1. Finalizers have no parameters, no return type, no generic type parameters, no modifiers, and cannot be explicitly called.

2. Classes with finalizers cannot be modified with open; only non-open classes can have finalizers.

3. A class can define at most one finalizer.

4. Finalizers cannot be defined in extensions.

5. The timing of finalizer execution is indeterminate.

6. Finalizers may execute on any thread.

7. The execution order of multiple finalizers is indeterminate.

8. Throwing uncaught exceptions from finalizers is undefined behavior.

9. Creating threads or using thread synchronization in finalizers is undefined behavior.

10. If an object remains accessible after its finalizer executes, this is undefined behavior.

11. If an object throws an exception during initialization, the finalizer for the incompletely initialized object will not execute.

12. Relying on finalizers for synchronization is undefined behavior. For example, in the following example, the main function waits for the finalizer in the Test class to modify the value of t0 via while (Test.t0 != 0), which is undefined behavior.

    import std.collection.ArrayList
    import std.runtime.gc
    
    class Test {
        public static var t0 : Int32 = 0
        public init () {
            t0++
        }
        ~init () {
            t0--
        }
    }
    
    var list: ArrayList<Test> = ArrayList<Test>()
    
    func foo() : Int32 {
        let o1 = Test()
        list.add(o1)
        if (Test.t0 != 1) {
            return 1
        }
        list.remove(at: 0)
        return 0
    }
    
    main(): Int64 {
        var i : Int64 = 0
        while (i < 100) {
            if (foo() != 0) {
                print("fail: obj is freed before gc!")
                return 1
            }
            gc(heavy: true) // blocking gc expected
            // wait ~init() to be executed
            while (Test.t0 != 0) {  // error, this is undefined behavior
                continue
            }
            i++
        }
        return 0
    }
    

Class Member Functions

Class member functions are similarly divided into instance member functions and static member functions (modified with the static modifier). Instance member functions can only be accessed through objects, while static member functions can only be accessed through the class type name. Static member functions cannot access instance member variables or call instance member functions, but instance member functions can access static member variables and call static member functions.

In the following example, area is an instance member function, and typeName is a static member function.

class Rectangle {
    let width: Int64 = 10
    let height: Int64 = 20

    public func area() {
        this.width * this.height
    }

    public static func typeName(): String {
        "Rectangle"
    }
}

Instance member functions can be further categorized into abstract member functions and non-abstract member functions based on whether they have a function body. Abstract member functions lack a function body and can only be defined in abstract classes or interfaces (see Interfaces for details). Note that abstract instance member functions inherently have open semantics, where the open modifier is optional and must be used with either public or protected modifiers.

Non-abstract functions must have a function body. Within the function body, instance member variables can be accessed via this. For example:

class Rectangle {
    let width: Int64 = 10
    let height: Int64 = 20

    public func area() {
        this.width * this.height
    }
}

Access Modifiers for Class Members

For class members (including member variables, member properties, constructors, and member functions), four access modifiers can be used: private, internal, protected, and public. The default is internal.

• private: Visible only within the class definition.
• internal: Visible only within the current package and its sub-packages (including sub-packages of sub-packages; see Packages).
• protected: Visible within the current module (see Packages) and to subclasses of the current class.
• public: Visible both inside and outside the module.

package a

public open class Rectangle {
    public var width: Int64
    protected var height: Int64
    private var area: Int64
    public init(width: Int64, height: Int64) {
        this.width = width
        this.height = height
        this.area = this.width * this.height
    }
    init(width: Int64, height: Int64, multiple: Int64) {
        this.width = width
        this.height = height
        this.area = width * height * multiple
    }
}

func samePkgFunc() {
    var r = Rectangle(10, 20) // OK: constructor 'Rectangle' can be accessed here
    r.width = 8               // OK: public 'width' can be accessed here
    r.height = 24             // OK: protected 'height' can be accessed here
    r.area = 30               // Error, private 'area' cannot be accessed here
}

package b
import a.*

public class Cuboid <: Rectangle {
    private var length: Int64
    public init(width: Int64, height: Int64, length: Int64) {
        super(width, height)
        this.length = length
    }
    public func volume() {
        this.width * this.height * this.length // OK: protected 'height' can be accessed here
    }
}

main() {
    var r = Rectangle(10, 20, 2) // Error, Rectangle has no `public` constructor with three parameters
    var c = Cuboid(20, 20, 20)
    c.width = 8               // OK: public 'width' can be accessed here
    c.height = 24             // Error, protected 'height' cannot be accessed here
    c.area = 30               // Error, private 'area' cannot be accessed here
}

The This Type

Within a class, the This type placeholder is supported, representing the current class type. It can only be used as the return type of instance member functions. When a subclass object calls a function defined in the parent class that returns a This type, the type of the function call is recognized as the subclass type, not the parent class type where it was defined.

If an instance member function does not declare a return type and only contains expressions returning This, the function’s return type is inferred as This. Example:

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
    }
}

main() {
    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
}

Creating Objects

After defining a class type, objects can be created by calling its constructor (via the class type name). For example, in the following code, Rectangle(10, 20) creates an object of type Rectangle and assigns it to variable r. After creation, (public-modified) instance member variables and instance member functions can be accessed through the object. For example, r.width and r.height access the values of width and height in r, respectively, and r.area() calls the member function area.

class Rectangle {
    let width: Int64
    let height: Int64

    public init(width: Int64, height: Int64) {
        this.width = width
        this.height = height
    }

    public func area() {
        this.width * this.height
    }
}

main() {
    let r = Rectangle(10, 20) // r.width = 10, r.height = 20
    let width = r.width       // width = 10
    let height = r.height     // height = 20
    let a = r.area()          // a = 200
}

If you wish to modify member variable values through objects (not recommended; it’s better to modify them via member functions), the member variables in the class must be defined as mutable (using var). Example:

class Rectangle {
   public var width: Int64
   public var height: Int64

    public init(width: Int64, height: Int64) {
        this.width = width
        this.height = height
    }
    public func area() {
        width * height
    }
}

main() {
    let r = Rectangle(10, 20) // r.width = 10, r.height = 20
    r.width = 8               // r.width = 8
    r.height = 24             // r.height = 24
    let a = r.area()          // a = 192
}

Unlike struct, when objects are assigned or passed as parameters, they are not copied. Multiple variables point to the same object, so modifying a member through one variable affects the corresponding member in other variables. For example, in the following code, after assigning r1 to r2, modifying r1.width and r1.height also changes r2.width and r2.height.

class Rectangle {
    var width: Int64
    var height: Int64

    public init(width: Int64, height: Int64) {
        this.width = width
        this.height = height
    }
     public func area() {
        this.width * this.height
    }
}
main() {
    var r1 = Rectangle(10, 20) // r1.width = 10, r1.height = 20
    var r2 = r1                // r2.width = 10, r2.height = 20
    r1.width = 8               // r1.width = 8
    r1.height = 24             // r1.height = 24
    let a1 = r1.area()         // a1 = 192
    let a2 = r2.area()         // a2 = 192
}

Class Inheritance

Like most programming languages that support class, Cangjie’s class also supports inheritance. If class B inherits from class A, A is called the parent class, and B is called the child class. The child class inherits all members of the parent class except private members and constructors.

Abstract classes are always inheritable, so the open modifier for abstract class definitions is optional. Alternatively, an abstract class can be modified with sealed, indicating it can only be inherited within its package. However, non-abstract classes can only be inherited if they are defined with the open modifier. When an open-modified instance member is inherited by a class, the open modifier is also inherited. If a non-open class contains open members, the compiler will issue a warning.

The parent class can be specified in the child class definition using <:, but the parent class must be inheritable. For example, in the following code, class A is modified with open, so it can be inherited by class B. However, since class B is not inheritable, C will report an error when attempting to inherit from B.

open class A {
    let a: Int64 = 10
}

class B <: A { // OK: 'B' Inheritance 'A'
    let b: Int64 = 20
}

class C <: B { // Error, 'B' is not inheritable
    let c: Int64 = 30
}

class supports only single inheritance, so the following code attempting to inherit from two classes is invalid (& is syntax for implementing multiple interfaces; see Interfaces).

open class A {
    let a: Int64 = 10
}

open class B {
    let b: Int64 = 20
}

class C <: A & B { // Error, 'C' can only inherit one class
    let c: Int64 = 30
}

Because classes support only single inheritance, any class can have at most one direct parent class. For classes defined with a parent class, the direct parent is the specified class. For classes defined without a parent class, the direct parent is the Object type. Object is the parent of all classes (note: Object has no direct parent and contains no members).

Because child classes inherit from parent classes, child class objects can naturally be used as parent class objects, but the reverse is not true. For example, in the following code, B is a child of A, so a B-type object can be assigned to an A-type variable, but an A-type object cannot be assigned to a B-type variable.

open class A {
    let a: Int64 = 10
}
class B <: A {
    let b: Int64 = 20
}

let a: A = B() // OK: subclass objects can be assigned to superclass variables

open class A {
    let a: Int64 = 10
}

class B <: A {
    let b: Int64 = 20
}

let b: B = A() // Error, superclass objects can not be assigned to subclass variables

The class defined type does not allow inheriting from itself.

class A <: A {}  // Error, 'A' inherits itself

Abstract classes can use the sealed modifier, indicating that the modified class definition can only be inherited by other classes within the same package where the definition resides. The sealed modifier already implies public/open semantics. Therefore, when defining a sealed abstract class, if public/open modifiers are provided, the compiler will issue a warning. Subclasses of sealed classes do not have to be sealed themselves and can still be modified with open/sealed or use no inheritance modifiers at all. If a subclass of a sealed class is modified with open, then its subclasses can be inherited outside the package. Subclasses of sealed classes do not need to be modified with public.

package A

public sealed abstract class C1 {}   // Warning, redundant modifier, 'sealed' implies 'public'
sealed open abstract class C2 {}     // Warning, redundant modifier, 'sealed' implies 'open'
sealed abstract class C3 {}          // OK, 'public' is optional when 'sealed' is used

class S1 <: C1 {}  // OK
public open class S2 <: C1 {}   // OK
public sealed abstract class S3 <: C1 {}  // OK
open class S4 <: C1 {}   // OK

package B
import A.*

class SS1 <: S2 {}  // OK
class SS2 <: S3 {}  // Error, S3 is sealed class, cannot be inherited here
sealed class SS3 {} // Error, 'sealed' cannot be used on non-abstract class

Superclass Constructor Invocation

The init constructor of a subclass can call the superclass constructor using the form super(args), or call another constructor of the same class using this(args), but only one of them can be called. If called, it must be the first expression in the constructor body, with no preceding expressions or declarations allowed.

open class A {
    A(let a: Int64) {}
}

class B <: A {
    let b: Int64
    init(b: Int64) {
        super(30)
        this.b = b
    }

    init() {
        this(20)
    }
}

In the primary constructor of a subclass, the superclass constructor can be called using super(args), but other constructors of the same class cannot be called using this(args).

If a subclass constructor does not explicitly call a superclass constructor or another constructor, the compiler will insert a call to 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 will occur.

open class A {
    let a: Int64
    init() {
        a = 100
    }
}

open class B <: A {
    let b: Int64
    init(b: Int64) {
        // OK, `super()` added by compiler
        this.b = b
    }
}

open class C <: B {
    let c: Int64
    init(c: Int64) {  // Error, there is no non-parameter constructor in super class
        this.c = c
    }
}

Overriding and Redefinition

In a subclass, non-abstract instance member functions with the same name as those in the parent class can be overridden, meaning new implementations can be defined for these functions in the subclass. When overriding, the member function in the parent class must be modified with open, and the function in the subclass must be modified with override, where override is optional. For example, in the following example, the function f in subclass B overrides the function f in parent class A.

open class A {
    public open func f(): Unit {
        println("I am superclass")
    }
}

class B <: A {
    public override func f(): Unit {
        println("I am subclass")
    }
}

main() {
    let a: A = A()
    let b: A = B()
    a.f()
    b.f()
}

For overridden functions, the version called is determined by the runtime type of the variable (determined by the actual object assigned to the variable), known as dynamic dispatch. For example, in the above example, the runtime type of a is A, so a.f() calls the function f in parent class A; the runtime type of b is B (compile-time type is A), so b.f() calls the function f in subclass B. Therefore, the program will output:

I am superclass
I am subclass

For static functions, non-abstract static functions with the same name as those in the parent class can be redefined in the subclass, meaning new implementations can be defined for these functions in the subclass. When redefining, the static function in the subclass must be modified with redef, where redef is optional. For example, in the following example, the function foo in subclass D redefines the function foo in parent class C.

open class C {
    public static func foo(): Unit {
        println("I am class C")
    }
}

class D <: C {
    public redef static func foo(): Unit {
        println("I am class D")
    }
}

main() {
    C.foo()
    D.foo()
}

For redefined functions, the version called is determined by the type of the class. For example, in the above example, C.foo() calls the function foo in parent class C, and D.foo() calls the function foo in subclass D.

I am class C
I am class D

If an abstract function or a function modified with open has named parameters, the implementing function or the function modified with override must maintain the same named parameters.

open class A {
    public open func f(a!: Int32): Int32 {
        a + 1
    }
}

class B <: A {
    public override func f(a!: Int32): Int32 { // OK
        a + 2
    }
}

class C <: A {
    public override func f(b!: Int32): Int32 { // Error
        b + 3
    }
}

main() {
    B().f(a: 0)
    C().f(b: 0)
}

It is also important to note that when implementing or redefining a generic function, the type parameter constraints of the subtype function must be looser or the same as those of the corresponding function in the parent type.

open class A {}
open class B <: A {}
open class C <: B {}

open class Base {
    public open func foo<T>(a: T): Unit where T <: B {}
    public open func bar<T>(a: T): Unit where T <: B {}
    public static func f<T>(a: T): Unit where T <: B {}
    public static func g<T>(): Unit where T <: B {}
}

class D <: Base {
    public override func foo<T>(a: T): Unit where T <: C {} // Error, stricter constraint
    public override func bar<T>(a: T): Unit where T <: C {} // Error, stricter constraint
    public redef static func f<T>(a: T): Unit where T <: C {} // Error, stricter constraint
    public redef static func g<T>(): Unit where T <: C {} // Error, stricter constraint
}

class E <: Base {
    public override func foo<T>(a: T): Unit where T <: A {} // OK: looser constraint
    public override func bar<V>(a: V): Unit where V <: A {} // OK: looser constraint, names of generic parameters do not matter
    public redef static func f<T>(a: T): Unit where T <: A {} // OK: looser constraint
    public redef static func g<T>(): Unit where T <: A {} // OK: looser constraint
}

class F <: Base {
    public override func foo<T>(a: T): Unit where T <: B {} // OK: same constraint
    public override func bar<V>(a: V): Unit where V <: B {} // OK: same constraint
    public redef static func f<T>(a: T): Unit where T <: B {} // OK: same constraint
    public redef static func g<T>(): Unit where T <: B {} // OK: same constraint
}

Interface

An interface is used to define an abstract type that contains no data but can specify the behavior of a type. A type is said to implement an interface if it declares to implement that interface and provides implementations for all its members.

Interface members may include:

• Member functions
• Operator overload functions
• Member properties

All these members are abstract, requiring the implementing type to provide corresponding implementations.

Interface Definition

A simple interface definition is as follows:

interface I { // 'open' modifier is optional.
    func f(): Unit
}

Interfaces are declared using the interface keyword, followed by the interface identifier I and its members. Interface members can be modified with the optional open modifier.

When interface I declares a member function f, any type implementing I must provide a corresponding implementation of f.

Since interface inherently has open semantics, the open modifier in interface definitions is optional.

As shown in the following code, a class Foo is defined using the syntax Foo <: I to declare that Foo implements interface I.

Foo must contain implementations for all members declared in I, meaning it needs to define an f of the same type; otherwise, a compilation error will occur due to unimplemented interface requirements.

class Foo <: I {
    public func f(): Unit {
        println("Foo")
    }
}

main() {
    let a = Foo()
    let b: I = a
    b.f() // "Foo"
}

When a type implements an interface, it becomes a subtype of that interface.

In the above example, Foo is a subtype of I, so any instance of Foo can be used as an instance of I.

In main, a Foo-type variable a is assigned to an I-type variable b. When calling function f on b, the f implementation from Foo is executed, printing:

Foo

An interface can also be modified with sealed to indicate that it can only be inherited, implemented, or extended within the package where the interface is defined. sealed inherently implies public/open semantics, so defining a sealed interface with additional public/open modifiers will trigger compiler warnings. Child interfaces inheriting from a sealed interface or abstract classes implementing it may still be marked sealed or left unmodified. If a child interface of a sealed interface is marked public but not sealed, it can be inherited, implemented, or extended outside the package. Types inheriting or implementing a sealed interface need not be marked public.

package A
public interface I1 {}
sealed interface I2 {}         // OK
public sealed interface I3 {}  // Warning, redundant modifier, 'sealed' implies 'public'
sealed open interface I4 {}    // Warning, redundant modifier, 'sealed' implies 'open'

class C1 <: I1 {}
public open class C2 <: I1 {}
sealed abstract class C3 <: I2 {}
extend Int64 <: I2 {}

package B
import A.*

class S1 <: I1 {}  // OK
class S2 <: I2 {}  // Error, I2 is sealed interface, cannot be inherited here.

Through this constraint mechanism, interfaces can define common functionalities for a series of types, achieving the purpose of functional abstraction.

For example, the following code defines a Flyable interface and has other classes with flying capabilities implement it.

interface Flyable {
    func fly(): Unit
}

class Bird <: Flyable {
    public func fly(): Unit {
        println("Bird flying")
    }
}

class Bat <: Flyable {
    public func fly(): Unit {
        println("Bat flying")
    }
}

class Airplane <: Flyable {
    public func fly(): Unit {
        println("Airplane flying")
    }
}

func fly(item: Flyable): Unit {
    item.fly()
}

main() {
    let bird = Bird()
    let bat = Bat()
    let airplane = Airplane()
    fly(bird)
    fly(bat)
    fly(airplane)
}

Compiling and executing the above code yields the following output:

Bird flying
Bat flying
Airplane flying

Interface members can be either instance or static. The previous examples demonstrated instance member functions; now let’s examine static member functions.

Static member functions, like instance member functions, require implementing types to provide implementations.

For example, the following code defines a NamedType interface containing a static member function typename to retrieve the string name of each type.

Other types implementing NamedType must provide an implementation of typename, enabling safe retrieval of type names for all subtypes of NamedType.

interface NamedType {
    static func typename(): String
}

class A <: NamedType {
    public static func typename(): String {
        "A"
    }
}

class B <: NamedType {
    public static func typename(): String {
        "B"
    }
}

main() {
    println("the type is ${ A.typename() }")
    println("the type is ${ B.typename() }")
}

The program outputs:

the type is A
the type is B

Static member functions (or properties) in interfaces may either have no default implementation or provide one.

When no default implementation exists, the member cannot be accessed via the interface type name. For example, the following code triggers a compilation error when attempting to access typename directly through NamedType, because NamedType lacks an implementation of typename.

interface NamedType {
    static func typename(): String
}
main() {
    NamedType.typename() // Error
}

Static member functions (or properties) in interfaces can also have default implementations. When a type inherits from an interface with default static function (or property) implementations, that type may omit reimplementing the static member, which can then be accessed directly through either the interface name or the type name. In the following example, NamedType’s typename member function has a default implementation, which A doesn’t need to reimplement, while still allowing direct access via both the interface and type names.

interface NamedType {
    static func typename(): String {
        "interface NamedType"
    }
}

class A <: NamedType {}

main() {
    println(NamedType.typename())
    println(A.typename())
}

The program outputs:

interface NamedType
interface NamedType

Such static members are typically used in generic functions through generic constraints.

For example, the printTypeName function below constrains the generic parameter T to be a subtype of NamedType, ensuring that all static member functions (or properties) in the instantiated type of T have implementations, enabling access via T.typename. This achieves abstraction of static members. See Generics for details.

interface NamedType {
    static func typename(): String
}

interface I <: NamedType {
    static func typename(): String {
        f()
    }
    static func f(): String
}

class A <: NamedType {
    public static func typename(): String {
        "A"
    }
}

class B <: NamedType {
    public static func typename(): String {
        "B"
    }
}

func printTypeName<T>() where T <: NamedType {
    println("the type is ${ T.typename() }")
}

main() {
    printTypeName<A>() // OK
    printTypeName<B>() // OK
    printTypeName<I>() // Error, 'I' must implement all static function. Otherwise, an unimplemented 'f' is called, causing problems.
}

Interfaces can define generic instance member functions or generic static member functions, which, like non-generic functions, have open semantics.

import std.collection.ArrayList
interface M {
    func foo<T>(a: T): T
    static func toString<T>(b: ArrayList<T>): String where T <: ToString
}
class C <: M {
    public func foo<S>(a: S): S { // implements M::foo, names of generic parameters do not matter
        a
    }
    public static func toString<T>(b: ArrayList<T>) where T <: ToString {
        var res = ""
        for (s in b) {
            res += s.toString()
        }
        res
    }
}

Note that interface members are inherently public and cannot be declared with additional access control modifiers. Implementing types must also use public implementations.

interface I {
    func f(): Unit
}

open class C <: I {
    protected func f() {} // Compiler Error, f needs to be public semantics
}
```## Interface Inheritance and Interface Implementation

When implementing multiple interfaces for a type, you can use `&` to separate multiple interfaces in the declaration, with no specific order required between the implemented interfaces.

For example, the following code allows `MyInt` to implement both the `Addable` and `Subtractable` interfaces.

<!-- compile -->

```cangjie
interface Addable {
    func add(other: Int64): Int64
}

interface Subtractable {
    func sub(other: Int64): Int64
}

class MyInt <: Addable & Subtractable {
    var value = 0
    public func add(other: Int64): Int64 {
        value + other
    }
    public func sub(other: Int64): Int64 {
        value - other
    }
}

An interface can inherit one or more interfaces but cannot inherit a class. Additionally, new interface members can be added during interface inheritance.

For example, the Calculable interface in the following code inherits both the Addable and Subtractable interfaces and adds overloads for multiplication and division operators.

interface Addable {
    func add(other: Int64): Int64
}

interface Subtractable {
    func sub(other: Int64): Int64
}

interface Calculable <: Addable & Subtractable {
    func mul(other: Int64): Int64
    func div(other: Int64): Int64
}

When a type implements the Calculable interface, it must implement all four operator overloads (addition, subtraction, multiplication, and division), with no members omitted.

class MyInt <: Calculable {
    var value = 0
    public func add(other: Int64): Int64 {
        value + other
    }
    public func sub(other: Int64): Int64 {
        value - other
    }
    public func mul(other: Int64): Int64 {
        value * other
    }
    public func div(other: Int64): Int64 {
        value / other
    }
}

By implementing Calculable, MyInt also implements all interfaces inherited by Calculable. Thus, MyInt is also a subtype of Addable and Subtractable.

main() {
    let myInt = MyInt()
    let add: Addable = myInt
    let sub: Subtractable = myInt
    let calc: Calculable = myInt
}

For interface inheritance, if a child interface inherits a function or property with a default implementation from its parent interface, it cannot merely declare that function or property (i.e., without a default implementation). It must provide a new default implementation. The override or redef modifier before the function definition is optional. If a child interface inherits a function or property without a default implementation from its parent interface, it can either declare it or provide a default implementation, with the override or redef modifier being optional. The redef modifier specifically targets the redefinition of static functions with the same name in child classes.

interface I1 {
   func f(a: Int64) {
        a
   }
   static func g(a: Int64) {
        a
   }
   func f1(a: Int64): Unit
   static func g1(a: Int64): Unit
}

interface I2 <: I1 {
    /*'override' is optional*/ func f(a: Int64) {
       a + 1
    }
    override func f(a: Int32) {} // Error, override function 'f' does not have an overridden function from its supertypes
    static /*'redef' is optional*/ func g(a: Int64) {
       a + 1
    }
    /*'override' is optional*/ func f1(a: Int64): Unit {}
    static /*'redef' is optional*/ func g1(a: Int64): Unit {}
}

Requirements for Interface Implementation

In Cangjie, all types except Tuple, VArray, and functions can implement interfaces.

A type can implement an interface in three ways:

1. Declaring interface implementation during type definition, as shown in the examples above.
2. Implementing interfaces via extensions (see Extensions for details).
3. Built-in language implementation (refer to the relevant documentation in the Cangjie Programming Language Library API).

When a type declares interface implementation, it must implement all required members of the interface, adhering to the following rules:

1. For member functions and operator overload functions, the implementing type must provide functions with the same name, parameter list, and return type as those specified in the interface.
2. For member properties, the mut modifier must be consistent, and the property types must match.

In most cases, as shown in the examples above, the implementing type must contain implementations matching the interface’s requirements.

However, there is one exception: if the return type of a member function or operator overload function in the interface is a class type, the implementing function’s return type can be a subtype of that class.

For example, in the following code, the return type of f in I is the class type Base, so the return type of f in C can be Sub, a subtype of Base.

open class Base {}
class Sub <: Base {}

interface I {
    func f(): Base
}

class C <: I {
    public func f(): Sub {
        Sub()
    }
}

Additionally, interface members can provide default implementations. For example, in the following code, say in SayHi has a default implementation, so A can inherit this implementation when implementing SayHi, while B can choose to provide its own implementation of say.

interface SayHi {
    func say() {
        "hi"
    }
}

class A <: SayHi {}

class B <: SayHi {
    public func say() {
        "hi, B"
    }
}

Notably, if a type implements multiple interfaces that contain default implementations for the same member, a multiple inheritance conflict occurs. The language cannot determine the most suitable implementation, so the default implementations become invalid, and the implementing type must provide its own implementation.

For example, in the following code, both SayHi and SayHello contain implementations of say. When Foo implements these two interfaces, it must provide its own implementation; otherwise, a compilation error will occur.

interface SayHi {
    func say() {
        "hi"
    }
}

interface SayHello {
    func say() {
        "hello"
    }
}

class Foo <: SayHi & SayHello {
    public func say() {
        "Foo"
    }
}

For struct, enum, and class, the override modifier (or redef modifier) before function or property definitions is optional when implementing interfaces, regardless of whether the interface’s functions or properties have default implementations.

interface I {
    func foo(): Int64 {
        return 0
    }
}
enum E <: I{
    elem
    public override func foo(): Int64 {
        return 1
    }
}
struct S <: I {
    public override func foo(): Int64 {
        return 1
    }
}

The Any Type

Any is a built-in interface defined as follows:

interface Any {}

In Cangjie, all interfaces implicitly inherit from Any, and all non-interface types implicitly implement it. Therefore, all types can be used as subtypes of Any.

For example, in the following code, variables of different types can be assigned to an Any-type variable.

main() {
    var any: Any = 1
    any = 2.0
    any = "hello, world!"
}

Properties

Properties provide a getter and an optional setter to indirectly retrieve and modify values.

When using properties, they behave no differently from ordinary variables—you only need to manipulate the data without being aware of the internal implementation. This facilitates mechanisms such as access control, data monitoring, debugging, and data binding.

Properties can be used as expressions or assigned values. Here, classes and interfaces are used as examples, but properties are not limited to these.

The following is a simple example where b is a typical property that encapsulates external access to a:

class Foo {
    private var a = 0

    public mut prop b: Int64 {
        get() {
            println("get")
            a
        }
        set(value) {
            println("set")
            a = value
        }
    }
}

main() {
    var x = Foo()
    let y = x.b + 1 // get
    x.b = y // set
}

Here, Foo provides a property named b. For the getter/setter functionality, Cangjie provides get and set syntax for definition. When a variable x of type Foo accesses b, the get operation of b is called, returning a value of type Int64, which can then be used to add to 1. When x assigns a value to b, the set operation of b is called, passing the value of y to the value parameter of set, and ultimately assigning value to a.

Through property b, external code remains completely unaware of the member variable a in Foo, yet can achieve the same access and modification operations via b, demonstrating effective encapsulation. Thus, the program outputs:

get
set

Property Definition

Properties can be defined in interface, class, struct, enum, and extend.

A typical property syntax structure is as follows:

class Foo {
    public prop a: Int64 {
        get() { 0 }
    }
    public mut prop b: Int64 {
        get() { 0 }
        set(v) {}
    }
}

Here, a and b declared with prop are both properties, and both are of type Int64. a is a property without the mut modifier—such properties must define only a getter (for value retrieval). b is a property with the mut modifier—such properties must define both a getter (for value retrieval) and a setter (for value assignment).

Note:

For numeric types, tuples, functions, Bool, Unit, Nothing, String, Range, and enum types, mut properties cannot be declared in their extensions or declarations, nor can interfaces with mut properties be implemented.

The getter and setter of a property correspond to two distinct functions.

1. The getter function type is () -> T, where T is the property’s type. The getter function is executed when the property is used as an expression.
2. The setter function type is (T) -> Unit, where T is the property’s type. The parameter name must be explicitly specified. The setter function is executed when the property is assigned a value.

The implementations of the getter and setter can include declarations and expressions, just like function bodies, following the same rules as function bodies. For details, refer to the Function Body section.

The parameter in the setter corresponds to the value passed during assignment.

class Foo {
    private var j = 0
    public mut prop i: Int64 {
        get() {
            j
        }
        set(v) {
            j = v
        }
    }
}

Note that accessing the property itself within its getter or setter constitutes a recursive call, which, like function calls, may lead to infinite loops.

Modifiers

Modifiers can be declared before prop.

class Foo {
    public prop a: Int64 {
        get() {
            0
        }
    }
    private prop b: Int64 {
        get() {
            0
        }
    }
}

Like member functions, member properties also support the open, override, and redef modifiers, allowing properties to be overridden/redefined in subtypes.

When a subtype overrides a property from its parent type, if the parent property has the mut modifier, the subtype property must also have the mut modifier and maintain the same type.

As shown in the following code, A defines two properties, x and y. B can override/redefine x and y using override/redef:

open class A {
    private var valueX = 0
    private static var valueY = 0

    public open prop x: Int64 {
        get() { valueX }
    }

    public static mut prop y: Int64 {
        get() { valueY }
        set(v) {
            valueY = v
        }
    }
}
class B <: A {
    private var valueX2 = 0
    private static var valueY2 = 0

    public override prop x: Int64 {
        get() { valueX2 }
    }

    public redef static mut prop y: Int64 {
        get() { valueY2 }
        set(v) {
            valueY2 = v
        }
    }
}

Abstract Properties

Similar to abstract functions, abstract properties can be declared in interface and abstract classes. These abstract properties have no implementation.

interface I {
    prop a: Int64
}

abstract class C {
    public prop a: Int64
}

When an implementing type realizes an interface or a non-abstract subclass inherits from an abstract class, these abstract properties must be implemented.

Like the rules for overriding, if the parent property has the mut modifier, the subtype property must also have the mut modifier and maintain the same type.

interface I {
    prop a: Int64
    mut prop b: Int64
}
class C <: I {
    private var value = 0

    public prop a: Int64 {
        get() { value }
    }

    public mut prop b: Int64 {
        get() { value }
        set(v) {
            value = v
        }
    }
}

Abstract properties allow interfaces and abstract classes to specify data operations in a more user-friendly manner, making them more intuitive compared to function-based approaches.

As shown in the following code, if you want to specify the retrieval and modification of a size value, using properties (I1) results in less code and aligns better with the intent of data manipulation compared to using functions (I2).

interface I1 {
    mut prop size: Int64
}

interface I2 {
    func getSize(): Int64
    func setSize(value: Int64): Unit
}

class C <: I1 & I2 {
    private var mySize = 0

    public mut prop size: Int64 {
        get() {
            mySize
        }
        set(value) {
            mySize = value
        }
    }

    public func getSize() {
        mySize
    }

    public func setSize(value: Int64) {
        mySize = value
    }
}

main() {
    let a: I1 = C()
    a.size = 5
    println(a.size)

    let b: I2 = C()
    b.setSize(5)
    println(b.getSize())
}

5
5

Property Usage

Properties are divided into instance member properties and static member properties. The usage of member properties is the same as that of member variables. For details, refer to the Member Variables section.

class A {
    public prop x: Int64 {
        get() {
            123
        }
    }
    public static prop y: Int64 {
        get() {
            321
        }
    }
}

main() {
    var a = A()
    println(a.x) // 123
    println(A.y) // 321
}

The result is:

123
321

Properties without the mut modifier are similar to variables declared with let and cannot be assigned.

class A {
    private let value = 0
    public prop i: Int64 {
        get() {
            value
        }
    }
}

main() {
    var x = A()
    println(x.i) // OK
    x.i = 1 // Error
}

Properties marked with the mut modifier are similar to variables declared with var, allowing both value retrieval and assignment.

class A {
    private var value: Int64 = 0
    public mut prop i: Int64 {
        get() {
            value
        }
        set(v) {
            value = v
        }
    }
}

main() {
    var x = A()
    println(x.i) // OK
    x.i = 1 // OK
}

0

Subtype Relationships

Like other object-oriented languages, the Cangjie language provides subtype relationships and subtype polymorphism. Examples include (but are not limited to the following use cases):

• If a function’s formal parameter is of type T, the actual type of the argument passed during the function call can be either T or a subtype of T (strictly speaking, the subtypes of T already include T itself, and the same applies below).
• If the type of the variable on the left-hand side of an assignment expression = is T, the actual type of the expression on the right-hand side of = can be either T or a subtype of T.
• If the user-annotated return type in a function definition is T, the type of the function body (and the types of all return expressions within the function body) can be either T or a subtype of T.

The following sections describe several scenarios where two types form a subtype relationship.

Subtype Relationships Introduced by Class Inheritance

After inheriting from a class, the subclass becomes a subtype of the parent class. In the following code, Sub is a subtype of Super.

open class Super {}
class Sub <: Super {}

Subtype Relationships Introduced by Interface Implementation

After implementing an interface (including extension implementations), the type implementing the interface becomes a subtype of the interface. In the following code, I3 is a subtype of I1 and I2, C is a subtype of I1, and Int64 is a subtype of I2:

interface I1 {}
interface I2 {}

interface I3 <: I1 & I2 {}

class C <: I1 {}

extend Int64 <: I2 {}

Subtype Relationships of Tuple Types

Tuple types in the Cangjie language also have subtype relationships. Intuitively, if each element type of a tuple t1 is a subtype of the corresponding element type in another tuple t2, then the type of tuple t1 is also a subtype of the type of tuple t2. For example, in the following code, since C2 <: C1 and C4 <: C3, it follows that (C2, C4) <: (C1, C3) and (C4, C2) <: (C3, C1).

open class C1 {}
class C2 <: C1 {}

open class C3 {}
class C4 <: C3 {}

let t1: (C1, C3) = (C2(), C4()) // OK
let t2: (C3, C1) = (C4(), C2()) // OK

Subtype Relationships of Function Types

In the Cangjie language, functions are first-class citizens, and function types also have subtype relationships: Given two function types (U1) -> S2 and (U2) -> S1, (U1) -> S2 is a subtype of (U2) -> S1 if and only if U2 is a subtype of U1 and S2 is a subtype of S1 (note the order). For example, the following code defines two functions f : (U1) -> S2 and g : (U2) -> S1, where the type of f is a subtype of the type of g. Since the type of f is a subtype of g, f can be used wherever g is used.

open class U1 {}
class U2 <: U1 {}

open class S1 {}
class S2 <: S1 {}


func f(a: U1): S2 { S2() }
func g(a: U2): S1 { S1() }

func call1() {
    g(U2()) // OK
    f(U2()) // OK
}

func h(lam: (U2) -> S1): S1 {
    lam(U2())
}

func call2() {
    h(g) // OK
    h(f) // OK
}

For the above rule, the S2 <: S1 part is easy to understand: The result data produced by a function call will be used by subsequent programs. Function g can produce result data of type S1, and function f can produce result data of type S2. The result data produced by g should be replaceable by the result data produced by f, hence the requirement that S2 <: S1.

For the U2 <: U1 part, it can be understood as follows: Before a function call produces a result, it must be callable. The actual argument type of the function call remains fixed, while the formal parameter type can be more permissive and still be callable. However, if the formal parameter type is more restrictive, it may not be callable—for example, given the definitions in the above code, g(U2()) can be replaced with f(U2()) precisely because the actual argument type U2 is more restrictive than the formal parameter type U1.

Subtype Relationships That Always Hold

In the Cangjie language, some predefined subtype relationships always hold:

• A type T is always a subtype of itself, i.e., T <: T.
• The Nothing type is always a subtype of any other type T, i.e., Nothing <: T.
• Any type T is a subtype of the Any type, i.e., T <: Any.
• Any type defined by a class is a subtype of Object, i.e., if class C {} exists, then C <: Object.

Subtype Relationships Introduced by Transitivity

Subtype relationships are transitive. In the following code, although only I2 <: I1, C <: I2, and Bool <: I2 are described, the transitivity of subtypes implicitly establishes C <: I1 and Bool <: I1 as subtype relationships.

interface I1 {}
interface I2 <: I1 {}

class C <: I2 {}

extend Bool <: I2 {}

Subtype Relationships of Generic Types

Generic types also have subtype relationships. For details, see Subtype Relationships of Generic Types.

Type Conversion

Cangjie does not support implicit conversion between different types (subtypes are inherently parent types, so conversion from a subtype to a parent type is not implicit type conversion). Type conversion must be performed explicitly. The following sections will introduce conversions between numeric types, conversions from Rune to UInt32 and from integer types to Rune, as well as the is and as operators.

Conversions Between Numeric Types

For numeric types (including: Int8, Int16, Int32, Int64, IntNative, UInt8, UInt16, UInt32, UInt64, UIntNative, Float16, Float32, Float64), Cangjie supports using the T(e) syntax to obtain a value equal to e with type T. Here, the expression e and type T can be any of the aforementioned numeric types.

The following example demonstrates type conversion between numeric types:

main() {
    let a: Int8 = 10
    let b: Int16 = 20
    let r1 = Int16(a)
    println("The type of r1 is 'Int16', and r1 = ${r1}")
    let r2 = Int8(b)
    println("The type of r2 is 'Int8', and r2 = ${r2}")

    let c: Float32 = 1.0
    let d: Float64 = 1.123456789
    let r3 = Float64(c)
    println("The type of r3 is 'Float64', and r3 = ${r3}")
    let r4 = Float32(d)
    println("The type of r4 is 'Float32', and r4 = ${r4}")

    let e: Int64 = 1024
    let f: Float64 = 1024.1024
    let r5 = Float64(e)
    println("The type of r5 is 'Float64', and r5 = ${r5}")
    let r6 = Int64(f)
    println("The type of r6 is 'Int64', and r6 = ${r6}")
}

The execution result of the above code is:

The type of r1 is 'Int16', and r1 = 10
The type of r2 is 'Int8', and r2 = 20
The type of r3 is 'Float64', and r3 = 1.000000
The type of r4 is 'Float32', and r4 = 1.123457
The type of r5 is 'Float64', and r5 = 1024.000000
The type of r6 is 'Int64', and r6 = 1024

Note:

Overflow may occur during type conversion. If the overflow can be detected by the compiler in advance, the compiler will directly report an error. Otherwise, an exception will be thrown according to the default overflow policy.

Conversion from Rune to UInt32 and from Integer Types to Rune

Conversion from Rune to UInt32 uses the UInt32(e) syntax, where e is a Rune-type expression. The result of UInt32(e) is the UInt32-type integer value corresponding to the Unicode scalar value of e.

Conversion from integer types to Rune uses the Rune(num) syntax, where num can be of any integer type. Only when the value of num falls within [0x0000, 0xD7FF] or [0xE000, 0x10FFFF] (i.e., Unicode scalar value range), the corresponding character represented by the Unicode scalar value is returned. Otherwise, a compilation error will occur (if the value of num can be determined at compile time) or an exception will be thrown at runtime.

The following example demonstrates type conversion between Rune and UInt32:

main() {
    let x: Rune = 'a'
    let y: UInt32 = 65
    let r1 = UInt32(x)
    let r2 = Rune(y)
    println("The type of r1 is 'UInt32', and r1 = ${r1}")
    println("The type of r2 is 'Rune', and r2 = ${r2}")
}

The execution result of the above code is:

The type of r1 is 'UInt32', and r1 = 97
The type of r2 is 'Rune', and r2 = A

The is and as Operators

Cangjie supports using the is operator to determine whether the type of an expression is the specified type (or its subtype). Specifically, for the expression e is T (where e can be any expression and T can be any type), when the runtime type of e is a subtype of T, the value of e is T is true; otherwise, it is false.

The following example demonstrates the use of the is operator:

open class Base {
    var name: String = "Alice"
}
class Derived <: Base {
    var age: UInt8 = 18
}

main() {
    let a = 1 is Int64
    println("Is the type of 1 'Int64'? ${a}")
    let b = 1 is String
    println("Is the type of 1 'String'? ${b}")

    let b1: Base = Base()
    let b2: Base = Derived()
    var x = b1 is Base
    println("Is the type of b1 'Base'? ${x}")
    x = b1 is Derived
    println("Is the type of b1 'Derived'? ${x}")
    x = b2 is Base
    println("Is the type of b2 'Base'? ${x}")
    x = b2 is Derived
    println("Is the type of b2 'Derived'? ${x}")
}

The execution result of the above code is:

Is the type of 1 'Int64'? true
Is the type of 1 'String'? false
Is the type of b1 'Base'? true
Is the type of b1 'Derived'? false
Is the type of b2 'Base'? true
Is the type of b2 'Derived'? true

The as operator can be used to convert the type of an expression to the specified type. Since type conversion may fail, the as operator returns an Option type. Specifically, for the expression e as T (where e can be any expression and T can be any type), when the runtime type of e is a subtype of T, the value of e as T is Option<T>.Some(e); otherwise, it is Option<T>.None.

The following example demonstrates the use of the as operator (comments indicate the results of the as operation):

open class Base {
    var name: String = "Alice"
}
class Derived <: Base {
    var age: UInt8 = 18
}

let a = 1 as Int64     // a = Option<Int64>.Some(1)
let b = 1 as String    // b = Option<String>.None

let b1: Base = Base()
let b2: Base = Derived()
let d: Derived = Derived()
let r1 = b1 as Base    // r1 = Option<Base>.Some(b1)
let r2 = b1 as Derived // r2 = Option<Derived>.None
let r3 = b2 as Base    // r3 = Option<Base>.Some(b2)
let r4 = b2 as Derived // r4 = Option<Derived>.Some(b2)
let r5 = d as Base     // r5 = Option<Base>.Some(d)
let r6 = d as Derived  // r6 = Option<Derived>.Some(d)

Generics Overview

In the Cangjie programming language, generics refer to parameterized types, where a parameterized type is one that is unknown at declaration time and must be specified upon usage. Both type declarations and function declarations can be generic. The most common examples are container types such as Array<T> and Set<T>.

In Cangjie, declarations of function, class, interface, struct, and enum can all declare type parameters, meaning they can all be generic.

For ease of discussion, the following commonly used terms are defined:

• Type Parameter: A type or function declaration may have one or more types that need to be specified at the point of use. These types are referred to as type parameters. When declaring a parameter, an identifier must be provided for reference within the declaration body.
• Type Variable: After declaring a type parameter, when these types are referenced via identifiers, these identifiers are called type variables.
• Type Argument: When specifying generic parameters while using a generic type or function, these parameters are called type arguments.
• Type Constructor: A type that requires zero, one, or more types as arguments is called a type constructor.

Type parameters are generally declared after the type name or function name, enclosed in angle brackets <...>. For example, a generic list can be declared as:

class List<T> {
    var elem: Option<T> = None
    var tail: Option<List<T>> = None
}

func sumInt(a: List<Int64>) {  }

Here, T in List<T> is called a type parameter. The reference to T in elem: Option<T> is called a type variable, and similarly, T in tail: Option<List<T>> is also a type variable. In the parameter of the function sumInt, Int64 in List<Int64> is called the type argument for List. List is the type constructor, and List<Int64> constructs a list type for Int64 using the type argument Int64.

Generic Functions

A function is called a generic function if it declares one or more type parameters. Syntactically, type parameters are placed immediately after the function name, enclosed in <>, and separated by , if there are multiple type parameters.

Global Generic Functions

When declaring a global generic function, simply declare the type parameters using angle brackets after the function name. These type parameters can then be referenced in the function parameters, return type, and function body. For example, the id function is defined as:

func id<T>(a: T): T {
    return a
}

Here, (a: T) is the function parameter declaration, which uses the type parameter T declared by the id function, and the return type of id also utilizes this type parameter.

Another more complex example is the generic function composition, which declares three type parameters T1, T2, T3. Its functionality is to compose two functions f: (T1) -> T2 and g: (T2) -> T3 into a function of type (T1) -> T3.

func composition<T1, T2, T3>(f: (T1) -> T2, g: (T2) -> T3): (T1) -> T3 {
    return {x: T1 => g(f(x))}
}

Since the functions that can be composed can be of any type (e.g., composition of (Int32) -> Bool and (Bool) -> Int64, or (Int64) -> Rune and (Rune) -> Int8), generic functions are necessary.

func times2(a: Int64): Int64 {
    return a * 2
}

func plus10(a: Int64): Int64 {
    return a + 10
}

func times2plus10(a: Int64) {
    return composition<Int64, Int64, Int64>(times2, plus10)(a)
}

main() {
  println(times2plus10(9))
}

Here, composing two (Int64) -> Int64 functions first multiplies 9 by 2 and then adds 10, resulting in 28.

28

Local Generic Functions

Local functions can also be generic. For example, the generic function id can be nested within other functions:

func foo(a: Int64) {
    func id<T>(a: T): T { a }

    func double(a: Int64): Int64 { a + a }

    return (id<Int64> ~> double)(a) == (double ~> id<Int64>)(a)
}

main() {
    println(foo(1))
}

Due to the identity property of id, the functions id<Int64> ~> double and double ~> id<Int64> are equivalent, resulting in true.

true

Generic Member Functions

Member functions of classes, structs, and enums can be generic. For example:

class A {
    func foo<T>(a: T): Unit where T <: ToString {
        println("${a}")
    }
}

struct B {
    func bar<T>(a: T): Unit where T <: ToString {
        println("${a}")
    }
}

enum C {
    | X | Y

    func coo<T>(a: T): Unit where T <: ToString {
        println("${a}")
    }
}

main() {
    var a = A()
    var b = B()
    var c = C.X
    a.foo<Int64>(10)
    b.bar<String>("abc")
    c.coo<Bool>(false)
}

The program output will be:

10
abc
false

When extending types using the extend declaration, the functions within the extension can also be generic. For example, we can add a generic member function to the Int64 type:

extend Int64 {
    func printIntAndArg<T>(a: T) where T <: ToString {
        println(this)
        println("${a}")
    }
}

main() {
    var a: Int64 = 12
    a.printIntAndArg<String>("twelve")
}

The program output will be:

12
twelve

Static Generic Functions

Interfaces, classes, structs, enums, and extensions can define static generic functions. For example, the following ToPair class returns a tuple from an ArrayList:

import std.collection.ArrayList

class ToPair {
    public static func fromArray<T>(l: ArrayList<T>): (T, T) {
        return (l[0], l[1])
    }
}

main() {
    var res: ArrayList<Int64> = ArrayList([1,2,3,4])
    var a: (Int64, Int64) = ToPair.fromArray<Int64>(res)
}

Generic Interfaces

Generics can be used to define generic interfaces. Taking the Iterable interface from the standard library as an example, its member function iterator needs to return an Iterator type, which serves as a container’s traverser. Iterator is a generic interface that contains a next member function for retrieving the next element from the container type. The return type of the next member function is a type that needs to be specified during usage, so Iterator requires the declaration of generic parameters.

public interface Iterable<E> {
    func iterator(): Iterator<E>
}

public interface Iterator<E> <: Iterable<E> {
    func next(): Option<E>
}

public interface Collection<T> <: Iterable<T> {
     prop size: Int64
     func isEmpty(): Bool
}

Generic Classes

Generic Interfaces introduced the definition and usage of generic interfaces. This section covers the definition and usage of generic classes. For example, the key-value pairs in Map are defined using generic classes.

The Node type for key-value pairs in Map can be defined using a generic class:

open class Node<K, V> where K <: Hashable & Equatable<K> {
    var key: Option<K> = Option<K>.None
    var value: Option<V> = Option<V>.None

    init() {}

    init(key: K, value: V) {
        this.key = Option<K>.Some(key)
        this.value = Option<V>.Some(value)
    }
}

Since the types of keys and values may differ and can be any type that meets certain conditions, the Node class requires two type parameters K and V. The constraint K <: Hashable, K <: Equatable<K> specifies that the key type K must implement both the Hashable and Equatable<K> interfaces, which are the conditions K must satisfy. For more details on generic constraints, refer to the Generic Constraints section.

Because static member variables of generic classes share memory, the type declarations and expressions of static member variables or properties cannot reference type parameters or contain uninstantiated generic type expressions. Additionally, static variable or property initialization expressions cannot call static member functions or properties of generic classes.

class A<T> {}
class B<T> {
    static func foo() {1}
    static var err1: A<T> = A<T>() // Error, static member cannot depend on generic parameter 'Generics-T'
    static prop err2: A<T> { // Error, static member cannot depend on generic parameter 'Generics-T'
        get() {
            A<T>() // Error, static member cannot depend on generic parameter 'Generics-T'
        }
    }
    static var vfoo = foo() // Error, it's equal to 'static var vfoo = B<T>.foo()', implicit reference to generic 'T'.
    static var ok: Int64 = 1
}

main() {
    B<Int32>.ok = 2
    println(B<Int64>.ok) // 2
}

Generic Structs

Generic struct types are similar to classes. Below is an example of using a struct to define a binary tuple-like type:

struct Pair<T, U> {
    let x: T
    let y: U
    public init(a: T, b: U) {
        x = a
        y = b
    }
    public func first(): T {
        return x
    }
    public func second(): U {
        return y
    }
}

main() {
    var a: Pair<String, Int64> = Pair<String, Int64>("hello", 0)
    println(a.first())
    println(a.second())
}

The program output is:

hello
0

The Pair struct provides two functions first and second to retrieve the first and second elements of the tuple respectively.

Generic Enums

In the design of generic enum types in the Cangjie programming language, the Option type serves as a classic example. For a detailed description of Option, please refer to the Option Type chapter. The Option type is used to represent a value that may be empty for a certain type. Thus, Option can indicate computational failure for a particular type. Since the specific type of failure is indeterminate, it’s evident that Option is a generic type requiring the declaration of type parameters.

package std.core // `Option` is defined in std.core.

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

    public func getOrThrow(): T {
        match (this) {
            case Some(v) => v
            case None => throw NoneValueException()
        }
    }
    // ...
}

As shown, Option<T> has two variants: Some(T), which represents a successful return value, and None, which indicates an empty result. The getOrThrow function extracts the inner value from Some(T), returning a result of type T. If the parameter is None, it directly throws an exception.

For example, to define a safe division operation (since division computations may fail), we can return None when the divisor is 0, otherwise returning a result wrapped in Some:

func safeDiv(a: Int64, b: Int64): Option<Int64> {
    var res: Option<Int64> = match (b) {
                case 0 => None
                case _ => Some(a/b)
            }
    return res
}

This approach ensures the program won’t throw arithmetic exceptions during runtime when encountering division by zero.

Subtyping Relationships of Generic Types

Instantiated generic types also have subtyping relationships. For example:

interface I<X, Y> { }

class C<Z> <: I<Z, Z> { }

Based on class C<Z> <: I<Z, Z> { }, we know that C<Bool> <: I<Bool, Bool> and C<D> <: I<D, D> hold, among others. This can be interpreted as “For all types Z without type variables, C<Z> <: I<Z, Z> holds.”

However, for the following code:

open class C { }
class D <: C { }

interface I<X> { }

I<D> <: I<C> does not hold (even though D <: C holds). This is because in the Cangjie language, user-defined type constructors are invariant at their type parameters.

The formal definition of variance is: If A and B are (instantiated) types, and T is a type constructor with a type parameter X (e.g., interface T<X>), then:

• If T(A) <: T(B) if and only if A = B, then T is invariant.
• If T(A) <: T(B) if and only if A <: B, then T is covariant at X.
• If T(A) <: T(B) if and only if B <: A, then T is contravariant at X.

In the current version of Cangjie, all user-defined generic types are invariant at all their type parameters. Therefore, given interface I<X> and types A, B, I<A> <: I<B> holds only if A = B. Conversely, if I<A> <: I<B> is known, we can deduce A = B (with the exception of built-in types: built-in tuple types are covariant at each of their element types; built-in function types are contravariant at their parameter types and covariant at their return types.)

Note:

For types other than class that implement interfaces, the subtyping relationship between the type and the interface cannot serve as a basis for covariance or contravariance.

Invariance limits some expressive power of the language but also avoids certain safety issues, such as the “covariant array runtime exception” problem.

Type Aliases

When a type name is overly complex or not intuitive in a specific context, you can use a type alias to assign an alternative name to that type.

type I64 = Int64

A type alias definition begins with the keyword type, followed by the alias name (e.g., I64 in the example above), then an equals sign =, and finally the original type (i.e., the type being aliased, such as Int64 in the example above).

Type aliases can only be defined at the top level of a source file, and the original type must be visible at the point of alias definition. For example, in the following code, the alias definition for Int64 within main will result in an error, and the type LongNameClassB is not visible when defining its alias, which will also cause an error.

main() {
    type I64 = Int64 // Error, type aliases can only be defined at the top level of the source file
}

class LongNameClassA { }
type B = LongNameClassB // Error, type 'LongNameClassB' is not defined

Direct or indirect circular references are prohibited in one or more type alias definitions.

type A = (Int64, A) // Error, 'A' refered itself
type B = (Int64, C) // Error, 'B' and 'C' are circularly refered
type C = (B, Int64)

A type alias does not define a new type; it merely provides another name for the original type. It can be used in the following scenarios:

1. 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 actually refers to a class or struct, it can be used as a constructor name:

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

3. When the type alias actually refers to a class, interface, or struct, it can be used as the type name to access internal static member variables 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 actually refers to an enum, it can be used as the type name for the enum’s constructors:

   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
   

Note that currently, user-defined type aliases are not supported in type conversion expressions. Refer to the following example:

type MyInt = Int32
MyInt(0)  // Error, no matching function for operator '()' function call

Generic Type Aliases

Type aliases can also declare type parameters, but constraints cannot be applied to these parameters using where clauses. Constraints for generic type arguments will be explained later.

When a generic type name is too long, a type alias can be used to declare a shorter alternative. For example, a type RecordData can be abbreviated as RD using a type alias:

struct RecordData<T> {
    var a: T
    public init(x: T) {
        a = x
    }
}

type RD<T> = RecordData<T>

main(): Int64 {
    var struct1: RD<Int32> = RecordData<Int32>(2)
    return 1
}

In usage, RD<Int32> can be used to refer to the RecordData<Int32> type.

Generic Constraints

The purpose of generic constraints is to specify the operations and capabilities that generic type parameters must possess when declaring functions, classes, interfaces, structs, or enums. Only by declaring these constraints can corresponding member functions be called. In many scenarios, generic type parameters need to be constrained. Take the id function as an example:

func id<T>(a: T) {
    return a
}

The only thing the developer can do is return the function parameter a, but cannot perform operations like a + 1 or println("${a}") because it could be any type, such as (Bool) -> Bool, which cannot be added to an integer. Similarly, since it’s a function type, it cannot be printed to the command line via the println function. However, if constraints are applied to this generic type parameter, more operations become possible.

Constraints are broadly divided into interface constraints and class type constraints. Before the declaration body of a function or type, the where keyword can be used to declare generic constraints. For declared generic type parameters T1, T2, constraints can be specified using syntax like where T1 <: Interface, T2 <: Class. If multiple constraints apply to the same type parameter, they can be connected with &, e.g., where T1 <: Interface1 & Interface2.

In Cangjie, the println function can accept parameters of type string. If you need to print a generic type variable as a string on the command line, you can constrain this generic type parameter with the ToString interface defined in core, which is clearly an interface constraint:

package std.core // `ToString` is defined in core.

public interface ToString {
    func toString(): String
}

This allows you to define a function named genericPrint using this constraint:

func genericPrint<T>(a: T) where T <: ToString {
    println(a)
}

main() {
    genericPrint<Int64>(10)
}

The result is:

10

If the type argument for the genericPrint function does not implement the ToString interface, the compiler will report an error. For example, when passing a function as a parameter:

func genericPrint<T>(a: T) where T <: ToString {
    println(a)
}

main() {
    genericPrint<(Int64) -> Int64>({ i => 0 })
}

If you compile the above file, the compiler will throw an error indicating that the generic type argument does not satisfy the constraint, because the type argument (Int64) -> Int64 does not satisfy (Int64) -> Int64 <: ToString.

In addition to interface-based constraints, class types can also be used to constrain generic type parameters. For example, when declaring a zoo type Zoo<T>, you might want the type parameter T to be constrained to subtypes of the Animal class, where Animal declares a run member function. Here, two subtypes Dog and Fox both implement the run member function, allowing instances stored in the animals array list within Zoo<T> to call the run member function:

import std.collection.ArrayList

abstract class Animal {
    public func run(): String
}

class Dog <: Animal {
    public func run(): String {
        return "dog run"
    }
}

class Fox <: Animal {
    public func run(): String {
        return "fox run"
    }
}

class Zoo<T> where T <: Animal {
    var animals: ArrayList<Animal> = ArrayList<Animal>()
    public func addAnimal(a: T) {
        animals.add(a)
    }

    public func allAnimalRuns() {
        for(a in animals) {
            println(a.run())
        }
    }
}

main() {
    var zoo: Zoo<Animal> = Zoo<Animal>()
    zoo.addAnimal(Dog())
    zoo.addAnimal(Fox())
    zoo.allAnimalRuns()
}

The program output is:

dog run
fox run

Note:

Constraints for generic type parameters can only be concrete class types or interfaces. If a type parameter has multiple class-type upper bounds, they must be in the same inheritance chain.

Extension Overview

Extensions can add new functionality to types (excluding functions, tuples, and interfaces) that are visible within the current package.

Extensions are used when you need to add additional functionality without breaking the encapsulation of the extended type.

The functionalities that can be added include:

• Adding member functions
• Adding operator overload functions
• Adding member properties
• Implementing interfaces

For specific examples of how to add the above functionalities, refer to the following example. For detailed syntax usage, please see subsequent sections:

interface Foo {
    func printValue(a: Int64): Unit
}

class Boo {
    var boo: Int64 = 2
}

extend Boo {
    public prop x: Int64 { // Adding a member property
        get() {
            123
        }
    }

    func newMember(): Unit {
        println("This is a member function of a new extension.") // Adding a member function
    }

    public operator func -() {
        println("Overload the operator addition function.") // Adding an operator overload function
        -x
    }
}

// Interface extension, implementing an interface
extend<T> Array<T> <: Foo {
    public func printValue(a: Int64) {
        println("The is ${a}.")
    }
}

Although extensions can add extra functionality, they cannot alter the encapsulation of the extended type. Therefore, extensions do not support the following functionalities:

1. Extensions cannot add member variables.
2. Functions and properties in extensions must have implementations.
3. Functions and properties in extensions cannot be modified with open, override, or redef.
4. Extensions cannot access members modified with private in the extended type.

Based on whether an extension implements a new interface, extensions can be divided into two usage types: direct extensions and interface extensions. A direct extension does not include additional interfaces, while an interface extension includes interfaces. Interface extensions can be used to add new functionality to existing types and implement interfaces, enhancing abstract flexibility.

Direct Extension

A simple example of extension syntax is as follows:

extend String {
    public func printSize() {
        println("the size is ${this.size}")
    }
}

As shown in the example above, extensions are declared using the extend keyword, followed by the extended type String and the extended functionality.

After extending the String type with the printSize function, instances of String within the current package can access this function as if it were native to String.

main() {
    let a = "123"
    a.printSize() // the size is 3
}

Compiling and executing the above code yields the output:

the size is 3

When extending generic types, there are two syntax approaches for adding functionality.

The first approach extends specific instantiated generic types. The extend keyword can be followed by any fully instantiated generic type. The added functionality is only available when the type exactly matches, and the type arguments must satisfy the constraints defined in the generic type declaration.

For example, consider Foo<T> below:

class Foo<T> where T <: ToString {}

extend Foo<Int64> {} // OK

class Bar {}
extend Foo<Bar> {} // Error, generics type arguments do not match the constraint of 'Class-Foo<Generics-T>'

The second approach uses generic extension by introducing type parameters after extend. Generic extensions can extend uninstantiated or partially instantiated generic types. The type parameters declared after extend must be directly or indirectly used in the extended generic type. The added functionality is only available when both the type and constraints fully match.

For example, consider MyList<T> below:

class MyList<T> {
    public let data: Array<T> = Array<T>()
}

extend<T> MyList<T> {}          // OK
extend<R> MyList<R> {}          // OK
extend<T, R> MyList<(T, R)> {}  // OK
extend MyList {}                // Error, generic type should be used with type argument
extend<T, R> MyList<T> {}       // Error, type parameter 'R' must be used in extended type
extend<T, R> MyList<T, R> {}    // Error, type argument's number does not match type parameter's number

For generic type extensions, additional constraints can be declared to implement functions that are only available under specific conditions.

For example, we can define a type called Pair that conveniently stores two elements (similar to Tuple). We want the Pair type to accommodate any type, so the two generic parameters should have no constraints to ensure Pair can hold all types. However, we also want Pair to support equality comparison when both elements are comparable. This can be achieved using extensions.

As shown in the code below, the extension syntax constrains T1 and T2 to support the equals operation, enabling Pair to implement the equals function when these conditions are met.

class Pair<T1, T2> {
    var first: T1
    var second: T2
    public init(a: T1, b: T2) {
        first = a
        second = b
    }
}

interface Eq<T> {
    func equals(other: T): Bool
}

extend<T1, T2> Pair<T1, T2> where T1 <: Eq<T1>, T2 <: Eq<T2> {
    public func equals(other: Pair<T1, T2>) {
        first.equals(other.first) && second.equals(other.second)
    }
}

class Foo <: Eq<Foo> {
    public func equals(other: Foo): Bool {
        true
    }
}

main() {
    let a = Pair(Foo(), Foo())
    let b = Pair(Foo(), Foo())
    println(a.equals(b)) // true
}

Compiling and executing the above code yields the output:

true

Interface Extension

For example, in the following case, the type Array does not inherently implement the interface PrintSizeable. However, we can use extension to add an additional member function printSize to Array and implement PrintSizeable.

interface PrintSizeable {
    func printSize(): Unit
}

extend<T> Array<T> <: PrintSizeable {
    public func printSize() {
        println("The size is ${this.size}")
    }
}

After extending Array to implement PrintSizeable, it is equivalent to Array having implemented PrintSizeable at its definition time.

Therefore, Array can be used as an implementation type of PrintSizeable, as shown in the following code.

main() {
    let a: PrintSizeable = Array<Int64>()
    a.printSize() // 0
}

Compiling and executing the above code yields the output:

The size is 0

Multiple interfaces can be implemented simultaneously within the same extension. Separate the interfaces with &, and their order does not matter.

As shown in the following code, we can implement I1, I2, and I3 for Foo in a single extension.

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(): Unit {}
    public func f2(): Unit {}
    public func f3(): Unit {}
}

Additional generic constraints can also be declared in interface extensions to satisfy interfaces under specific conditions.

For example, we can make the Pair type implement the Eq interface, allowing Pair itself to become a type that satisfies the Eq constraint, as shown below.

class Pair<T1, T2> {
    var first: T1
    var second: T2
    public init(a: T1, b: T2) {
        first = a
        second = b
    }
}

interface Eq<T> {
    func equals(other: T): Bool
}

extend<T1, T2> Pair<T1, T2> <: Eq<Pair<T1, T2>> where T1 <: Eq<T1>, T2 <: Eq<T2> {
    public func equals(other: Pair<T1, T2>) {
        first.equals(other.first) && second.equals(other.second)
    }
}

class Foo <: Eq<Foo> {
    public func equals(other: Foo): Bool {
        true
    }
}

main() {
    let a = Pair(Foo(), Foo())
    let b = Pair(Foo(), Foo())
    println(a.equals(b)) // true
}

Compiling and executing the above code yields the output:

true

If the extended type already includes the functions or properties required by the interface, these functions or properties need not (and cannot) be re-implemented in the extension.

For example, in the following case, a new interface Sizeable is defined to retrieve the size of a type. Since Array already contains this function, we can extend Array to implement Sizeable without adding additional functions.

interface Sizeable {
    prop size: Int64
}

extend<T> Array<T> <: Sizeable {}

main() {
    let a: Sizeable = Array<Int64>()
    println(a.size)
}

Compiling and executing the above code yields the output:

0

When interface extensions implement interfaces with inheritance relationships, the extensions are checked in the order of “first checking extensions implementing parent interfaces, then checking extensions implementing child interfaces.”

For example, if interface I1 has a child interface I2, and I1 contains a default implementation, while type A has two extensions implementing the parent and child interfaces respectively, the extension implementing I1 will be checked first, followed by the extension implementing I2.

interface I1 {
    func foo(): Unit { println("I1 foo") }
}
interface I2 <: I1 {
    func foo(): Unit { println("I2 foo") }
}

class A {}

extend A <: I1 {} // first check
extend A <: I2 {} // second check

main() {
    A().foo()
}

Compiling and executing the above code yields the output:

I2 foo

In this example, when checking the extension implementing I1, the foo function is inherited from I1. When checking the extension implementing I2, since A already has an inherited default implementation of foo with the same signature, this foo will be overridden. Thus, when calling A’s foo function, it ultimately points to the implementation in I2 (the child interface).

If two interface extensions of the same type implement interfaces with conflicting inheritance relationships, making it impossible to determine the checking order, an error will be reported.

interface I1 {}
interface I2 <: I1 {}
interface I3 {}
interface I4 <: I3 {}

class A {}
extend A <: I1 & I4 {} // error: unable to decide which extension happens first
extend A <: I2 & I3 {} // error: unable to decide which extension happens first

If two interface extensions of the same type implement interfaces without inheritance relationships, they will be checked simultaneously.

interface I1 {
    func foo() {}
}
interface I2 {
    func foo() {}
}

class A {}
extend A <: I1 {} // Error, multiple default implementations, need to re-implement 'foo' in 'A'
extend A <: I2 {} // Error, multiple default implementations, need to re-implement 'foo' in 'A'

Note:

When class A has a generic base class B<T1,...,Tn>, and B<T1,...,Tn> extends an interface I<R1,...,Rn> with default implementations of instance or static functions (e.g., foo), if this function is not overridden in B<T1,...,Tn> or its extensions, and class A does not directly implement the interface I<R1,...,Rn>, calling the function foo through an instance of class A may lead to unexpected behavior.

interface I<N> {
    func foo(n: N): N {n}
}

open class B<T> {}

extend<T> B<T> <: I<T> {}

class A <: B<Int64>{}

main() {
    A().foo(0) // this call triggers unexpected behaviour
}

Access Rules

Extension Modifiers

Extensions themselves cannot be modified with modifiers.

For example, in the following example, using the public modifier before directly extending A will result in a compilation error.

public class A {}

public extend A {}  // Error, expected no modifier before extend

Modifiers that can be used for extension members include: static, public, protected, internal, private, mut.

• Members modified with private can only be used within the extension and are invisible externally.
• Members modified with internal can be used within the current package and its sub-packages (including sub-packages of sub-packages), which is the default behavior.
• Members modified with protected can be accessed within the current module (subject to export rules). When the extended type is a class, the subclass definition body of that class can also access them.
• Members modified with static can only be accessed via the type name and not through instance objects.
• Extensions for struct types can define mut functions.

package p1

public open class A {}

extend A {
    public func f1() {}
    protected func f2() {}
    private func f3() {}
    static func f4() {}
}

main() {
    A.f4()
    var a = A()
    a.f1()
    a.f2()
}

Member definitions within extensions do not support the use of open, override, or redef modifiers.

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
}

Orphan Rule for Extensions

Implementing an interface from another package for a type from a different package can cause confusion.

To prevent a type from accidentally implementing an inappropriate interface, Cangjie does not allow orphan extensions—i.e., extensions that are neither defined in the same package as the interface (including all interfaces in the interface inheritance chain) nor in the same package as the extended type.

As shown in the following code, you cannot implement Bar from package b for Foo from package a within package c.

You can only implement Bar for Foo in package a or package b.

// package a
public class Foo {}

// package b
public interface Bar {}

// package c
import a.Foo
import b.Bar

extend Foo <: Bar {} // Error

Access and Shadowing in Extensions

Instance members in extensions can use this just like in the type definition, and this functions the same way. this can also be omitted when accessing members. Instance members in extensions cannot use super.

class A {
    var v = 0
}

extend A {
    func f() {
        print(this.v) // OK
        print(v) // OK
    }
}

Extensions cannot access members modified with private in the extended type.

class A {
    private var v1 = 0
    protected var v2 = 0
}

extend A {
    func f() {
        print(v1) // Error
        print(v2) // OK
    }
}

Extensions cannot shadow any members of the extended type.

class A {
    func f() {}
}

extend A {
    func f() {} // Error
}

Extensions are also not allowed to shadow any members added by other extensions.

class A {}

extend A {
    func f() {}
}

extend A {
    func f() {} // Error
}

Within the same package, a type can be extended multiple times, and within an extension, you can directly call non-private functions from other extensions of the extended type.

class Foo {}

extend Foo { // OK
    private func f() {}
    func g() {}
}

extend Foo { // OK
    func h() {
        g() // OK
        f() // Error
    }
}

When extending generic types, additional generic constraints can be used. The visibility rules between any two extensions of a generic type are as follows:

• If two extensions have the same constraints, they are mutually visible—i.e., functions or properties from one extension can be directly used in the other.
• If two extensions have different constraints, and one constraint is a superset of the other, the extension with the looser constraint is visible to the one with the stricter constraint, but not vice versa.
• If two extensions have different constraints and the constraints are not subsets of each other, the extensions are mutually invisible.

Example: Suppose there are two extensions, extension 1 and extension 2, for the same type E<X>. If the constraint for X in extension 1 is stricter than in extension 2, then functions and properties in extension 1 are invisible to extension 2, but functions and properties in extension 2 are visible to extension 1.

open class A {}
class B <: A {}
class E<X> {}

interface I1 {
    func f1(): Unit
}
interface I2 {
    func f2(): Unit
}

extend<X> E<X> <: I1 where X <: B {  // extension 1
    public func f1(): Unit {
        f2() // OK
    }
}

extend<X> E<X> <: I2 where X <: A   { // extension 2
    public func f2(): Unit {
        f1() // Error
    }
}

Import and Export of Extensions

Extensions can also be imported and exported, but extensions themselves cannot be modified with visibility modifiers. The export of extensions follows special rules.

For direct extensions, when the extension and the extended type are in the same package, whether the extension is exported is determined by the access modifiers of both the extended type and the generic constraints (if any). When all generic constraints are exported types (for modifier and export rules, see the Top-Level Declaration Visibility chapter), the extension will be exported. When the extension and the extended type are in different packages, the extension will not be exported.

As shown in the following code, Foo is exported. The extension containing the f1 function is not exported because its generic constraint is not exported. The extensions containing f2 and f3 functions are exported because their generic constraints are exported. The extension containing the f4 function is not exported because one of its generic constraints, I1, is not exported. The extension containing the f5 function is exported because all its generic constraints are exported.

// package a.b
package a.b

private interface I1 {}
internal interface I2 {}
protected interface I3 {}

extend Int64 <: I1 & I2 & I3 {}

public class Foo<T> {}
// The extension will not be exported
extend<T> Foo<T> where T <: I1 {
    public func f1() {}
}
// The extension will be exported, and only packages that import both Foo and I2 will be able to access it.
extend<T> Foo<T> where T <: I2 {
    public func f2() {}
}
// The extension will be exported, and only packages that import both Foo and I3 will be able to access it.
extend<T> Foo<T> where T <: I3 {
    public func f3() {}
}
// The extension will not be exported. The I1 with the lowest access level determines the export.
extend<T> Foo<T> where T <: I1 & I2 & I3 {
    public func f4() {}
}
// The extension is exported. Only the package that imports Foo, I2, and I3 can access the extension.
extend<T> Foo<T> where T <: I2 & I3 {
    public func f5() {}
}

// package a.c
package a.c
import a.b.*

main() {
    Foo<Int64>().f1() // Cannot access.
    Foo<Int64>().f2() // Cannot access. Visible only for sub-pkg.
    Foo<Int64>().f3() // OK.
    Foo<Int64>().f4() // Cannot access.
    Foo<Int64>().f5() // Cannot access. Visible only for sub-pkg.
}

// package a.b.d
package a.b.d
import a.b.*

main() {
    Foo<Int64>().f1() // Cannot access.
    Foo<Int64>().f2() // OK.
    Foo<Int64>().f3() // OK.
    Foo<Int64>().f4() // Cannot access.
    Foo<Int64>().f5() // OK.
}

For interface extensions, there are two scenarios:

1. When the interface extension and the extended type are in the same package, the extension will be exported along with the extended type and generic constraints (if any), regardless of the interface type’s access level. Packages outside do not need to import the interface type to access the extension’s members.
2. When the interface extension and the extended type are in different packages, whether the extension is exported is determined by the lowest access level among the interface type and the generic constraints (if any). Other packages must import the extended type, the corresponding interface, and any constraint types (if applicable) to access the extension members of the interface.

As shown in the following code, in package a, even though the interface access modifier is private, the extension for Foo will still be exported.

// package a
package a

private interface I0 {}

public class Foo<T> {}

// The extension is exported.
extend<T> Foo<T> <: I0 {}

When extending the Foo type in another package, whether the extension is exported depends on the access modifiers of the implemented interface and generic constraints. The extension will be exported if at least one implemented interface is exported and all generic constraints are exportable.

// package b
package b
import a.Foo

private interface I1 {}
internal interface I2 {}
protected interface I3 {}
public interface I4 {}

// The extension will not be exported because I1 is not visible outside the file.
extend<T> Foo<T> <: I1 {}

// The extension is exported.
extend<T> Foo<T> <: I2 {}

// The extension is exported.
extend<T> Foo<T> <: I3 {}

// The extension is exported
extend<T> Foo<T> <: I1 & I2 & I3 {}

// The extension will not be exported. The I1 with the lowest access level determines the export.
extend<T> Foo<T> <: I4 where T <: I1 & I2 & I3 {}

// The extension is exported.
extend<T> Foo<T> <: I4 where T <: I2 & I3 {}

// The extension is exported.
extend<T> Foo<T> <: I4 & I3 where T <: I2 {}

Specifically, the exported members of interface extensions are limited to those contained within the interfaces.

// package a
package a

public class Foo {}

// package b
package b

import a.Foo

public interface I1 {
    func f1(): Unit
}

public interface I2 {
    func f2(): Unit
}

extend Foo <: I1 & I2 {
    public func f1(): Unit {}
    public func f2(): Unit {}
    public func f3(): Unit {} // f3 will not be exported
}

// package c
package c

import a.Foo
import b.I1

main() {
    let x: Foo = Foo()
    x.f1() // OK, because f1 is a member of I1.
    x.f2() // error, I2 is not imported
    x.f3() // error, f3 not found
}

Similar to the export of extensions, importing extensions does not require explicit import statements. To import all accessible extensions, one only needs to import the extended type, interfaces, and generic constraints (if any).

As shown in the following code, in package b, importing Foo alone is sufficient to use the function f from the corresponding extension of Foo.

For interface extensions, it is necessary to import both the extended type and the extended interfaces (plus generic constraints if present) to use them. Therefore, in package c, both Foo and I must be imported to use the function g from the corresponding extension.

// package a
package a
public class Foo {}
extend Foo {
    public func f() {}
}

// package b
package b
import a.Foo

public interface I {
    func g(): Unit
}
extend Foo <: I {
    public func g() {
        this.f() // OK
    }
}

// package c
package c
import a.Foo
import b.I

func test() {
    let a = Foo()
    a.f() // OK
    a.g() // OK
}

Overview of Basic Collection Types

This chapter introduces several fundamental Collection types commonly used in the Cangjie language, including Array, ArrayList, HashSet, and HashMap.

You can choose the appropriate type for specific business scenarios:

• Array: When you don’t need to add or remove elements but require element modification
• ArrayList: When frequent element insertion, deletion, querying, and modification are needed
• HashSet: When you want each element to be unique
• HashMap: When you need to store a series of key-value mappings

The following table summarizes the basic characteristics of these types:

ArrayList

To use the ArrayList type, you need to import the collection package:

import std.collection.*

In Cangjie, ArrayList<T> represents the ArrayList type, where T denotes the element type of the ArrayList, which can be any type.

ArrayList has excellent expansion capabilities, making it suitable for scenarios requiring frequent addition and deletion of elements.

Compared to Array, ArrayList allows both in-place modification of elements and in-place addition/deletion of elements.

The mutability of ArrayList is a highly useful feature, enabling all references to the same ArrayList instance to share the same elements and apply unified modifications.

var a: ArrayList<Int64> = ... // ArrayList whose element type is Int64
var b: ArrayList<String> = ... // ArrayList whose element type is String

ArrayLists with different element types are distinct types and therefore cannot be assigned to each other.

Thus, the following example is invalid:

b = a // Type mismatch

In Cangjie, you can construct a specific ArrayList using constructors.

let a = ArrayList<String>() // Created an empty ArrayList whose element type is String
let b = ArrayList<String>(100) // Created an ArrayList whose element type is String, and allocate a space of 100
let c = ArrayList<Int64>([0, 1, 2]) // Created an ArrayList whose element type is Int64, containing elements 0, 1, 2
let d = ArrayList<Int64>(c) // Use another Collection to initialize an ArrayList
let e = ArrayList<String>(2, {x: Int64 => x.toString()}) // Created an ArrayList whose element type is String and size is 2. All elements are initialized by specified rule function

Accessing ArrayList Members

When you need to access all elements of an ArrayList, you can use a for-in loop to iterate through them.

import std.collection.ArrayList

main() {
    let list = ArrayList<Int64>([0, 1, 2])
    for (i in list) {
        println("The element is ${i}")
    }
}

Compiling and executing the above code will output:

The element is 0
The element is 1
The element is 2

To determine the number of elements in an ArrayList, you can use the size property.

import std.collection.ArrayList

main() {
    let list = ArrayList<Int64>([0, 1, 2])
    if (list.size == 0) {
        println("This is an empty arraylist")
    } else {
        println("The size of arraylist is ${list.size}")
    }
}

Compiling and executing the above code will output:

The size of arraylist is 3

To access a single element at a specified position, you can use subscript syntax (the subscript must be of type Int64). The first element of a non-empty ArrayList always starts at position 0. You can access any element from 0 up to the last position (ArrayList’s size - 1). Using a negative index or an index greater than or equal to the size will trigger a runtime exception.

let a = list[0] // a == 0
let b = list[1] // b == 1
let c = list[-1] // Runtime exceptions

ArrayList also supports Range syntax in subscripts. For details, refer to the Array chapter.

Modifying ArrayList

You can use subscript syntax to modify elements at specific positions.

let list = ArrayList<Int64>([0, 1, 2])
list[0] = 3

ArrayList is a reference type. When used as an expression, ArrayList does not create a copy; all references to the same ArrayList instance share the same data.

Thus, modifications to ArrayList elements affect all references to that instance.

let list1 = ArrayList<Int64>([0, 1, 2])
let list2 = list1
list2[0] = 3
// list1 contains elements 3, 1, 2
// list2 contains elements 3, 1, 2

To add a single element to the end of an ArrayList, use the add function. To add multiple elements simultaneously, use the add(all!: Collection<T>) function, which accepts other Collection types with the same element type, such as Array. For details on Collection types, refer to Basic Collection Type Overview.

import std.collection.ArrayList

main() {
    let list = ArrayList<Int64>()
    list.add(0) // list contains element 0
    list.add(1) // list contains elements 0, 1
    let li = [2, 3]
    list.add(all: li) // list contains elements 0, 1, 2, 3
}

You can use the add(T, at!: Int64) and add(all!: Collection<T>, at!: Int64) functions to insert a single element or a Collection of the same element type at a specified index. The element at that index and subsequent elements will be shifted to make space.

let list = ArrayList<Int64>([0, 1, 2]) // list contains elements 0, 1, 2
list.add(4, at: 1) // list contains elements 0, 4, 1, 2

To remove an element from an ArrayList, use the remove function, specifying the index to remove. Subsequent elements will be shifted forward to fill the gap.

let list = ArrayList<String>(["a", "b", "c", "d"]) // list contains the elements "a", "b", "c", "d"
list.remove(at: 1) // Delete the element at subscript 1, now the list contains elements "a", "c", "d"

Increasing ArrayList Size

Each ArrayList requires a specific amount of memory to store its contents. When adding elements to an ArrayList causes it to exceed its reserved capacity, the ArrayList allocates a larger memory region and copies all elements to the new memory. This growth strategy means that add operations triggering reallocation incur performance costs, but as the ArrayList’s reserved memory grows larger, these operations occur less frequently.

If you know approximately how many elements you’ll be adding, you can pre-allocate sufficient memory before adding to avoid intermediate reallocations, thereby improving performance.

import std.collection.ArrayList

main() {
    let list = ArrayList<Int64>(100) // Allocate space at once
    for (i in 0..100) {
        list.add(i) // Does not trigger reallocation of space
    }
    list.reserve(100) // Prepare more space
    for (i in 0..100) {
        list.add(i) // Does not trigger reallocation of space
    }
}

HashSet

To use the HashSet type, you need to import the collection package:

import std.collection.*

You can use the HashSet type to construct a Collection that contains only unique elements.

Cangjie uses HashSet<T> to represent the HashSet type, where T denotes the element type of the HashSet. T must be a type that implements both the Hashable and Equatable<T> interfaces, such as numeric values or String.

var a: HashSet<Int64> = ... // HashSet whose element type is Int64
var b: HashSet<String> = ... // HashSet whose element type is String

HashSets with different element types are distinct types, so they cannot be assigned to each other.

Therefore, the following example is invalid:

b = a // Type mismatch

In Cangjie, you can construct a specific HashSet using constructor methods.

let a = HashSet<String>() // Created an empty HashSet whose element type is String
let b = HashSet<String>(100) // Created a HashSet whose capacity is 100
let c = HashSet<Int64>([0, 1, 2]) // Created a HashSet whose element type is Int64, containing elements 0, 1, 2
let d = HashSet<Int64>(c) // Use another Collection to initialize a HashSet
let e = HashSet<Int64>(10, {x: Int64 => (x * x)}) // Created a HashSet whose element type is Int64 and size is 10. All elements are initialized by specified rule function

Accessing HashSet Members

When you need to access all elements of a HashSet, you can use a for-in loop to iterate through all elements.

Note that HashSet does not guarantee element ordering based on insertion sequence, so traversal order may differ from insertion order.

import std.collection.*

main() {
    let mySet = HashSet<Int64>([0, 1, 2])
    for (i in mySet) {
        println("The element is ${i}")
    }
}

Compiling and executing the above code might output:

The element is 0
The element is 1
The element is 2

To determine the number of elements in a HashSet, use the size property.

import std.collection.*

main() {
    let mySet = HashSet<Int64>([0, 1, 2])
    if (mySet.size == 0) {
        println("This is an empty hashset")
    } else {
        println("The size of hashset is ${mySet.size}")
    }
}

Compiling and executing the above code will output:

The size of hashset is 3

To check if an element exists in a HashSet, use the contains function. It returns true if the element exists, otherwise false.

let mySet = HashSet<Int64>([0, 1, 2])
let a = mySet.contains(0) // a == true
let b = mySet.contains(-1) // b == false

Modifying HashSet

HashSet is a mutable reference type that provides functionality for adding and removing elements.

The mutability of HashSet is a useful feature, allowing all references to the same HashSet instance to share the same elements and receive unified modifications.

To add a single element to a HashSet, use the add function. To add multiple elements simultaneously, use the add(all!: Collection<T>) function, which accepts another Collection type (such as Array) with the same element type. When the element doesn’t exist, the add function performs the addition; when the element already exists in the HashSet, the add function has no effect.

let mySet = HashSet<Int64>()
mySet.add(0) // mySet contains elements 0
mySet.add(0) // mySet contains elements 0
mySet.add(1) // mySet contains elements 0, 1
let li = [2, 3]
mySet.add(all: li) // mySet contains elements 0, 1, 2, 3

HashSet is a reference type. When used as an expression, HashSet doesn’t create copies—all references to the same HashSet instance share the same data.

Therefore, modifications to HashSet elements affect all references to that instance.

let set1 = HashSet<Int64>([0, 1, 2])
let set2 = set1
set2.add(3)
// set1 contains elements 0, 1, 2, 3
// set2 contains elements 0, 1, 2, 3

To remove elements from a HashSet, use the remove function, specifying the element to be removed.

let mySet = HashSet<Int64>([0, 1, 2, 3])
mySet.remove(1) // mySet contains elements 0, 2, 3

HashMap

To use the HashMap type, you need to import the collection package:

import std.collection.*

You can use the HashMap type to construct a Collection of key-value pairs.

HashMap is a hash table that provides fast access to its contained elements. Each element in the table is identified by its key, and the corresponding value can be accessed using the key.

Cangjie uses HashMap<K, V> to represent the HashMap type, where K denotes the key type of the HashMap. K must be a type that implements both the Hashable and Equatable<K> interfaces, such as numeric types or String. V denotes the value type of the HashMap, which can be any type.

var a: HashMap<Int64, Int64> = ... // HashMap whose key type is Int64 and value type is Int64
var b: HashMap<String, Int64> = ... // HashMap whose key type is String and value type is Int64

HashMaps with different element types are considered distinct types, so they cannot be assigned to each other.

Therefore, the following example is invalid:

b = a // Type mismatch

In Cangjie, you can construct a specific HashMap using constructors.

let a = HashMap<String, Int64>() // Created an empty HashMap whose key type is String and value type is Int64
let b = HashMap<String, Int64>([("a", 0), ("b", 1), ("c", 2)]) // whose key type is String and value type is Int64, containing elements ("a", 0), ("b", 1), ("c", 2)
let c = HashMap<String, Int64>(b) // Use another Collection to initialize a HashMap
let d = HashMap<String, Int64>(10) // Created a HashMap whose key type is String and value type is Int64 and capacity is 10
let e = HashMap<Int64, Int64>(10, {x: Int64 => (x, x * x)}) // Created a HashMap whose key and value type is Int64 and size is 10. All elements are initialized by specified rule function

Accessing HashMap Members

When you need to access all elements of a HashMap, you can use a for-in loop to iterate through all elements.

Note that HashMap does not guarantee the order of elements based on insertion, so the traversal order may differ from the insertion order.

import std.collection.HashMap

main() {
    let map = HashMap<String, Int64>([("a", 0), ("b", 1), ("c", 2)])
    for ((k, v) in map) {
        println("The key is ${k}, the value is ${v}")
    }
}

Compiling and executing the above code might output:

The key is a, the value is 0
The key is b, the value is 1
The key is c, the value is 2

When you need to know the number of elements in a HashMap, you can use the size property to obtain this information.

import std.collection.HashMap

main() {
    let map = HashMap<String, Int64>([("a", 0), ("b", 1), ("c", 2)])
    if (map.size == 0) {
        println("This is an empty hashmap")
    } else {
        println("The size of hashmap is ${map.size}")
    }
}

Compiling and executing the above code will output:

The size of hashmap is 3

To check if a HashMap contains a specific key, you can use the contains function. It returns true if the key exists, otherwise false.

let map = HashMap<String, Int64>([("a", 0), ("b", 1), ("c", 2)])
let a = map.contains("a") // a == true
let b = map.contains("d") // b == false

To access the value associated with a specific key, you can use subscript syntax (the subscript type must match the key type). Using a non-existent key as an index will trigger a runtime exception.

let map = HashMap<String, Int64>([("a", 0), ("b", 1), ("c", 2)])
let a = map["a"] // a == 0
let b = map["b"] // b == 1
let c = map["d"] // Runtime exceptions

Modifying HashMap

HashMap is a mutable reference type that provides functionality to modify, add, and remove elements.

The mutability of HashMap is a highly useful feature, allowing all references to the same HashMap instance to share the same elements and apply modifications uniformly.

You can use subscript syntax to modify the value associated with a key.

let map = HashMap<String, Int64>([("a", 0), ("b", 1), ("c", 2)])
map["a"] = 3

HashMap is a reference type. When used as an expression, HashMap does not create a copy; all references to the same HashMap instance share the same data.

Therefore, modifications to HashMap elements will affect all references to that instance.

let map1 = HashMap<String, Int64>([("a", 0), ("b", 1), ("c", 2)])
let map2 = map1
map2["a"] = 3
// map1 contains the elements ("a", 3), ("b", 1), ("c", 2)
// map2 contains the elements ("a", 3), ("b", 1), ("c", 2)

To add a single key-value pair to a HashMap, use the add function. To add multiple key-value pairs simultaneously, use the add(all!: Collection<(K, V)>) function. If the key does not exist, the add function will perform an insertion. If the key exists, the add function will overwrite the old value with the new one.

let map = HashMap<String, Int64>()
map.add("a", 0) // map contains the element ("a", 0)
map.add("b", 1) // map contains the elements ("a", 0), ("b", 1)
let map2 = HashMap<String, Int64>([("c", 2), ("d", 3)])
map.add(all: map2) // map contains the elements ("a", 0), ("b", 1), ("c", 2), ("d", 3)

Alternatively, you can use assignment syntax to directly add new key-value pairs to a HashMap.

let map = HashMap<String, Int64>([("a", 0), ("b", 1), ("c", 2)])
map["d"] = 3 // map contains the elements ("a", 0), ("b", 1), ("c", 2), ("d", 3)

To remove an element from a HashMap, use the remove function and specify the key to be deleted.

let map = HashMap<String, Int64>([("a", 0), ("b", 1), ("c", 2), ("d", 3)])
map.remove("d") // map contains the elements ("a", 0), ("b", 1), ("c", 2)

Iterable and Collections

We have previously learned about Range, Array, and ArrayList, all of which can be traversed using for-in operations. For types defined by developers, similar traversal operations can also be implemented.

Range, Array, and ArrayList all support the for-in syntax through Iterable.

Iterable is a built-in interface with the following form (only core code is shown):

interface Iterable<T> {
    func iterator(): Iterator<T>
    ...
}

The iterator function requires the returned Iterator type to be another built-in interface with the following form (only core code is shown):

interface Iterator<T> <: Iterable<T> {
    mut func next(): Option<T>
    ...
}

You can use the for-in syntax to traverse any instance of a type that implements the Iterable interface.

Assume we have the following for-in code:

let list = [1, 2, 3]
for (i in list) {
    println(i)
}

It is equivalent to the following while code:

let list = [1, 2, 3]
var it = list.iterator()
while (true) {
    match (it.next()) {
        case Some(i) => println(i)
        case None => break
    }
}

Another common method for traversing Iterable types is to use pattern matching in the condition of a while expression. For example, another equivalent form of the above while code is:

let list = [1, 2, 3]
var it = list.iterator()
while (let Some(i) <- it.next()) {
    println(i)
}

Array, ArrayList, HashSet, and HashMap types all implement Iterable, so they can be used in for-in or while loops.

Overview of Packages

As project scale continues to expand, managing source code in a single oversized file becomes increasingly difficult. In such cases, source code can be grouped by functionality, with different functional code segments managed separately. Each independently managed group generates an output file. During usage, corresponding functionality can be accessed by importing the appropriate output file, or more complex features can be achieved through interaction and combination of different functionalities, thereby making project management more efficient.

In the Cangjie programming language, a package is the smallest unit of compilation. Each package can independently output artifacts such as AST files, static library files, or dynamic library files. Each package has its own namespace, and within the same package, no duplicate top-level definitions or declarations are allowed (except for function overloading). A package may contain multiple source files.

A module is a collection of packages and represents the smallest unit of distribution for third-party developers. A module’s program entry point must be located in its root directory, and it can have at most one main function serving as the program entry at the top level. This main function either takes no parameters or has parameters of type Array<String>, and its return type must be an integer type or Unit.

Package Declaration

In the Cangjie programming language, package declarations begin with the keyword package, followed by the package names from the root package to the current package, separated by .. Package names must be valid ordinary identifiers (excluding raw identifiers). For example:

package pkg1      // root package pkg1
package pkg1.sub1 // sub-package sub1 under root package pkg1

Note:

In the current Windows platform version, package names do not support Unicode characters. Package names must be valid ordinary identifiers containing only ASCII characters.

The package declaration must appear as the first non-empty, non-comment line in a source file, and all source files within the same package must maintain consistent package declarations.

// file 1
// Comments are accepted
package test
// declarations...

// file 2
let a = 1 // Error, package declaration must appear first in a file
package test
// declarations...

In Cangjie, package names should reflect the relative path of the current source file from the project’s source root directory src, with path separators replaced by dots. For example, if the package’s source code is located under src/directory_0/directory_1 and the root package name is pkg, the package declaration in the source code should be package pkg.directory_0.directory_1.

Important considerations:

• The folder name containing the package must match the package name.
• The default name for the source root directory is src.
• Packages in the source root directory may omit package declarations, in which case the compiler will assign them the default package name default.

Given the following source directory structure:

// The directory structure is as follows:
src
`-- directory_0
    |-- directory_1
    |    |-- a.cj
    |    `-- b.cj
    `-- c.cj
`-- main.cj

The package declarations in a.cj, b.cj, c.cj, and main.cj can be:

// a.cj
// in file a.cj, the declared package name must correspond to relative path directory_0/directory_1.

package default.directory_0.directory_1

// b.cj
// in file b.cj, the declared package name must correspond to relative path directory_0/directory_1.

package default.directory_0.directory_1

// c.cj
// in file c.cj, the declared package name must correspond to relative path directory_0.

package default.directory_0

// main.cj
// file main.cj is in the module root directory and may omit package declaration.

main(): Int64 {
    return 0
}

Additionally, package declarations must not cause naming conflicts: sub-packages cannot share names with top-level declarations in the current package.

Here are some error examples:

// a.cj
package a
public class B { // Error, 'B' is conflicted with sub-package 'a.B'
    public static func f() {}
}

// b.cj
package a.B
public func f {}

// main.cj
import a.B // ambiguous use of 'a.B'

main() {
    a.B.f()
}

Visibility of Top-Level Declarations

In the Cangjie programming language, access modifiers can be used to control the visibility of top-level declarations such as types, variables, and functions. Cangjie provides four access modifiers: private, internal, protected, and public. The semantics of these modifiers when applied to top-level elements are as follows:

• private: Visible only within the current file. Members with this modifier cannot be accessed from different files.
• internal: Visible only within the current package and its subpackages (including nested subpackages). Members can be accessed without import within the same package, while subpackages (including nested subpackages) can access these members through imports.
• protected: Visible only within the current module. Files in the same package can access these members without import, while other packages within the same module (but in different packages) can access them through imports. Packages from different modules cannot access these members.
• public: Visible both inside and outside the module. Files in the same package can access these members without import, while other packages can access them through imports.

Different top-level declarations support specific access modifiers and have default modifiers (default modifiers apply when the modifier is omitted; these defaults can also be explicitly specified):

• package: Supports internal, protected, and public, with public as the default modifier.
• import: Supports all access modifiers, with private as the default modifier.
• Other top-level declarations support all access modifiers, with internal as the default modifier.

package a

private func f1() { 1 }   // f1 is visible only within the current file
func f2() { 2 }           // f2 is visible only within the current package and subpackages
protected func f3() { 3 } // f3 is visible only within the current module
public func f4() { 4 }    // f4 is visible both inside and outside the module

The access level hierarchy in Cangjie is public > protected > internal > private. The access modifier of a declaration cannot be higher than the access level of the types used within that declaration. Refer to the following examples:

• Parameters and return values in function declarations

  // a.cj
  package a
  class C {}
  public func f1(a1: C) // Error, public declaration f1 cannot use internal type C.
  {
      return 0
  }
  public func f2(a1: Int8): C // Error, public declaration f2 cannot use internal type C.
  {
      return C()
  }
  public func f3 (a1: Int8) // Error, public declaration f3 cannot use internal type C.
  {
      return C()
  }
  

• Variable declarations

  // a.cj
  package a
  class C {}
  public let v1: C = C() // Error, public declaration v1 cannot use internal type C.
  public let v2 = C() // Error, public declaration v2 cannot use internal type C.
  

• Type arguments for generic types

  // a.cj
  package a
  public class C1<T> {}
  class C2 {}
  public let v1 = C1<C2>() // Error, public declaration v1 cannot use internal type C2.
  

• Type bounds in where constraints

  // a.cj
  package a
  interface I {}
  public class B<T> where T <: I {}  // Error, public declaration B cannot use internal type I.
  

Notably:

• public declarations can use any types visible within their package in their initialization expressions or function bodies, including both public and non-public types.

  // a.cj
  package a
  class C1 {}
  func f1(a1: C1)
  {
    return 0
  }
  public func f2(a1: Int8) // OK.
  {
    var v1 = C1()
    return 0
  }
  public let v1 = f1(C1()) // OK.
  public class C2 // OK.
  {
    var v2 = C1()
  }
  

• public top-level declarations can use anonymous functions or any top-level functions, including both public and non-public top-level functions.

  public var t1: () -> Unit = { => } // OK.
  func f1(): Unit {}
  public let t2 = f1 // OK.
  
  public func f2() // OK.
  {
    return f1
  }
  

• Built-in types such as Rune and Int64 default to public visibility.

  var num = 5
  public var t3 = num // OK.
  

Note:

Within the same package, private custom types (e.g., struct, class, enum, and interface) with the same name are not supported in certain scenarios. Unsupported cases will trigger compiler errors.

For example, in the following program, example1.cj and example2.cj share the same package name. example1.cj defines a private class A, while example2.cj defines a private struct A.

// example1.cj
package test

private class A {}

public class D<T> {
    private let a: A = A()
}

// example2.cj
package test

private struct A {}

public class C<T> {
    private let a: A = A()
}

Running this program will output:

error: currently, it is not possible to export two private declarations with the same name

Package Import

Using import Statements to Import Declarations or Definitions from Other Packages

In the Cangjie programming language, you can import a top-level declaration or definition from another package using the syntax import fullPackageName.itemName, where fullPackageName is the fully qualified package name and itemName is the name of the declaration. The import statements must be placed after the package declaration and before any other declarations or definitions in the source file. For example:

package a
import std.math.*
import package1.foo
import {package1.foo, package2.bar}

If multiple itemNames belong to the same fullPackageName, you can use the syntax import fullPackageName.{itemName[, itemName]*}. For example:

import package1.{foo, bar, fuzz}

This is equivalent to:

import package1.foo
import package1.bar
import package1.fuzz

In addition to importing a specific top-level declaration or definition using import fullPackagename.itemName, you can also use import packageName.* to import all visible top-level declarations or definitions from the packageName package. For example:

import package1.*
import {package1.*, package2.*}

Note the following:

• The scope level of imported members is lower than that of members declared in the current package.
• If the module name or package name of an exported package is altered, making it inconsistent with the name specified during export, an error will occur during import.
• Only top-level declarations or definitions visible to the current file can be imported. Attempting to import invisible declarations or definitions will result in an error at the import statement.
• It is prohibited to import declarations or definitions from the package where the current source file resides using import.
• Circular dependency imports between packages are prohibited. If circular dependencies exist between packages, the compiler will report an error.

Example:

// pkga/a.cj
package pkga    // Error, packages pkga pkgb are in circular dependencies.
import pkgb.*

class C {}
public struct R {}

// pkgb/b.cj
package pkgb

import pkga.*

// pkgc/c1.cj
package pkgc

import pkga.C // Error, 'C' is not accessible in package 'pkga'.
import pkga.R // OK, R is an external top-level declaration of package pkga.
import pkgc.f1 // Error, package 'pkgc' should not import itself.

public func f1() {}

// pkgc/c2.cj
package pkgc

func f2() {
    /* OK, the imported declaration is visible to all source files of the same package
     * and accessing import declaration by its name is supported.
     */
    R()

    // OK, accessing imported declaration by fully qualified name is supported.
    pkga.R()

    // OK, the declaration of current package can be accessed directly.
    f1()

    // OK, accessing declaration of current package by fully qualified name is supported.
    pkgc.f1()
}

In the Cangjie programming language, if an imported declaration or definition has the same name as a top-level declaration or definition in the current package and does not constitute function overloading, the imported declaration or definition will be shadowed. If they do constitute function overloading, function resolution will follow the rules of function overloading during function calls.

// pkga/a.cj
package pkga

public struct R {}            // R1
public func f(a: Int32) {}    // f1
public func f(a: Bool) {} // f2

// pkgb/b.cj
package pkgb
import pkga.*

func f(a: Int32) {}         // f3
struct R {}                 // R2

func bar() {
    R()     // OK, R2 shadows R1.
    f(1)    // OK, invoke f3 in current package.
    f(true) // OK, invoke f2 in the imported package
}

Implicit Import of the core Package

Types such as String and Range can be used directly not because they are built-in types, but because the compiler automatically and implicitly imports all public declarations from the core package for the source code.

Using import as to Rename Imported Names

Different packages have separate namespaces, so top-level declarations with the same name may exist across different packages. When importing top-level declarations with the same name from different packages, you can use import packageName.name as newName to rename them and avoid conflicts. Even without name conflicts, you can still use import as to rename imported content. The rules for import as are as follows:

• After renaming an imported declaration using import as, only the new name can be used in the current package; the original name becomes unavailable.

• If the renamed name conflicts with other names in the top-level scope of the current package and all corresponding declarations are function types, they participate in function overloading; otherwise, a redefinition error is reported.

• The syntax import pkg as newPkgName is supported to rename package names, resolving naming conflicts for packages with the same name in different modules.

  // a.cj
  package p1
  public func f1() {}
  

  // d.cj
  package p2
  public func f3() {}
  

  // b.cj
  package p1
  public func f2() {}
  

  // c.cj
  package pkgc
  public func f1() {}
  

  // main.cj
  import p1 as A
  import p1 as B
  import p2.f3 as f  // OK
  import pkgc.f1 as a
  import pkgc.f1 as b // OK
  
  func f(a: Int32) {}
  
  main() {
      A.f1()  // OK, package name conflict is resolved by renaming package name.
      B.f2()  // OK, package name conflict is resolved by renaming package name.
      p1.f1() // Error, the original package name cannot be used.
      a()     // OK.
      b()     // OK.
      pkgc.f1()    // Error, the original name cannot be used.
  }
  

• If conflicting imported names are not renamed, no error is reported at the import statement. However, an error will occur at the usage site due to the inability to import a unique name. This can be resolved by defining aliases with import as or importing the package as a namespace using import fullPackageName.

  // a.cj
  package p1
  public class C {}
  
  // b.cj
  package p2
  public class C {}
  
  // main1.cj
  package pkga
  import p1.C
  import p2.C
  
  main() {
      let _ = C() // Error
  }
  
  // main2.cj
  package pkgb
  import p1.C as C1
  import p2.C as C2
  
  main() {
      let _ = C1() // OK
      let _ = C2() // OK
  }
  
  // main3.cj
  package pkgc
  import p1
  import p2
  
  main() {
      let _ = p1.C() // OK
      let _ = p2.C() // OK
  }
  

Re-exporting an Imported Name

In large-scale projects with extensive functionality, this scenario is very common: package p2 heavily uses declarations imported from package p1. When package p3 imports p2 and uses its functionality, the declarations from p1 also need to be visible to p3. Requiring p3 to manually import all p1 declarations used by p2 would be overly cumbersome. Therefore, it is desirable to import p1 declarations used by p2 when p2 is imported.

In the Cangjie programming language, import can be modified with the access modifiers private, internal, protected, or public. Among these, import statements modified with public, protected, or internal can re-export the imported members (provided these members are not rendered unavailable in the current package due to name conflicts or shadowing). Other packages can directly import and use the re-exported content based on visibility without needing to import it from the original package.

• private import means the imported content is only accessible within the current file. private is the default modifier for import; an import without an access modifier is equivalent to private import.
• internal import means the imported content is accessible within the current package and its subpackages (including subpackages of subpackages). Access from outside the current package requires an explicit import.
• protected import means the imported content is accessible within the current module. Access from outside the current package requires an explicit import.
• public import means the imported content is accessible externally. Access from outside the current package requires an explicit import.

In the following example, b is a subpackage of a, and a re-exports the function f defined in b using public import.

package a
public import a.b.f

public let x = 0

internal package a.b

public func f() { 0 }

import a.f  // OK
let _ = f() // OK

Note that packages cannot be re-exported: if the import statement imports a package, it cannot be modified with public, protected, or internal.

public import a.b // Error, cannot re-export package

Program Entry Point

The entry point of a Cangjie program is main. At the top level of the package in the root directory of the source files, there can be at most one main function.

When compiling a module into an executable, the compiler only searches for main at the top level of the root directory’s source files. If no main is found, the compiler will report an error. If main is found, the compiler will further verify its parameter and return types. Note that main cannot be modified by access modifiers. When a package is imported, any main defined within that package will not be imported.

The main function serving as the program entry point can either have no parameters or accept a parameter of type Array<String>. Its return type must be either Unit or an integer type.

Example of main without parameters:

// main.cj
main(): Int64 { // OK.
    return 0
}

Example of main with Array<String> parameter:

// main.cj
main(args: Array<String>): Unit { // OK.
    for (arg in args) {
        println(arg)
    }
}

After compiling with cjc main.cj, executing via command line: ./main Hello, World will produce the following output:

Hello,
World

Below are some incorrect examples:

// main.cj
main(): String { // Error, return type of 'main' is not 'Integer' or 'Unit'.
    return ""
}

// main.cj
main(args: Array<Int8>): Int64 { // Error, 'main' cannot be defined with parameter whose type is not Array<String>.
    return 0
}

// main.cj
// Error, multiple 'main's are found in source files.
main(args: Array<String>): Int32 {
    return 0
}

main(): Int8 {
    return 0
}

Defining Exceptions

Exceptions are a special category of errors that can be caught and handled by programmers, representing a series of abnormal behaviors that occur during program execution. Examples include array index out of bounds, division by zero, arithmetic overflow, illegal input, etc. To ensure system correctness and robustness, many software systems contain extensive code for error detection and handling.

Exceptions are not part of a program’s normal functionality. Once an exception occurs, the program must handle it immediately by transferring control from the normal execution flow to the exception handling section. The Cangjie programming language provides an exception handling mechanism to address various exceptional conditions that may arise during runtime.

In Cangjie, exception classes include Error and Exception:

• The Error class describes internal runtime system errors and resource exhaustion errors in Cangjie. Applications should not throw this type of error. If internal errors occur, they should only be reported to users, and the program should attempt to terminate safely.
• The Exception class describes runtime logical errors or IO errors that cause exceptions, such as array index out of bounds or attempting to open a non-existent file. These exceptions need to be caught and handled within the program.

Developers cannot define custom exceptions by inheriting from Cangjie’s built-in Error class or its subclasses. However, they can inherit from the built-in Exception class or its subclasses to create custom exceptions, for example:

open class FatherException <: Exception {
    public init() {
        super("This is FatherException.")
    }
    public init(message: String) {
        super(message)
    }
    public open override func getClassName(): String {
        "FatherException"
    }
}

class ChildException <: FatherException {
    public init() {
        super("This is ChildException.")
    }
    public open override func getClassName(): String {
        "ChildException"
    }
}

The following table shows the main functions of Exception and their descriptions:

The following table shows the main functions of Error and their descriptions:

throw and Exception Handling

The previous section discussed how to define custom exceptions. Now let’s learn how to throw and handle exceptions.

• Since exceptions are of class type, you only need to create them in the same way as class objects. For example, the expression FatherException() creates an exception of type FatherException.

• The Cangjie language supports creating exception chains (only for Exception, not including Error), such as the expression let fatherException = FatherException("this is message", causeException), where causeException is another exception and serves as the cause that triggered fatherException. When printing the exception stack trace, it will recursively print the cause.

• The Cangjie language provides the throw keyword for throwing exceptions. When using throw, the expression following it must be a subtype of Exception (note that Error, though also an exception type, cannot be manually thrown via throw). For example, throw ArithmeticException("I am an Exception!") will throw an arithmetic exception when executed.

• Exceptions thrown via the throw keyword must be caught and handled. If an exception is not caught, the system will invoke the default exception handler.

  Note:

  Developers can call the following static functions of the Thread class to register a custom exception handler for uncaught Exception:

  • public static func handleUncaughtExceptionBy(exHandler: (Thread, Exception) -> Unit): Unit

Exception handling is performed using try expressions, which come in two forms:

1. Regular try expressions without automatic resource management.
2. Try-with-resources expressions that perform automatic resource management.

Regular try Expressions

A regular try expression consists of three parts: a try block, catch blocks, and a finally block.

• Try block: Begins with the try keyword followed by a block of expressions and declarations (enclosed in curly braces, defining a new local scope that can contain any expressions or declarations, hereafter referred to as “block”). The block following try may throw exceptions, which can be caught and handled by subsequent catch blocks (if no catch block exists or the exception is uncaught, the exception continues to propagate after executing the finally block).

• Catch blocks: A regular try expression may contain zero or more catch blocks (when no catch block exists, a finally block must be present). Each catch block starts with the catch keyword, followed by a catchPattern and a block. The catchPattern matches the exception to be caught via pattern matching. Once matched, the exception is handled by the subsequent block, and any remaining catch blocks are ignored. If a catch block’s exception type can be caught by a preceding catch block, a “catch block unreachable” warning will be issued for that catch block.

• Finally block: Begins with the finally keyword followed by a block. The finally block is primarily used for cleanup tasks, such as releasing resources, and should avoid throwing further exceptions. The finally block executes regardless of whether an exception occurs (i.e., whether the try block throws an exception). If the exception remains unhandled, it continues to propagate after the finally block executes. A try expression may omit the finally block only if it includes catch blocks; otherwise, the finally block is mandatory.

The scopes of the block following try and each catch block are independent.

Here is a simple example with only a try block and a catch block:

main() {
    try {
        throw NegativeArraySizeException("I am an Exception!")
    } catch (e: NegativeArraySizeException) {
        println(e)
        println("NegativeArraySizeException is caught!")
    }
    println("This will also be printed!")
}

Execution result:

NegativeArraySizeException: I am an Exception!
NegativeArraySizeException is caught!
This will also be printed!

Variables introduced in catchPattern have the same scope level as variables in the block following catch. Redefining the same variable name in the catch block will trigger a redefinition error. For example:

main() {
    try {
        throw NegativeArraySizeException("I am an Exception!")
    } catch (e: NegativeArraySizeException) {
        println(e)
        let e = 0 // Error, redefinition
        println(e)
        println("NegativeArraySizeException is caught!")
    }
    println("This will also be printed!")
}

Below is a simple example of a try expression with a finally block:

main() {
    try {
        throw NegativeArraySizeException("NegativeArraySizeException")
    } catch (e: NegativeArraySizeException) {
        println("Exception info: ${e}.")
    } finally {
        println("The finally block is executed.")
    }
}

Execution result:

Exception info: NegativeArraySizeException: NegativeArraySizeException.
The finally block is executed.

Try expressions can appear anywhere expressions are allowed. The type of a try expression is determined similarly to multi-branch constructs like if and match expressions: it is the least common supertype of all branch types (excluding the finally branch). For example, in the following code, the try expression and variable x both have type D, the least common supertype of E and D. The C() in the finally branch does not participate in the least common supertype calculation (if it did, the least common supertype would become C).

Additionally, when the value of a try expression is unused, its type is Unit, and the branches are not required to have a least common supertype.

open class C {}

open class D <: C {}

class E <: D {}

main () {
    let x = try {
        E()
    } catch (e: Exception) {
        D()
    } finally {
        C()
    }
    0
}

Try-with-resources Expressions

Try-with-resources expressions are primarily used for automatic release of non-memory resources. Unlike regular try expressions, catch and finally blocks are optional in try-with-resources expressions. Additionally, between the try keyword and the block, one or more ResourceSpecification clauses can be inserted to acquire resources (the ResourceSpecification does not affect the type of the try expression). In the context of the language, resources correspond to objects, so ResourceSpecification essentially instantiates a series of objects (multiple instantiations are separated by “,”). An example of using try-with-resources is shown below:

class Worker <: Resource {
    var hasTools: Bool = false
    let name: String

    public init(name: String) {
        this.name = name
    }
    public func getTools() {
        println("${name} picks up tools from the warehouse.")
        hasTools = true
    }

    public func work() {
        if (hasTools) {
            println("${name} does some work with tools.")
        } else {
            println("${name} doesn't have tools, does nothing.")
        }
    }

    public func isClosed(): Bool {
        if (hasTools) {
            println("${name} hasn't returned the tool.")
            false
        } else {
            println("${name} has no tools")
            true
        }
    }
    public func close(): Unit {
        println("${name} returns the tools to the warehouse.")
        hasTools = false
    }
}

main() {
    try (r = Worker("Tom")) {
        r.getTools()
        r.work()
    }
    try (r = Worker("Bob")) {
        r.work()
    }
    try (r = Worker("Jack")) {
        r.getTools()
        throw Exception("Jack left, because of an emergency.")
    }
}

Program output:

Tom picks up tools from the warehouse.
Tom does some work with tools.
Tom hasn't returned the tool.
Tom returns the tools to the warehouse.
Bob doesn't have tools, does nothing.
Bob has no tools
Jack picks up tools from the warehouse.
Jack hasn't returned the tool.
Jack returns the tools to the warehouse.
An exception has occurred:
Exception: Jack left, because of an emergency.
         at test.main()(xxx/xx.cj:xx)

Variables introduced between the try keyword and {} have the same scope level as variables introduced within {}. Redefining the same name within {} will trigger a redefinition error.

class R <: Resource {
    public func isClosed(): Bool {
        true
    }
    public func close(): Unit {
        print("R is closed")
    }
}

main() {
    try (r = R()) {
        println("Get the resource")
        let r = 0 // Error, redefinition
        println(r)
    }
}

The types in ResourceSpecification of a try-with-resources expression must implement the Resource interface:

interface Resource {
    func isClosed(): Bool // Determines whether the `close` function should be called to release resources when exiting the try-with-resources scope.
    func close(): Unit // Releases resources when `isClosed` returns false.
}

It is worth noting that try-with-resources expressions generally do not need to include catch or finally blocks, nor is it recommended for developers to manually release resources (redundant logic). However, if you need to explicitly catch and handle exceptions that may occur during the try block or resource acquisition/release, you can still include catch and finally blocks in try-with-resources expressions:

class R <: Resource {
    public func isClosed(): Bool {
        true
    }
    public func close(): Unit {
        print("R is closed")
    }
}

main() {
    try (r = R()) {
        println("Get the resource")
    } catch (e: Exception) {
        println("Exception happened when executing the try-with-resources expression")
    } finally {
        println("End of the try-with-resources expression")
    }
}

Program output:

Get the resource
End of the try-with-resources expression

The type of a try-with-resources expression is Unit.

Advanced CatchPattern Introduction

Most of the time, you only want to catch exceptions of a specific type and its subtypes. In such cases, use the type pattern of CatchPattern. However, sometimes you may need to handle all exceptions uniformly (e.g., when no exception should occur, and any exception triggers a uniform error message). In such cases, use the wildcard pattern of CatchPattern.

The type pattern has two syntactic forms:

1. Identifier: ExceptionClass: This form catches exceptions of type ExceptionClass and its subclasses. The caught exception instance is cast to ExceptionClass and bound to the variable defined by Identifier, which can then be used to access the exception instance in the catch block.
2. Identifier: ExceptionClass_1 | ExceptionClass_2 | ... | ExceptionClass_n: This form concatenates multiple exception classes using the | operator, which represents an “or” relationship. It catches exceptions of type ExceptionClass_1 or its subclasses, or ExceptionClass_2 or its subclasses, and so on (assuming n > 1). When the exception type matches any of these types or their subtypes, it is caught. However, since the exact type cannot be determined statically, the caught exception is cast to the least common superclass of all types connected by | and bound to the variable defined by Identifier. Thus, in this mode, the catch block can only access members of the least common superclass via the Identifier variable. Alternatively, a wildcard can replace the Identifier in the type pattern, with the only difference being that the wildcard does not perform binding.

Example:

main(): Int64 {
    try {
        throw IllegalArgumentException("This is an Exception!")
    } catch (e: OverflowException) {
        println(e.message)
        println("OverflowException is caught!")
    } catch (e: IllegalArgumentException | NegativeArraySizeException) {
        println(e.message)
        println("IllegalArgumentException or NegativeArraySizeException is caught!")
    } finally {
        println("finally is executed!")
    }
    return 0
}

Execution result:

This is an Exception!
IllegalArgumentException or NegativeArraySizeException is caught!
finally is executed!

Example demonstrating “the caught exception type is the least common superclass of all types connected by |”:

open class Father <: Exception {
    var father: Int32 = 0
}
class ChildOne <: Father {
    var childOne: Int32 = 1
}

class ChildTwo <: Father {
    var childTwo: Int32 = 2
}

main() {
    try {
        throw ChildOne()
    } catch (e: ChildTwo | ChildOne) {
        println("${e is Father}")
    }
}

Execution result:

true

The syntax for wildcard pattern is _, which can catch any type of exception thrown within the same-level try block. It is equivalent to the type pattern e: Exception, meaning it catches exceptions defined by subclasses of Exception. Example as follows:

// Catch with wildcardPattern.
try {
    throw OverflowException()
} catch (_) {
    println("catch an exception!")
}

Common Runtime Exceptions

The Cangjie language has built-in the most common exception classes that developers can directly use.

Using Option

The Option type was introduced earlier, defining its characteristics. Since the Option type can represent both a value and the absence of a value (where the absence may be interpreted as an error in certain contexts), it can also be used for error handling.

For example, in the following case, if the parameter value of the function getOrThrow equals Some(v), it returns the value v; if the parameter equals None, it throws an exception.

func getOrThrow(a: ?Int64) {
    match (a) {
        case Some(v) => v
        case None => throw NoneValueException()
    }
}

Because Option is an extremely common type, Cangjie provides multiple destructuring methods to facilitate its usage, including: pattern matching, the getOrThrow function, the coalescing operator (??), and the question mark operator (?). Each of these methods will be explained in detail below.

• Pattern Matching: Since the Option type is an enum type, the pattern matching for enums mentioned earlier can be used to destructure Option values. For example, in the following function getString, which takes a parameter of type ?Int64, if the parameter is a Some value, it returns the string representation of the contained number; if the parameter is None, it returns the string "none".

  func getString(p: ?Int64): String{
      match (p) {
          case Some(x) => "${x}"
          case None => "none"
      }
  }
  main() {
      let a = Some(1)
      let b: ?Int64 = None
      let r1 = getString(a)
      let r2 = getString(b)
      println(r1)
      println(r2)
  }
  

  The execution result of the above code is:

  1
  none
  

• Coalescing Operator (??): For an expression e1 of type ?T, if you want to return a value e2 of type T when e1 equals None, you can use the ?? operator. For the expression e1 ?? e2, if e1 equals Some(v), it returns v; otherwise, it returns e2. Example:

  main() {
      let a = Some(1)
      let b: ?Int64 = None
      let r1: Int64 = a ?? 0
      let r2: Int64 = b ?? 0
      println(r1)
      println(r2)
  }
  

  The execution result of the above code is:

  1
  0
  

• Question Mark Operator (?): The ? operator must be used in conjunction with ., (), [], or {} (specifically in trailing lambda calls) to enable support for these operations on Option types. Taking . as an example (similarly for (), [], and {}), for an expression e of type ?T1, when e equals Some(v), the value of e?.b is Option<T2>.Some(v.b); otherwise, it is Option<T2>.None, where T2 is the type of v.b. Example:

  struct R {
      public var a: Int64
      public init(a: Int64) {
          this.a = a
      }
  }
  
  let r = R(100)
  let x = Some(r)
  let y = Option<R>.None
  let r1 = x?.a   // r1 = Option<Int64>.Some(100)
  let r2 = y?.a   // r2 = Option<Int64>.None
  
  class C {
      var item: Int64 = 100
  }
  let c = C()
  let c1 = Option<C>.Some(c)
  let c2 = Option<C>.None
  func test1() {
      c1?.item = 200             // c.item = 200
      c2?.item = 300             // no effect
  }
  

  The question mark operator (?) supports multi-level access. For example, in a?.b.c?.d (similarly for (), [], and {}), the expression a must be of type Option<T1>, where T1 contains an instance member b. The type of b must contain an instance member c, and c must be of type Option<T2>, where T2 contains an instance member d. The type of a?.b.c?.d is Option<T3>, where T3 is the type of T2’s instance member d. When a equals Some(va) and va.b.c equals Some(vc), the value of a?.b.c?.d is Option<T3>.Some(vc.d). When a equals Some(va) but va.b.c equals None, the value is Option<T3>.None (d is not evaluated). When a equals None, the value is Option<T3>.None (b, c, and d are not evaluated).

  class A {
      public var b: B = B()
  }
  
  class B {
      public var c: Option<C> = C()
      public var c1: Option<C> = Option<C>.None
  }
  
  class C {
      public var d: Int64 = 100
  }
  
  main(){
      var a = Some(A())
      let a1 = a?.b.c?.d  // a1 = Option<Int64>.Some(100)
      let a2 = a?.b.c1?.d // a2 = Option<Int64>.None
      a?.b.c?.d = 200     // a.b.c.d = 200
      a?.b.c1?.d = 200    // no effect
  }
  

• getOrThrow Function: For an expression e of type ?T, you can destructure it by calling the getOrThrow function. When e equals Some(v), getOrThrow() returns v; otherwise, it throws an exception. Example:

  main() {
      let a = Some(1)
      let b: ?Int64 = None
      let r1 = a.getOrThrow()
      println(r1)
      try {
          let r2 = b.getOrThrow()
      } catch (e: NoneValueException) {
          println("b is None")
      }
  }
  

  The execution result of the above code is:

  1
  b is None
  

Concurrency Overview

Concurrency programming is an indispensable feature in modern programming languages. The Cangjie programming language provides a preemptive thread model as its concurrency mechanism. Threads can be categorized into two distinct concepts: language threads and native threads.

• Language threads are the fundamental execution units in a programming language’s concurrency model. The Cangjie programming language aims to provide developers with a friendly, efficient, and unified concurrency programming interface, allowing them to focus on writing concurrent code without worrying about differences between operating system threads and user-mode threads. Therefore, it introduces the concept of Cangjie threads. In most cases, developers only need to write concurrent code targeting Cangjie threads.

• Native threads refer to the threads used in the language implementation (typically operating system threads), which serve as the concrete carriers for language threads. Different programming languages implement language threads in various ways. For example, some languages directly create threads through operating system calls, meaning each language thread corresponds to a native thread. This implementation is generally referred to as the 1:1 thread model. Alternatively, some languages provide specialized thread implementations that allow multiple language threads to switch execution across multiple native threads. This is known as the M:N thread model, where M language threads are scheduled to execute on N native threads, with M and N not necessarily being equal. Currently, the Cangjie language implementation also adopts the M:N thread model. Thus, Cangjie threads are essentially lightweight user-mode threads that support preemption and are more lightweight compared to operating system threads.

Cangjie threads are fundamentally lightweight user-mode threads. Each Cangjie thread is scheduled and executed by an underlying native thread, and multiple Cangjie threads can be executed by a single native thread. Each native thread continuously selects a ready Cangjie thread for execution. If a Cangjie thread blocks during execution (e.g., waiting for a mutex to be released), the native thread will suspend the current Cangjie thread and proceed to select the next ready one. A blocked Cangjie thread will resume execution once it becomes ready again.

In most cases, developers only need to focus on writing concurrent code for Cangjie threads without considering these details. However, during cross-language programming, developers must exercise caution when calling potentially blocking foreign functions, such as operating system calls related to I/O. For example, in the following code snippet, a new thread calls the foreign function socket_read. During program execution, a native thread will schedule and execute this Cangjie thread. Upon entering the foreign function, the system call will directly block the current native thread until the function completes. During this blocking period, the native thread cannot schedule other Cangjie threads for execution, which reduces the program’s throughput.

foreign socket_read(sock: Int64): CPointer<Int8>

let fut = spawn {
    let sock: Int64 = ...
    let ptr = socket_read(sock)
}

Note:

In this document, the term thread will be used as a shorthand for Cangjie thread when there is no ambiguity.

Creating Threads

When developers wish to execute a segment of code concurrently, they simply need to create a Cangjie thread. To create a new Cangjie thread, use the keyword spawn followed by a parameterless lambda expression, which represents the code to be executed in the new thread.

In the following example code, both the main thread and the new thread will attempt to print some text:

main(): Int64 {
    spawn { =>
        println("New thread before sleeping")
        sleep(100 * Duration.millisecond) // sleep for 100ms.
        println("New thread after sleeping")
    }

    println("Main thread")

    return 0
}

In the above example, the new thread will terminate along with the main thread when it ends, regardless of whether the new thread has completed its execution. The output of the above example may vary slightly each time and could produce something similar to:

New thread before sleeping
Main thread

The sleep() function suspends the current thread for the specified duration before resuming execution, with the timing determined by the specified Duration type. For detailed information about sleep(), please refer to the Sleeping for a Specified Duration section.

Accessing Threads

Using Future<T> to Wait for Thread Completion and Retrieve Return Values

In the previous example, the newly created thread may terminate prematurely due to the main thread’s completion. Without proper sequencing guarantees, it’s even possible for the newly created thread to exit before getting a chance to execute. The return value of the spawn expression can be used to wait for thread completion.

The return type of the spawn expression is Future<T>, where T is a type parameter matching the return type of the lambda expression. When calling the get() member function of Future<T>, it will wait for the corresponding thread to complete execution.

The prototype declaration of Future<T> is as follows:

public class Future<T> {
    // Blocking the current thread, waiting for the result of the thread corresponding to the current Future object.
    // If an exception occurs in the corresponding thread, the method will throw the exception.
    public func get(): T

    // Blocking the current thread, waiting for the result of the thread corresponding to the current Future object.
    // If the corresponding thread has not completed execution within Duration, the method will throws TimeoutException.
    // If `timeout` <= Duration.Zero, its behavior is the same as `get()`.
    public func get(timeout: Duration): T

    // Non-blocking method that immediately returns Option<T>.None if thread has not finished execution.
    // Returns the computed result otherwise.
    // If an exception occurs in the corresponding thread, the method will throw the exception.
    public func tryGet(): Option<T>
}

The following example demonstrates how to use Future<T> to wait for the newly created thread to complete execution within the main function:

main(): Int64 {
    let fut: Future<Unit> = spawn { =>
        println("New thread before sleeping")
        sleep(100 * Duration.millisecond) // sleep for 100ms.
        println("New thread after sleeping")
    }

    println("Main thread")

    fut.get() // wait for the thread to finish.
    return 0
}

Calling get() on a Future<T> instance blocks the currently running thread until the thread represented by the Future<T> instance completes execution. Therefore, the above example might produce output similar to:

New thread before sleeping
Main thread
New thread after sleeping

After printing, the main thread will wait for the newly created thread to complete due to the get() call. However, the printing order between the main thread and the new thread is nondeterministic.

If fut.get() is moved before the main thread’s print statement as shown below:

main(): Int64 {
    let fut: Future<Unit> = spawn { =>
        println("New thread before sleeping")
        sleep(100 * Duration.millisecond) // sleep for 100ms.
        println("New thread after sleeping")
    }

    fut.get() // wait for the thread to finish.

    println("Main thread")
    return 0
}

The main thread will wait for the newly created thread to complete before executing its print statement, making the program output deterministic as follows:

New thread before sleeping
New thread after sleeping
Main thread

This demonstrates how the placement of get() calls affects whether threads can run concurrently.

Beyond blocking for thread completion, Future<T> can also retrieve execution results. Below are its specific member functions:

• get(): T: Blocks until thread completion and returns the execution result. If the thread has already completed, returns the result directly.

  Example code:

  main(): Int64 {
      let fut: Future<Int64> = spawn {
          sleep(Duration.second) // sleep for 1s.
          return 1
      }
  
      try {
          // wait for the thread to finish, and get the result.
          let res: Int64 = fut.get()
          println("result = ${res}")
      } catch (_) {
          println("oops")
      }
      return 0
  }
  

  Output:

  result = 1
  

• get(timeout: Duration): T: Blocks until thread completion and returns the execution result. If the timeout period is reached before thread completion, throws TimeoutException. When timeout <= Duration.Zero, behaves identically to get().

  Example code:

  main(): Int64 {
      let fut = spawn {
          sleep(Duration.second) // sleep for 1s.
          return 1
      }
  
      // wait for the thread to finish, but only for 1ms.
      try {
          let res = fut.get(Duration.millisecond * 1)
          println("result: ${res}")
      } catch (_: TimeoutException) {
          println("oops")
      }
      return 0
  }
  

  Output:

  oops
  

Accessing Thread Properties

Each Future<T> object corresponds to a Cangjie thread represented by a Thread object. The Thread class primarily provides access to thread property information, such as thread identifiers. Note that Thread objects cannot be directly instantiated—they can only be obtained through the thread member property of Future<T> or via the static currentThread property of the Thread class to get the Thread object representing the currently executing thread.

Partial method definitions of the Thread class are shown below (complete method descriptions can be found in the Cangjie Programming Language Library API).

class Thread {
    // Get the currently running thread
    static prop currentThread: Thread

    // Get the unique identifier (represented as an integer) of the thread object
    prop id: Int64

    // Check whether the thread has any cancellation request
    prop hasPendingCancellation: Bool
}

The following example demonstrates retrieving thread identifiers through both methods after creating a new thread. Since both the main thread and new thread access the same Thread object, they print identical thread identifiers.

main(): Unit {
    let fut = spawn {
        println("Current thread id: ${Thread.currentThread.id}")
    }
    println("New thread id: ${fut.thread.id}")
    fut.get()
}

Sample output (thread IDs may vary):

New thread id: 1
Current thread id: 1

Terminating Threads

The cancel() method of Future<T> can be used to send a termination request to the corresponding thread, but it does not forcibly stop thread execution. Developers need to check whether a termination request exists for the thread using the hasPendingCancellation property of Thread.

Generally, if a termination request exists for a thread, developers should implement appropriate thread termination logic. Therefore, how to terminate a thread is entirely up to the developer’s discretion. If the developer ignores the termination request, the thread will continue executing until it completes normally.

Example code:

import std.sync.SyncCounter

main(): Unit {
    let syncCounter = SyncCounter(1)
    let fut = spawn {
        syncCounter.waitUntilZero()  // block until the syncCounter becomes zero
        if (Thread.currentThread.hasPendingCancellation) {  // Check cancellation request
            println("cancelled")
            return
        }
        println("hello")
    }
    fut.cancel()    // Send cancellation request
    syncCounter.dec()
    fut.get() // Join thread
}

Output:

cancelled

Synchronization Mechanisms

In concurrent programming, without proper synchronization mechanisms to protect variables shared among multiple threads, data race issues can easily occur.

The Cangjie programming language provides three common synchronization mechanisms to ensure thread safety of data: atomic operations, mutex locks, and condition variables.

Atomic Operations

Cangjie provides atomic operations for integer types, Bool type, and reference types.

The integer types include: Int8, Int16, Int32, Int64, UInt8, UInt16, UInt32, UInt64.

Atomic operations for integer types support basic read/write, exchange, and arithmetic operations:

Important notes:

1. The return value of exchange and arithmetic operations is the value before modification.
2. compareAndSwap checks if the current atomic variable’s value equals the old value; if equal, it replaces it with the new value; otherwise, no replacement occurs.

Taking Int8 as an example, the corresponding atomic operation type declaration is as follows:

class AtomicInt8 {
    public func load(): Int8
    public func store(val: Int8): Unit
    public func swap(val: Int8): Int8
    public func compareAndSwap(old: Int8, new: Int8): Bool
    public func fetchAdd(val: Int8): Int8
    public func fetchSub(val: Int8): Int8
    public func fetchAnd(val: Int8): Int8
    public func fetchOr(val: Int8): Int8
    public func fetchXor(val: Int8): Int8
}

Each method of the atomic types mentioned above has a corresponding method that accepts memory ordering parameters. Currently, only sequential consistency is supported for memory ordering.

Similarly, other integer types have corresponding atomic operation types:

class AtomicInt16 {...}
class AtomicInt32 {...}
class AtomicInt64 {...}
class AtomicUInt8 {...}
class AtomicUInt16 {...}
class AtomicUInt32 {...}
class AtomicUInt64 {...}

The following example demonstrates how to use atomic operations to implement counting in a multi-threaded program:

import std.sync.AtomicInt64
import std.collection.ArrayList

let count = AtomicInt64(0)

main(): Int64 {
    let list = ArrayList<Future<Int64>>()

    // create 1000 threads.
    for (_ in 0..1000) {
        let fut = spawn {
            sleep(Duration.millisecond) // sleep for 1ms.
            count.fetchAdd(1)
        }
        list.add(fut)
    }

    // Wait for all threads finished.
    for (f in list) {
        f.get()
    }

    let val = count.load()
    println("count = ${val}")
    return 0
}

The expected output is:

count = 1000

Here are some other correct examples of using integer-type atomic operations:

var obj: AtomicInt32 = AtomicInt32(1)
var x = obj.load() // x: 1, the type is Int32
x = obj.swap(2) // x: 1
x = obj.load() // x: 2
var y = obj.compareAndSwap(2, 3) // y: true, the type is Bool.
y = obj.compareAndSwap(2, 3) // y: false, the value in obj is no longer 2 but 3. Therefore, the CAS operation fails.
x = obj.fetchAdd(1) // x: 3
x = obj.load() // x: 4

Atomic operations for Bool type and reference types only provide read/write and exchange operations:

Note:

Atomic reference operations are only valid for reference types.

The atomic reference type is AtomicReference. Here are some correct examples of using Bool type and reference-type atomic operations:

import std.sync.{AtomicBool, AtomicReference}

class A {}

main() {
    var obj = AtomicBool(true)
    var x1 = obj.load() // x1: true, the type is Bool
    println(x1)
    var t1 = A()
    var obj2 = AtomicReference(t1)
    var x2 = obj2.load() // x2 and t1 are the same object
    var y1 = obj2.compareAndSwap(x2, t1) // x2 and t1 are the same object, y1: true
    println(y1)
    var t2 = A()
    var y2 = obj2.compareAndSwap(t2, A()) // x and t1 are not the same object, CAS fails, y2: false
    println(y2)
    y2 = obj2.compareAndSwap(t1, A()) // CAS successes, y2: true
    println(y2)
}

Compiling and executing the above code produces the following output:

true
true
false
true

Reentrant Mutex Lock

The reentrant mutex lock protects critical sections, ensuring that only one thread can execute the critical section code at any given time. When a thread attempts to acquire a lock held by another thread, it blocks until the lock is released. Reentrant means a thread can acquire the same lock multiple times.

When using a reentrant mutex lock, two rules must be strictly followed:

1. Before accessing shared data, the lock must be acquired;
2. After processing the shared data, the lock must be released to allow other threads to acquire it.

The main member functions provided by Mutex are as follows:

public class Mutex <: UniqueLock {
    // Create a Mutex.
    public init()

    // Locks the mutex, blocks if the mutex is not available.
    public func lock(): Unit

    // Unlocks the mutex. If there are other threads blocking on this
    // lock, then wake up one of them.
    public func unlock(): Unit

    // Tries to lock the mutex, returns false if the mutex is not
    // available, otherwise returns true.
    public func tryLock(): Bool

    // Generate a Condition instance for the mutex.
    public func condition(): Condition
}

The following example demonstrates how to use Mutex to protect access to the global shared variable count. Operations on count constitute the critical section:

import std.sync.Mutex
import std.collection.ArrayList

var count: Int64 = 0
let mtx = Mutex()

main(): Int64 {
    let list = ArrayList<Future<Unit>>()

    // create 1000 threads.
    for (i in 0..1000) {
        let fut = spawn {
            sleep(Duration.millisecond) // sleep for 1ms.
            mtx.lock()
            count++
            mtx.unlock()
        }
        list.add(fut)
    }

    // Wait for all threads finished.
    for (f in list) {
        f.get()
    }

    println("count = ${count}")
    return 0
}

The expected output is:

count = 1000

The following example demonstrates how to use tryLock:

import std.sync.Mutex


main(): Int64 {
    let mtx: Mutex = Mutex()
    var future: Future<Unit> = spawn {
        mtx.lock()
        println("get the lock, do something")
        sleep(Duration.millisecond * 10)
        mtx.unlock()
    }
    try {
        future.get(Duration.millisecond * 10)
    } catch (e: TimeoutException) {
        if (mtx.tryLock()) {
            println("tryLock success, do something")
            mtx.unlock()
            return 0
        }
        println("tryLock failed, do nothing")
        return 0
    }
    return 0
}

One possible output is:

get the lock, do something

Here are some incorrect examples of mutex usage:

Error Example 1: A thread fails to unlock after operating on the critical section, causing other threads to block while waiting for the lock.

import std.sync.Mutex

var sum: Int64 = 0
let mutex = Mutex()

main() {
    let foo = spawn { =>
        mutex.lock()
        sum = sum + 1
    }
    let bar = spawn { =>
        mutex.lock()
        sum = sum + 1
    }
    foo.get()
    println("${sum}")
    bar.get() // Because the thread is not unlocked, other threads waiting to obtain the current mutex will be blocked.
}

Error Example 2: Calling unlock without holding the lock in the current thread will throw an exception.

import std.sync.Mutex

var sum: Int64 = 0
let mutex = Mutex()

main() {
    let foo = spawn { =>
        sum = sum + 1
        mutex.unlock() // Error, Unlock without obtaining the lock and throw an exception: IllegalSynchronizationStateException.
    }
    foo.get()
}

Error Example 3: tryLock() does not guarantee acquiring the lock, which may lead to operations on critical sections without lock protection and exceptions when calling unlock without holding the lock.

import std.sync.Mutex

var sum: Int64 = 0
let mutex = Mutex()

main() {
    for (i in 0..100) {
        spawn { =>
            mutex.tryLock() // Error, `tryLock()` just trying to acquire a lock, there is no guarantee that the lock will be acquired, and this can lead to abnormal behavior.
            sum = sum + 1
            mutex.unlock()
        }
    }
}

Additionally, Mutex is designed as a reentrant lock, meaning: when a thread already holds a Mutex lock, attempting to acquire the same Mutex lock again will always immediately succeed.

Note:

Although Mutex is a reentrant lock, the number of unlock() calls must match the number of lock() calls to successfully release the lock.

The following example demonstrates the reentrant property of Mutex:

import std.sync.Mutex

var count: Int64 = 0
let mtx = Mutex()

func foo() {
    mtx.lock()
    count += 10
    bar()
    mtx.unlock()
}

func bar() {
    mtx.lock()
    count += 100
    mtx.unlock()
}

main(): Int64 {
    let fut = spawn {
        sleep(Duration.millisecond) // sleep for 1ms.
        foo()
    }

    foo()

    fut.get()

    println("count = ${count}")
    return 0
}

The output should be:

count = 220

In the above example, whether in the main thread or the newly created thread, if the lock is already acquired in foo(), then calling bar() will immediately acquire the same Mutex lock without causing deadlock.

Condition

Condition is a condition variable (i.e., wait queue) bound to a mutex lock. Condition instances are created by mutex locks, and a single mutex can create multiple Condition instances. Condition allows threads to block and wait for signals from other threads to resume execution. This is a thread synchronization mechanism using shared variables, providing the following main methods:

public class Mutex <: UniqueLock {
    // ...
    // Generate a Condition instance for the mutex.
    public func condition(): Condition
}

public interface Condition {
    // Wait for a signal, blocking the current thread.
    func wait(): Unit
    func wait(timeout!: Duration): Bool

    // Wait for a signal and predicate, blocking the current thread.
    func waitUntil(predicate: ()->Bool): Unit
    func waitUntil(predicate: ()->Bool, timeout!: Duration): Bool

    // Wake up one thread of those waiting on the monitor, if any.
    func notify(): Unit

    // Wake up all threads waiting on the monitor, if any.
    func notifyAll(): Unit
}

Before calling wait, notify, or notifyAll methods of the Condition interface, ensure the current thread holds the bound lock. The wait method performs the following actions:

1. Adds the current thread to the wait queue of the corresponding lock;
2. Blocks the current thread while fully releasing the lock and recording the lock’s reentrant count;
3. Waits for another thread to signal this thread using notify or notifyAll on the same Condition instance;
4. When awakened, the thread automatically attempts to reacquire the lock with the same reentrant state as recorded in step 2; if acquisition fails, the thread blocks on the lock.

The wait method accepts an optional timeout parameter. Note that many common operating systems do not guarantee real-time scheduling, so precise blocking for “exactly N nanoseconds” cannot be guaranteed—system-dependent inaccuracies may be observed. Additionally, the current language specification explicitly allows implementations to produce spurious wakeups—in such cases, the wait return value is implementation-dependent (either true or false). Therefore, developers are encouraged to always wrap wait in a loop:

synchronized (obj) {
  while (<condition is not true>) {
    obj.wait()
  }
}

Below is a correct example of using Condition:

import std.sync.Mutex

let mtx = Mutex()
let condition = synchronized(mtx) {
    mtx.condition()
}
var flag: Bool = true

main(): Int64 {
    let fut = spawn {
        mtx.lock()
        while (flag) {
            println("New thread: before wait")
            condition.wait()
            println("New thread: after wait")
        }
        mtx.unlock()
    }

    // Sleep for 10ms, to make sure the new thread can be executed.
    sleep(10 * Duration.millisecond)

    mtx.lock()
    println("Main thread: set flag")
    flag = false
    mtx.unlock()

    mtx.lock()
    println("Main thread: notify")
    condition.notifyAll()
    mtx.unlock()

    // wait for the new thread finished.
    fut.get()
    return 0
}

The output should be:

New thread: before wait
Main thread: set flag
Main thread: notify
New thread: after wait

When executing wait on a Condition object, it must be done under lock protection; otherwise, the unlock operation in wait will throw an exception.

Below are some error examples of using condition variables:

import std.sync.Mutex

let m1 = Mutex()
let c1 = synchronized(m1) {
    m1.condition()
}
let m2 = Mutex()
var flag: Bool = true
var count: Int64 = 0

func foo1() {
    spawn {
        m2.lock()
        while (flag) {
            c1.wait() // Error：The lock used with the condition variable must be the same and in the locked state. Otherwise, the unlock operation in `wait` throws an exception.
        }
        count = count + 1
        m2.unlock()
    }
    m1.lock()
    flag = false
    c1.notifyAll()
    m1.unlock()
}

func foo2() {
    spawn {
        while (flag) {
            c1.wait() // Error：`wait` must be called while holding the lock.
        }
        count = count + 1
    }
    m1.lock()
    flag = false
    c1.notifyAll()
    m1.unlock()
}

main() {
    foo1()
    foo2()
    c1.wait()
}

In complex thread synchronization scenarios, multiple Condition instances may need to be generated for the same lock object. The following example implements a fixed-length bounded FIFO queue. When the queue is empty, get() blocks; when the queue is full, put() blocks.

import std.sync.{Mutex, Condition}

class BoundedQueue {
    // Create a Mutex, two Conditions.
    let m: Mutex = Mutex()
    var notFull: Condition
    var notEmpty: Condition

    var count: Int64 // Object count in buffer.
    var head: Int64  // Write index.
    var tail: Int64  // Read index.

    // Queue's length is 100.
    let items: Array<Object> = Array<Object>(100, {i => Object()})

    init() {
        count = 0
        head = 0
        tail = 0

        synchronized(m) {
          notFull  = m.condition()
          notEmpty = m.condition()
        }
    }

    // Insert an object, if the queue is full, block the current thread.
    public func put(x: Object) {
        // Acquire the mutex.
        synchronized(m) {
          while (count == 100) {
            // If the queue is full, wait for the "queue notFull" event.
            notFull.wait()
          }
          items[head] = x
          head++
          if (head == 100) {
            head = 0
          }
          count++

          // An object has been inserted and the current queue is no longer
          // empty, so wake up the thread previously blocked on get()
          // because the queue was empty.
          notEmpty.notify()
        } // Release the mutex.
    }

    // Pop an object, if the queue is empty, block the current thread.
    public func get(): Object {
        // Acquire the mutex.
        synchronized(m) {
          while (count == 0) {
            // If the queue is empty, wait for the "queue notEmpty" event.
            notEmpty.wait()
          }
          let x: Object = items[tail]
          tail++
          if (tail == 100) {
            tail = 0
          }
          count--

          // An object has been popped and the current queue is no longer
          // full, so wake up the thread previously blocked on put()
          // because the queue was full.
          notFull.notify()

          return x
        } // Release the mutex.
    }
}

The synchronized Keyword

The Lock provides a convenient and flexible way for locking operations. However, due to its flexibility, it may lead to issues such as forgetting to unlock or failing to automatically release held locks when exceptions occur while holding the lock. Therefore, the Cangjie programming language provides a synchronized keyword to be used with Lock, which automatically performs locking and unlocking operations within its following scope to address such problems.

The following example code demonstrates how to use the synchronized keyword to protect shared data:

import std.sync.Mutex
import std.collection.ArrayList

var count: Int64 = 0
let mtx = Mutex()

main(): Int64 {
    let list = ArrayList<Future<Unit>>()

    // create 1000 threads.
    for (i in 0..1000) {
        let fut = spawn {
            sleep(Duration.millisecond) // sleep for 1ms.
            // Use synchronized(mtx), instead of mtx.lock() and mtx.unlock().
            synchronized(mtx) {
                count++
            }
        }
        list.add(fut)
    }

    // Wait for all threads finished.
    for (f in list) {
        f.get()
    }

    println("count = ${count}")
    return 0
}

The expected output should be:

count = 1000

By adding a Lock instance after synchronized, the code block it modifies is protected, ensuring that at most one thread can execute the protected code at any given time:

1. Before entering the synchronized code block, a thread automatically acquires the lock corresponding to the Lock instance. If the lock cannot be acquired, the current thread is blocked;
2. Before exiting the synchronized code block, a thread automatically releases the lock of the Lock instance.

For control transfer expressions (such as break, continue, return, throw), when they cause the program execution to exit the synchronized code block, they also comply with point 2 above, meaning the lock corresponding to the synchronized expression is automatically released.

The following example demonstrates the case where a break statement appears within a synchronized code block:

import std.sync.Mutex
import std.collection.ArrayList

var count: Int64 = 0
var mtx: Mutex = Mutex()

main(): Int64 {
    let list = ArrayList<Future<Unit>>()
    for (i in 0..10) {
        let fut = spawn {
            while (true) {
                synchronized(mtx) {
                    count = count + 1
                    break
                    println("in thread")
                }
            }
        }
        list.add(fut)
    }

    // Wait for all threads finished.
    for (f in list) {
        f.get()
    }

    synchronized(mtx) {
        println("in main, count = ${count}")
    }
    return 0
}

The expected output should be:

in main, count = 10

In reality, the line in thread will not be printed because the break statement causes the program execution to exit the while loop (before exiting the while loop, it first exits the synchronized code block).

Thread-Local Variables (ThreadLocal)

Using the ThreadLocal from the core package, you can create and use thread-local variables. Each thread has its own independent storage space to hold these thread-local variables. Therefore, each thread can safely access its own thread-local variables without being affected by other threads.

public class ThreadLocal<T> {
    /* Construct a Cangjie thread-local variable carrying a null value */
    public init()

    /* Get the value of the Cangjie thread-local variable */
    public func get(): Option<T> // Returns Option<T>.None if the value does not exist. Return value Option<T> - the value of the Cangjie thread-local variable.

    /* Set the value of the Cangjie thread-local variable via 'value' */
    public func set(value: Option<T>): Unit // If Option<T>.None is passed, the value of the local variable will be deleted and cannot be retrieved in subsequent thread operations. Parameter value - the value to set for the local variable.
}

The following example code demonstrates how to use the ThreadLocal class to create and use thread-local variables for each thread:

main(): Int64 {
    let tl = ThreadLocal<Int64>()
    let fut1 = spawn {
        tl.set(123)
        println("tl in spawn1 = ${tl.get().getOrThrow()}")
    }
    let fut2 = spawn {
        tl.set(456)
        println("tl in spawn2 = ${tl.get().getOrThrow()}")
    }
    fut1.get()
    fut2.get()
    0
}

Possible output results are as follows:

tl in spawn1 = 123
tl in spawn2 = 456

Or:

tl in spawn2 = 456
tl in spawn1 = 123

Thread Sleep for Specified Duration

The sleep function blocks the currently running thread, causing it to voluntarily sleep for a specified duration before resuming execution. Its parameter type is Duration. The function prototype is:

func sleep(dur: Duration): Unit // Sleep for at least `dur`.

Note:

If dur <= Duration.Zero, the current thread will only yield execution resources without entering sleep mode.

Below is an example of using sleep:

main(): Int64 {
    println("Hello")
    sleep(Duration.second)  // sleep for 1s.
    println("World")
    return 0
}

The output is as follows:

Hello
World

Overview of I/O Streams

This chapter introduces fundamental I/O concepts and file operations.

In the Cangjie programming language, operations that interact with external carriers of applications are referred to as I/O operations. “I” stands for Input, and “O” stands for Output.

All I/O mechanisms in Cangjie are based on data streams for input and output, where these streams represent sequences of byte data. A data stream is a continuous collection of data, functioning like a pipeline that carries data—data is input at one end of the pipeline and output at the other.

The Cangjie programming language abstracts input and output as Streams.

• Reading data from external storage into memory is called an input stream (InputStream). The input end can write data into the pipeline segment by segment, and these segments form a long data stream in sequence.
• Writing data from memory to external storage is called an output stream (OutputStream). The output end can also read data from the pipeline segment by segment, where any length of data can be read each time (without needing to match the input end), but only earlier input data can be read before later input data.

With this layer of abstraction, the Cangjie programming language can use a unified interface to interact with external data.

The Cangjie programming language describes operations such as standard input/output, file operations, network data streams, string streams, encryption streams, compression streams, etc., uniformly using Stream.

Stream primarily deals with raw binary data, and the smallest data unit in a Stream is Byte.

The Cangjie programming language defines Stream as an interface, allowing different Streams to be combined using the decorator pattern, significantly enhancing extensibility.

Input Stream

A program reads data sources (including external devices like keyboards, files, networks, etc.) from an input stream. In other words, an input stream is a communication channel that reads data sources into the program.

The Cangjie programming language uses the InputStream interface type to represent an input stream. It provides a read function, which writes readable data into a buffer and returns the total number of bytes read in that operation.

Definition of the InputStream interface:

interface InputStream {
    func read(buffer: Array<Byte>): Int64
}

When an input stream is available, byte data can be read as shown in the following code. The read data is written into the input parameter array of read.

Example of reading from an input stream:

import std.io.InputStream

main() {
    let input: InputStream = ...
    let buf = Array<Byte>(256, repeat: 0)
    while (input.read(buf) > 0) {
        println(buf)
    }
}

Output Stream

A program writes data to an output stream. An output stream is a communication channel that outputs data from the program to external devices (such as displays, printers, files, networks, etc.).

The Cangjie programming language uses the OutputStream interface type to represent an output stream. It provides a write function, which writes data from the buffer into the bound stream.

Notably, some output streams’ write operations do not immediately write to external storage but follow certain buffering strategies. Data is only physically written when certain conditions are met or when flush is explicitly called, aiming to improve performance.

To uniformly handle these flush operations, OutputStream includes a default implementation of flush, which helps smooth out API call differences.

Definition of the OutputStream interface:

interface OutputStream {
    func write(buffer: Array<Byte>): Unit

    func flush(): Unit {
        // Empty implementation
    }
}

When an output stream is available, byte data can be written.

Example of writing to an output stream:

import std.io.OutputStream

main() {
    let output: OutputStream = ...
    let buf = Array<Byte>(256, repeat: 111)
    output.write(buf)
    output.flush()
}

Classification of Data Streams

Based on their functional differences, Streams can be broadly categorized into two types:

• Node Streams: Directly provide data sources. Node streams are typically constructed by relying on direct external resources (such as files, networks, etc.).
• Processing Streams: Can only delegate other data streams for processing. Processing streams are usually constructed by depending on other streams.

I/O Node Streams

Node streams refer to streams that directly provide data sources. The construction of node streams typically relies on some direct external resource (such as files, networks, etc.).

Common node streams in the Cangjie programming language include standard streams (ConsoleReader, ConsoleWriter), file streams (File), network streams (Socket), etc.

This chapter introduces standard streams and file streams.

Standard Streams

Standard streams include standard input stream, standard output stream, and standard error output stream.

Standard streams serve as the standard interface for programs to interact with external data. During program execution, data is read from the input stream as program input, output information is transmitted to the output stream, and similarly, error information is sent to the error stream.

In the Cangjie programming language, the global functions getStdIn, getStdOut, and getStdErr can be used to obtain these three standard streams respectively.

To use these functions, the env package needs to be imported:

Example of importing the env package:

import std.env.*

The ConsoleReader and ConsoleWriter types in the env package provide user-friendly wrappers for these three standard streams (since the standard error output stream is also an output stream, there are two types in total). They offer more convenient String-based extended operations and provide rich overloads for many common types to optimize performance.

Most importantly, ConsoleReader and ConsoleWriter types guarantee thread safety, allowing safe reading and writing through their interfaces in any thread.

By default, the standard input stream comes from keyboard input, such as text entered in a command-line interface.

When data needs to be obtained from the standard input stream, the ConsoleReader type can be acquired via the getStdIn global function, and then the readln function of this type can be used to get command-line input.

Example of reading from the standard input stream:

import std.env.getStdIn

main() {
    let consoleReader = getStdIn()
    let txt = consoleReader.readln()
    println(txt ?? "")
}

Run the above code, enter some text in the command line, and then press Enter to see the input content.

The output stream is divided into standard output stream and standard error stream. By default, both output to the screen, such as the text seen in the command-line interface.

When data needs to be written to the standard output stream, the ConsoleWriter can be obtained via the getStdOut/getStdErr global functions to write data, such as using the write function to print content to the console.

The difference between using ConsoleWriter and directly using the print function is that ConsoleWriter is thread-safe and, due to its caching technology, offers better performance when dealing with large amounts of content.

Note that after writing data, flush must be called on ConsoleWriter to ensure the content is completely written to the standard stream.

Example of writing to the standard output stream:

import std.env.getStdOut

main() {
    let consoleWriter = getStdOut()
    for (_ in 0..1000) {
        consoleWriter.writeln("hello, world!")
    }
    consoleWriter.flush()
}

File Streams

The Cangjie programming language provides the fs package to support general file system tasks. Different operating systems offer varying interfaces for file systems. The Cangjie programming language abstracts the following common functionalities, providing unified interfaces to mask differences between operating systems and simplify usage.

Common operations include: creating files/directories, reading/writing files, renaming or moving files/directories, deleting files/directories, copying files/directories, obtaining file/directory metadata, and checking file/directory existence. Specific APIs can be found in the library documentation.

To use file system-related functionalities, the fs package must be imported:

Example of importing the fs package:

import std.fs.*

This chapter focuses on the usage of File. For Path and Directory usage, please refer to the corresponding API documentation.

The File type in the Cangjie programming language provides both conventional file operations and file stream functionalities.

Conventional File Operations

For conventional file operations, a series of static functions can be used to perform quick operations.

For example, to check if a file exists at a certain path, the exists function can be used. When exists returns true, it indicates the file exists; otherwise, it does not.

Example of using the exists function:

import std.fs.exists

main() {
    let exist = exists("./tempFile.txt")
    println("exist: ${exist}")
}

Moving, copying, and deleting files are also straightforward. The File type provides corresponding static functions: move, copy, and delete.

Example of using move, copy, and delete functions:

import std.fs.{copy, rename, remove}

main() {
    copy("./tempFile.txt", to: "./tempFile2.txt", overwrite: false)
    rename("./tempFile2.txt",  to: "./tempFile3.txt", overwrite: false)
    remove("./tempFile3.txt")
}

If all data from a file needs to be read at once or data needs to be written to a file in one go, the readFrom and writeTo functions provided by File can be used. For small amounts of data, these functions are both simple to use and offer good performance without manual stream handling.

Example of using readFrom and writeTo functions:

import std.fs.File

main() {
    let bytes = File.readFrom("./tempFile.txt") // Reads all data at once
    File.writeTo("./otherFile.txt", bytes) // Writes all data to another file at once
}

File Stream Operations

In addition to the conventional file operations mentioned above, the File type is also designed as a data stream type. Therefore, the File type implements the IOStream interface. When a File instance is created, it can be used as a data stream.

Definition of the File class:

public class File <: Resource & IOStream & Seekable {
    ...
}

File provides two construction methods: one uses the convenient static function create to directly create a new file instance, and the other uses a constructor with a complete file opening mode to create a new instance.

Files created with create are write-only; read operations on such instances will throw a runtime exception.

Example of File construction:

// Create
internal import std.fs.*
internal import std.io.*

main() {
    let file = File.create("./tempFile.txt")
    file.write("hello, world!".toArray())

    // Open
    let file2 = File("./tempFile.txt", Read)
    let bytes = readToEnd(file2) // Reads all data
    println(bytes)
}

When more precise opening modes are needed, a constructor can be used with an OpenMode value. OpenMode is an enum type that provides rich file opening modes, including Read, Write, Append, and ReadWrite.

Example of using File opening modes:

// Open with specified options
let file = File("./tempFile.txt", Write)

Since opening a File instance consumes valuable system resources, it is important to close the File promptly after use to release system resources.

File implements the Resource interface, so in most cases, the try-with-resource syntax can be used to simplify operations.

Example of using try-with-resource syntax:

try (file2 = File("./tempFile.txt", Read)) {
    ...
    // Automatically releases the file after use
}

I/O Processing Streams

Processing streams refer to streams that act as intermediaries for processing other data streams.

Common processing streams in the Cangjie programming language include BufferedInputStream, BufferedOutputStream, StringReader, StringWriter, ChainedInputStream, etc.

This chapter introduces buffered streams and string streams.

Buffered Streams

Since disk I/O operations are significantly slower than memory I/O operations, for high-frequency, small-data read/write operations, unbuffered data streams are highly inefficient—each read and write operation incurs substantial I/O overhead. Buffered data streams, however, can perform multiple read/write operations without triggering disk I/O; instead, data is temporarily stored in memory. Only when the buffer reaches its capacity is the data written to disk in a single operation. This approach dramatically reduces the number of disk operations, thereby improving performance.

The Cangjie programming language standard library provides the BufferedInputStream and BufferedOutputStream types to offer buffering functionality.

To use BufferedInputStream and BufferedOutputStream, the io package must be imported.

Example of importing the io package:

import std.io.*

The BufferedInputStream adds buffering capabilities to another input stream. Essentially, BufferedInputStream is implemented using an internal buffer array.

When reading data through BufferedInputStream, it reads an entire buffer’s worth of data at once. Subsequent read operations can then retrieve smaller chunks of data. When the buffer is exhausted, the input stream refills it. This process repeats until all data in the stream is read.

To construct a BufferedInputStream, simply pass another input stream to its constructor. To specify the buffer size, an additional capacity parameter can be provided.

Example of constructing a BufferedInputStream:

import std.io.{ByteBuffer, BufferedInputStream}

main(): Unit {
    let arr1 = "0123456789".toArray()
    let byteBuffer = ByteBuffer()
    byteBuffer.write(arr1)
    let bufferedInputStream = BufferedInputStream(byteBuffer)
    let arr2 = Array<Byte>(20, repeat: 0)

    /* Reads data from the stream and returns the length of the data read */
    let readLen = bufferedInputStream.read(arr2)
    println(String.fromUtf8(arr2[..readLen])) // 0123456789
}

The BufferedOutputStream adds buffering capabilities to another output stream. It is also implemented using an internal buffer array.

When writing data through BufferedOutputStream, the write operations first fill the internal buffer. Once the buffer is full, BufferedOutputStream writes the entire buffer’s contents to the output stream in one operation and then clears the buffer for subsequent writes. This process repeats until all data is written.

Note: Since writing data that doesn’t fill the buffer won’t trigger an output stream write operation, after completing all writes to BufferedOutputStream, an additional flush call is required to finalize the writes.

To construct a BufferedOutputStream, pass another output stream to its constructor. To specify the buffer size, an additional capacity parameter can be provided.

Example of constructing a BufferedOutputStream:

import std.io.{ByteBuffer, BufferedOutputStream, readToEnd}

main(): Unit {
    let arr1 = "01234".toArray()
    let byteBuffer = ByteBuffer()
    byteBuffer.write(arr1)
    let bufferedOutputStream = BufferedOutputStream(byteBuffer)
    let arr2 = "56789".toArray()

    /* Writes data to the stream; the data remains in the external stream's buffer */
    bufferedOutputStream.write(arr2)

    /* Calls the flush function to finally write the data to the internal stream */
    bufferedOutputStream.flush()
    println(String.fromUtf8(readToEnd(byteBuffer))) // 0123456789
}

String Streams

Since the input and output streams in the Cangjie programming language are byte-based (for better performance), they can be less user-friendly in scenarios primarily involving strings, such as writing large amounts of text to a file, where text must first be converted to byte data before writing.

To provide convenient string manipulation capabilities, the Cangjie programming language offers StringReader and StringWriter for string processing.

To use StringReader and StringWriter, the io package must be imported:

Example of importing the io package:

import std.io.*

StringReader provides line-by-line reading and conditional reading capabilities, offering better performance and usability compared to manually converting byte data to strings.

To construct a StringReader, simply pass another input stream to it.

Example of using StringReader:

import std.io.{ByteBuffer, StringReader}

main(): Unit {
    let arr1 = "012\n346789".toArray()
    let byteBuffer = ByteBuffer()
    byteBuffer.write(arr1)
    let stringReader = StringReader(byteBuffer)

    /* Reads a line of data */
    let line = stringReader.readln()
    println(line ?? "error") // 012
}

StringWriter provides direct string writing and line-by-line string writing capabilities, offering better performance and usability compared to manually converting strings to byte data before writing.

To construct a StringWriter, simply pass another output stream to it.

Example of using StringWriter:

import std.io.{ByteBuffer, StringWriter, readToEnd}

main(): Unit {
    let byteBuffer = ByteBuffer()
    let stringWriter = StringWriter(byteBuffer)

    /* Writes a string */
    stringWriter.write("number")

    /* Writes a string and automatically appends a newline */
    stringWriter.writeln(" is:")

    /* Writes a number */
    stringWriter.write(100.0f32)

    stringWriter.flush()

    println(String.fromUtf8(readToEnd(byteBuffer))) // number is:\n100.000000
}

Overview of Network Programming

Network communication is the process of data exchange between two devices through a computer network. The act of achieving network communication through software development is referred to as network programming.

Cangjie provides developers with fundamental network programming capabilities. Within the Cangjie standard library, developers can utilize the socket package under the std module to implement transport-layer network communication.

In transport-layer protocols, there are two categories: unreliable transmission and reliable transmission. Cangjie abstracts these as DatagramSocket and StreamSocket, respectively. Among unreliable transmission protocols, UDP is the most common, while TCP is the predominant reliable transmission protocol. Cangjie abstracts these as UdpSocket and TcpSocket, respectively. Additionally, Cangjie implements support for the Unix Domain protocol at the transport layer, enabling communication through both reliable and unreliable transmission methods.

At the application layer, the HTTP protocol is widely used, particularly in developing web applications. Currently, there are multiple versions of the HTTP protocol, and Cangjie currently supports HTTP/1.0, HTTP/1.1, and HTTP/2.0.

Furthermore, WebSocket, as an application-layer protocol designed to enhance communication efficiency between web servers and clients, is abstracted by Cangjie as the WebSocket object. Cangjie also supports protocol upgrades from HTTP to WebSocket.

It is important to note that network programming in Cangjie is blocking. However, it is the Cangjie thread that gets blocked, and a blocked Cangjie thread yields the system thread, thus not truly blocking a system thread.

Socket Programming

Cangjie’s socket programming refers to the implementation of network packet transmission functionality based on transport layer protocols.

In reliable transmission scenarios, Cangjie initiates both client and server sockets. The client socket must specify the remote address to connect to and may optionally bind to a local address. Only after a successful connection can it send and receive messages. The server socket, on the other hand, must bind to a local address, and only after successful binding can it send and receive messages.

In unreliable transmission scenarios, sockets do not need to distinguish between client and server roles. Cangjie initiates two sockets for data transmission. The sockets must bind to local addresses, and only after successful binding can they send and receive messages. Additionally, sockets may optionally specify a remote connection address. When specified, the socket will only accept messages from that particular remote address, and when sending (via send), there’s no need to specify the remote address as messages will automatically be sent to the successfully connected address.

TCP Programming

As a common reliable transmission protocol, using TCP-type sockets as an example, Cangjie’s reference programming model for reliable transmission scenarios is as follows:

1. Create a server socket and specify the local binding address.
2. Perform binding.
3. Execute the accept operation, which will block until a client socket connection is obtained.
4. Synchronously create a client socket and specify the remote address to connect to.
5. Perform the connection.
6. After successful connection, the server will return a new socket through the accept interface. At this point, the server can perform read/write operations (i.e., send/receive messages) through this socket, while the client can directly perform read/write operations.

Example of TCP server and client programs:

import std.time.*
import std.sync.*
import std.net.*

var SERVER_PORT: UInt16 = 0

func runTcpServer() {
    try (serverSocket = TcpServerSocket(bindAt: SERVER_PORT)) {
        serverSocket.bind()
        SERVER_PORT = (serverSocket.localAddress as IPSocketAddress)?.port ?? 0

        try (client = serverSocket.accept()) {
            let buf = Array<Byte>(10, repeat: 0)
            let count = client.read(buf)

            // Data read by server: [1, 2, 3, 0, 0, 0, 0, 0, 0, 0]
            println("Server read ${count} bytes: ${buf}")
        }
    }
}

main(): Int64 {
    let future = spawn {
        runTcpServer()
    }
    sleep(Duration.millisecond * 500)

    try (socket = TcpSocket("127.0.0.1", SERVER_PORT)) {
        socket.connect()
        socket.write([1, 2, 3])
    }

    future.get()

    return 0
}

Compiling and executing the above code will print:

Server read 3 bytes: [1, 2, 3, 0, 0, 0, 0, 0, 0, 0]

UDP Programming

As a common unreliable transmission protocol, using UDP-type sockets as an example, Cangjie’s reference programming model for unreliable transmission scenarios is as follows:

1. Create a socket and specify the local binding address.
2. Perform binding.
3. Specify the remote address for message sending.
4. Without connecting to a remote address, the socket can receive messages from different remote addresses and return the remote address information.

Example of UDP message sending/receiving program:

import std.time.*
import std.sync.*
import std.net.*

let SERVER_PORT: UInt16 = 8080

func runUpdServer() {
    try (serverSocket = UdpSocket(bindAt: SERVER_PORT)) {
        serverSocket.bind()

        let buf = Array<Byte>(3, repeat: 0)
        let (clientAddr, count) = serverSocket.receiveFrom(buf)
        let sender = (clientAddr as IPSocketAddress)?.address.toString() ?? ""

        // Server receive 3 bytes: [1, 2, 3] from 127.0.0.1
        println("Server receive ${count} bytes: ${buf} from ${sender}")
    }
}

main(): Int64 {
    let future = spawn {
        runUpdServer()
    }
    sleep(Duration.second)

    try (udpSocket = UdpSocket(bindAt: 0)) {
        udpSocket.sendTimeout = Duration.second * 2
        udpSocket.bind()
        udpSocket.sendTo(
            IPSocketAddress("127.0.0.1", SERVER_PORT),
            [1, 2, 3]
        )
    }

    future.get()

    return 0
}

Compiling and executing the above code will print:

Server receive 3 bytes: [1, 2, 3] from 127.0.0.1

HTTP Programming

HTTP, as a universal application-layer protocol, facilitates data transmission through a request-response mechanism where the client sends requests and the server returns responses. The format of requests and responses is fixed, consisting of a header and a body.

The most commonly used request types are GET and POST. A GET request contains only a header and is used to request application-layer data from the server. A POST request includes a body, separated from the header by an empty line, and is used to provide application-layer data to the server.

The header fields of request-response messages are numerous and will not be exhaustively detailed here. Cangjie supports HTTP protocol versions 1.0/1.1/2.0, among others. Developers can construct request and response messages based on RFCs 9110, 9112, 9113, 9218, 7541, and the HttpRequestBuilder and HttpResponseBuilder classes provided by Cangjie.

The following example demonstrates how to use Cangjie for client and server programming. The functionality implemented involves the client sending a request with the header GET /hello, and the server returning a response with the body "Hello Cangjie!". The code is as follows:

Note:

Libraries such as net and log have been moved from the Cangjie SDK to the stdx module. Before use, download the software package and configure it in cjpm.toml.

import stdx.net.http.*
import std.time.*
import std.sync.*
import stdx.log.*

// 1. Build a Server instance
let server = ServerBuilder()
    .addr("127.0.0.1")
    .port(0)
    .build()

func startServer(): Unit {
    // 2. Register request handling logic
    server.distributor.register("/hello", {httpContext =>
        httpContext.responseBuilder.body("Hello Cangjie!")
    })
    server.logger.level = LogLevel.OFF
    // 3. Start the service
    server.serve()
}

func startClient(): Unit {
    // 1. Build a client instance
    let client = ClientBuilder().build()
    // 2. Send a request
    let response = client.get("http://127.0.0.1:${server.port}/hello")
    // 3. Read the response body
    let buffer = Array<Byte>(32, repeat: 0)
    let length = response.body.read(buffer)
    println(String.fromUtf8(buffer[..length]))
    // 4. Close the connection
    client.close()
}

main () {
    spawn {
        startServer()
    }
    sleep(Duration.second)
    startClient()
}

Compiling and executing the above code will print:

Hello Cangjie!

WebSocket Programming

In network programming, WebSocket is a commonly used application-layer protocol. Like HTTP, it is also built on top of the TCP protocol and is frequently employed in web server application development.

Unlike HTTP, WebSocket only requires a single handshake between the client and server to establish a persistent connection, enabling bidirectional data transmission. This means that WebSocket-based servers can actively send data to clients, thereby achieving real-time communication.

WebSocket is an independent protocol. Its connection to HTTP lies in the fact that its handshake is interpreted by HTTP servers as an upgrade request. Therefore, Cangjie includes WebSocket within the http package.

Cangjie abstracts the WebSocket communication mechanism into the WebSocket class, providing methods to upgrade an HTTP/1.1 or HTTP/2.0 server handle to a WebSocket protocol instance. Communication is then conducted through the returned WebSocket instance, such as reading and writing data packets.

In Cangjie, the fundamental unit of data transmitted via WebSocket is called a frame. Frames are divided into two categories: one type transmits control information, including Close Frame for closing connections, Ping Frame for implementing Keep-Alive, and Pong Frame as the response type to Ping Frame. The other type transmits application data, supporting segmented transmission.

Cangjie’s frames consist of three attributes: fin and frameType together indicate whether the frame is segmented and its type, while payload represents the frame’s data payload. Developers do not need to concern themselves with other attributes for packet transmission.

The following example demonstrates the WebSocket handshake and message exchange process: creating an HTTP client and server, initiating WebSocket upgrade (or handshake) respectively, and beginning frame read/write operations after a successful handshake.

Note:

Libraries such as net, encoding, and log have been moved from the Cangjie SDK to the stdx module. Before use, download the package and configure it in cjpm.toml.

import stdx.net.http.*
import stdx.encoding.url.*
import std.time.*
import std.sync.*
import std.collection.*
import stdx.log.*

let server = ServerBuilder()
                        .addr("127.0.0.1")
                        .port(0)
                        .build()

// Client:
main() {
    // 1 Start the server
    spawn { startServer() }
    sleep(Duration.millisecond * 200)

    let client = ClientBuilder().build()
    let u = URL.parse("ws://127.0.0.1:${server.port}/webSocket")

    let subProtocol = ArrayList<String>(["foo1", "bar1"])
    let headers = HttpHeaders()
    headers.add("test", "echo")

    // 2 Complete WebSocket handshake and obtain WebSocket instance
    let websocket: WebSocket
    let respHeaders: HttpHeaders
    (websocket, respHeaders) = WebSocket.upgradeFromClient(client, u, subProtocols: subProtocol, headers: headers)
    client.close()

    println("subProtocol: ${websocket.subProtocol}")      // fool1
    println(respHeaders.getFirst("rsp") ?? "") // echo

    // 3 Message exchange
    // Send "hello"
    websocket.write(TextWebFrame, "hello".toArray())
    // Receive
    let data = ArrayList<UInt8>()
    var frame = websocket.read()
    while(true) {
        match(frame.frameType) {
            case ContinuationWebFrame =>
                data.add(all: frame.payload)
                if (frame.fin) {
                    break
                }
            case TextWebFrame | BinaryWebFrame =>
                if (!data.isEmpty()) {
                    throw Exception("invalid frame")
                }
                data.add(all: frame.payload)
                if (frame.fin) {
                    break
                }
            case CloseWebFrame =>
                websocket.write(CloseWebFrame, frame.payload)
                break
            case PingWebFrame =>
                websocket.writePongFrame(frame.payload)
            case _ => ()
        }
        frame = websocket.read()
    }
    println("data size: ${data.size}")      // 4097
    println("last item: ${String.fromUtf8(data.toArray()[4096])}")        // a


    // 4 Close WebSocket
    // Exchange CloseFrame
    websocket.writeCloseFrame(status: 1000)
    let websocketFrame = websocket.read()
    println("close frame type: ${websocketFrame.frameType}")      // CloseWebFrame
    println("close frame payload: ${websocketFrame.payload}")     // 3, 232
    // Close underlying connection
    websocket.closeConn()

    server.close()
}

func startServer() {
    // 1 Register handler
    server.distributor.register("/webSocket", handler1)
    server.logger.level = LogLevel.OFF
    server.serve()
}

// Server:
func handler1(ctx: HttpContext): Unit {
    // 2 Complete WebSocket handshake and obtain WebSocket instance
    let websocketServer = WebSocket.upgradeFromServer(ctx, subProtocols: ArrayList<String>(["foo", "bar", "foo1"]),
        userFunc: {request: HttpRequest =>
            let value = request.headers.getFirst("test") ?? ""
            let headers = HttpHeaders()
            headers.add("rsp", value)
            headers
        })
    // 3 Message exchange
    // Receive "hello"
    let data = ArrayList<UInt8>()
    var frame = websocketServer.read()
    while(true) {
        match(frame.frameType) {
            case ContinuationWebFrame =>
                data.add(all: frame.payload)
                if (frame.fin) {
                    break
                }
            case TextWebFrame | BinaryWebFrame =>
                if (!data.isEmpty()) {
                    throw Exception("invalid frame")
                }
                data.add(all: frame.payload)
                if (frame.fin) {
                    break
                }
            case CloseWebFrame =>
                websocketServer.write(CloseWebFrame, frame.payload)
                break
            case PingWebFrame =>
                websocketServer.writePongFrame(frame.payload)
            case _ => ()
        }
        frame = websocketServer.read()
    }
    println("data: ${String.fromUtf8(data.toArray())}")    // hello
    // Send 4097 'a's
    websocketServer.write(TextWebFrame, Array<UInt8>(4097, repeat: 97))

    // 4 Close WebSocket
    // Exchange CloseFrame
    let websocketFrame = websocketServer.read()
    println("close frame type: ${websocketFrame.frameType}")   // CloseWebFrame
    println("close frame payload: ${websocketFrame.payload}")     // 3, 232
    websocketServer.write(CloseWebFrame, websocketFrame.payload)
    // Close underlying connection
    websocketServer.closeConn()
}

The example produces the following output:

subProtocol: foo1
echo
data: hello
data size: 4097
last item: a
close frame type: CloseWebFrame
close frame payload: [3, 232]
close frame type: CloseWebFrame
close frame payload: [3, 232]

Introduction to Macros

Macros can be understood as a special type of function. While regular functions perform computations on input values and output a new value, macros take and return the program itself. They accept a piece of code as input and output a new piece of code, which is then used for compilation and execution. To distinguish macro calls from function calls, macros are invoked using @ followed by the macro name.

The following example demonstrates printing both the value and the expression itself during debugging:

let x = 3
let y = 2
@dprint(x)        // Prints "x = 3"
@dprint(x + y)    // Prints "x + y = 5"

Clearly, dprint cannot be implemented as a regular function because functions only receive the value of the input expression, not the expression itself. However, dprint can be implemented as a macro to access the code fragment of the input expression. A basic implementation is shown below:

macro package define

import std.ast.*

public macro dprint(input: Tokens): Tokens {
    let inputStr = input.toString()
    let result = quote(
        print($(inputStr) + " = ")
        println($(input)))
    return result
}

Before explaining each line, let’s verify this macro achieves the desired effect. First, create a define directory in the current folder, then create a dprint.cj file inside it with the above content. Additionally, create a main.cj file in the current directory with the following test code:

import define.*

main() {
    let x = 3
    let y = 2
    @dprint(x)
    @dprint(x + y)
}

Note the resulting directory structure:

// Directory layout.
src
|-- define
|     `-- dprint.cj
`-- main.cj

In the current directory (src), run the compilation commands:

cjc define/*.cj --compile-macro
cjc main.cj -o main

Then execute ./main to see the following output:

x = 3
x + y = 5

Now let’s examine each part of the code:

• Line 1: macro package define

  Macros must be declared in separate packages (they cannot coexist with other public functions). Packages containing macros are declared using macro package. Here we declare a macro package named define.

• Line 2: import std.ast.*

  The data types required for macro implementation, such as Tokens and syntax node types (to be discussed later), are located in the ast package of the Cangjie standard library. Therefore, any macro implementation must first import the ast package.

• Line 3: public macro dprint(input: Tokens): Tokens

  This declares a macro named dprint. Since this is a non-attribute macro (this concept will be explained later), it accepts a parameter of type Tokens, representing the code fragment passed to the macro. The macro’s return value is also a code fragment.

• Line 4: let inputStr = input.toString()

  In the macro implementation, we first convert the input code fragment to a string. In our test cases, inputStr becomes "x" or "x + y".

• Lines 5-7: let result = quote(...)

  The quote expression is used to construct Tokens. It converts the code fragment within parentheses into Tokens. Inside quote, interpolation $(...) can be used to convert the enclosed expression into Tokens and insert it into the Tokens constructed by quote. In this code, $(inputStr) inserts the value of inputStr (including quotation marks), while $(input) inserts the input code fragment. Thus, if the input expression is x + y, the resulting Tokens would be:

  print("x + y" + " = ")
  println(x + y)
  

• Line 8: return result

  Finally, the constructed code fragment is returned. These two lines of code will be compiled, and when executed, will output x + y = 5.

Reviewing the dprint macro definition: it uses Tokens as input and employs quote with interpolation to construct another Tokens as output. To work with macros effectively, we need detailed understanding of Tokens, quote, and interpolation concepts, which will be introduced separately below.

Token-Related Types and Quote Expressions

Token Type

The fundamental type for macro operations is Tokens, representing a code fragment. Tokens consist of multiple Token elements, where each Token can be understood as a user-operable lexical unit. A Token may be an identifier (e.g., variable names), literal (e.g., integers, floats, strings), keyword, or operator. Each Token contains its type, content, and positional information.

The type of a Token is an enum value from TokenKind. For available values of TokenKind, refer to the Cangjie Programming Language Library API documentation. By providing TokenKind and Token values (the identifier or literal corresponding to TokenKind), any Token can be directly constructed. The specific constructors are as follows:

Token(k: TokenKind)
Token(k: TokenKind, v: String)

Below are some examples of Token construction:

import std.ast.*

let tk1 = Token(TokenKind.ADD)   // '+' operator
let tk2 = Token(TokenKind.FUNC)   // func keyword
let tk3 = Token(TokenKind.IDENTIFIER, "x")   // x identifier
let tk4 = Token(TokenKind.INTEGER_LITERAL, "3")  // integer literal
let tk5 = Token(TokenKind.STRING_LITERAL, "xyz")  // string literal

Tokens Type

A Tokens represents a sequence composed of multiple Token elements. Tokens can be constructed directly from an array of Token. Below are three basic ways to construct Tokens instances:

Tokens()   // construct an empty list
Tokens(tks: Array<Token>)
Tokens(tks: ArrayList<Token>)

Additionally, the Tokens type supports the following functionalities:

• size: Returns the number of Token elements contained in Tokens
• get(index: Int64): Retrieves the Token element at the specified index
• []: Retrieves the Token element at the specified index
• +: Concatenates two Tokens or directly concatenates Tokens with a Token
• dump(): Prints all contained Token elements for debugging purposes
• toString(): Prints the code fragment corresponding to Tokens

In the following example, constructors are used to directly create Token and Tokens, followed by printing detailed debugging information:

import std.ast.*

let tks = Tokens([
    Token(TokenKind.INTEGER_LITERAL, "1"),
    Token(TokenKind.ADD),
    Token(TokenKind.INTEGER_LITERAL, "2")
])
main() {
    println(tks)
    tks.dump()
}

The expected output is as follows (specific positional information may vary):

1 + 2
description: integer_literal, token_id: 140, token_literal_value: 1, fileID: 1, line: 4, column: 5
description: add, token_id: 12, token_literal_value: +, fileID: 1, line: 5, column: 5
description: integer_literal, token_id: 140, token_literal_value: 2, fileID: 1, line: 6, column: 5

The dump information includes each Token’s type (description) and value (token_literal_value), followed by the positional information of each Token.

Quote Expression and Interpolation

In most cases, directly constructing and concatenating Tokens can be cumbersome. Therefore, the Cangjie language provides the quote expression to construct Tokens from code templates. The term “code template” is used because quote allows the use of $(...) to interpolate expressions from the context. The interpolated expressions must be convertible to Tokens (specifically, they must implement the ToTokens interface). In the standard library, the following types implement the ToTokens interface:

• All node types (nodes will be discussed in Syntax Nodes)
• Token and Tokens types
• All primitive data types: integers, floats, Bool, Rune, and String
• Array<T> and ArrayList<T>, where T has type restrictions and outputs different delimiters based on T’s type. For details, refer to the Cangjie Programming Language Library API documentation.

The following example demonstrates interpolation with Array and primitive data types:

import std.ast.*

let intList: Array<Int64> = [1, 2, 3, 4, 5]
let float: Float64 = 1.0
let str: String = "Hello"
let tokens = quote(
    arr = $(intList)
    x = $(float)
    s = $(str)
)

main() {
    println(tokens)
}

The output is:

arr =[1, 2, 3, 4, 5]
x = 1.0
s = "Hello"

For more interpolation usage, refer to Using Quote to Interpolate Syntax Nodes.

Specifically, when a quote expression contains certain special Token elements, escaping is required:

• Unmatched parentheses are not allowed in quote expressions, but parentheses escaped with \ are exempt from the matching rules.
• When $ represents a regular Token rather than code interpolation, it must be escaped with \.
• Except for the above cases, the presence of \ in quote expressions will result in a compilation error.

Note:

The # symbol can only be used to construct multiline raw string literals and cannot be used standalone.

Below are some examples of quote expressions containing these special Token elements:

import std.ast.*

let tks1 = quote((x))       // ok
let tks2 = quote(\()        // ok
let tks3 = quote( ( \) ) )  // ok
let tks4 = quote())         // error: unmatched delimiter: ')'
let tks5 = quote( ( \) )    // error: unclosed delimiter: '('
let tks6 = quote(\$(1))     // ok
let tks7 = quote(\x)        // error: unknown start of token: \
let tks8 = quote(#)         // error: expected '#' or '"' in raw string

Syntax Nodes

In the compilation process of the Cangjie language, the code is first converted into Tokens through lexical analysis, followed by syntactic parsing of the Tokens to generate a syntax tree. Each node in the syntax tree may represent an expression, declaration, type, pattern, etc. The Cangjie standard library std.ast package provides corresponding classes for each type of node, with appropriate inheritance relationships. The main abstract classes are as follows:

• Node: The parent class of all syntax nodes
• TypeNode: The parent class of all type nodes
• Expr: The parent class of all expression nodes
• Decl: The parent class of all declaration nodes
• Pattern: The parent class of all pattern nodes

There are numerous specific node types. For detailed information, please refer to the Cangjie Programming Language Library API. The following examples primarily use the following nodes:

• BinaryExpr: Binary operation expressions
• FuncDecl: Function declarations

Parsing Nodes

Using the std.ast standard library package, virtually any node can be parsed from Tokens. There are two methods for parsing Tokens and constructing syntax nodes.

Parsing Tokens Using Parsing Functions

The following functions are used to parse and construct arbitrary syntax nodes from Tokens:

• parseExpr(input: Tokens): Expr: Parses the input Tokens into an expression node.
• parseExprFragment(input: Tokens, startFrom!: Int64 = 0): (Expr, Int64): Parses a fragment of the input Tokens into an expression node, starting from the startFrom index. The parsing may consume only part of the fragment starting from startFrom and returns the index of the first unconsumed Token (if the entire fragment is consumed, the return value is input.size).
• parseDecl(input: Tokens, astKind!: String = ""): Parses the input Tokens into a declaration node. astKind provides additional settings; refer to the Cangjie Programming Language Library API for details.
• parseDeclFragment(input: Tokens, startFrom!: Int64 = 0): (Decl, Int64): Parses a fragment of the input Tokens into a declaration node. The startFrom parameter and the meaning of the returned index are the same as in parseExpr.
• parseType(input: Tokens): TypeNode: Parses the input Tokens into a type node.
• parseTypeFragment(input: Tokens, startFrom!: Int64 = 0): (TypeNode, Int64): Parses a fragment of the input Tokens into a type node. The startFrom parameter and the meaning of the returned index are the same as in parseExpr.
• parsePattern(input: Tokens): Pattern: Parses the input Tokens into a pattern node.
• parsePatternFragment(input: Tokens, startFrom!: Int64 = 0): (Pattern, Int64): Parses a fragment of the input Tokens into a pattern node. The startFrom parameter and the meaning of the returned index are the same as in parseExpr.

If parsing fails, an exception is thrown. This parsing method is suitable for code fragments of unknown types. If a specific subtype node is required, the parsing result must be manually cast to the corresponding subtype.

Usage examples of these functions are shown below:

let tks1 = quote(a + b)
let tks2 = quote(u + v, x + y)
let tks3 = quote(
    func f1(x: Int64) { return x + 1 }
)
let tks4 = quote(
    func f2(x: Int64) { return x + 2 }
    func f3(x: Int64) { return x + 3 }
)

let binExpr1 = parseExpr(tks1)
let (binExpr2, mid) = parseExprFragment(tks2)
let (binExpr3, _) = parseExprFragment(tks2, startFrom: mid + 1) // Skip the comma
println("binExpr1 = ${binExpr1.toTokens()}")
println("binExpr2 = ${binExpr2.toTokens()}, binExpr3 = ${binExpr3.toTokens()}")
let funcDecl1 = parseDecl(tks3)
let (funcDecl2, mid2) = parseDeclFragment(tks4)
let (funcDecl3, _) = parseDeclFragment(tks4, startFrom: mid2)
println("${funcDecl1.toTokens()}")
println("${funcDecl2.toTokens()}")
println("${funcDecl3.toTokens()}")

Output:

binExpr1 = a + b
binExpr2 = u + v, binExpr3 = x + y
func f1(x: Int64) {
    return x + 1
}

func f2(x: Int64) {
    return x + 2
}

func f3(x: Int64) {
    return x + 3
}

Parsing Tokens Using Syntax Node Constructors

Most syntax nodes support the init(input: Tokens) constructor, which parses the input Tokens into a node of the corresponding type. For example:

import std.ast.*

let binExpr = BinaryExpr(quote(a + b))
let funcDecl = FuncDecl(quote(func f1(x: Int64) { return x + 1 }))

If parsing fails, an exception is thrown. This parsing method is suitable for code fragments of known types, eliminating the need for manual casting to specific subtypes after parsing.

Components of Nodes

After parsing nodes from Tokens, you can examine their components. For illustration, only the components of BinaryExpr and FuncDecl are listed here. For more detailed explanations of other nodes, refer to the Cangjie Programming Language Library API.

• BinaryExpr node:
  • leftExpr: Expr: The expression on the left side of the operator
  • op: Token: The operator
  • rightExpr: Expr: The expression on the right side of the operator
• FuncDecl node (partial):
  • identifier: Token: The function name
  • funcParams: ArrayList<FuncParam>: The parameter list
  • declType: TypeNode: The return type
  • block: Block: The function body
• FuncParam node (partial):
  • identifier: Token: The parameter name
  • paramType: TypeNode: The parameter type
• Block node (partial):
  • nodes: ArrayList<Node>: Expressions and declarations within the block

Each component is a public mut prop and can be inspected and updated. The results of such updates are demonstrated in the following examples.

BinaryExpr Example

let binExpr = BinaryExpr(quote(x * y))
binExpr.leftExpr = BinaryExpr(quote(a + b))
println(binExpr.toTokens())

binExpr.op = Token(TokenKind.ADD)
println(binExpr.toTokens())

Output:

(a + b) * y
a + b + y

First, parsing yields binExpr as the node x * y, represented as:

    *
  /   \
 x     y

Next, the left node (x) is replaced with a + b, resulting in the following syntax tree:

      *
    /   \
   +     y
  / \
 a   b

When outputting this syntax tree, parentheses must be added around a + b to yield (a + b) * y (outputting a + b * y would imply multiplication before addition, which contradicts the syntax tree’s meaning). The ast library automatically adds parentheses when outputting syntax trees.

Finally, the operator at the root of the syntax tree is changed from * to +, resulting in:

      +
    /   \
   +     y
  / \
 a   b

This syntax tree can be output as a + b + y since addition is left-associative and does not require parentheses on the left side.

FuncDecl Example

let funcDecl = FuncDecl(quote(func f1(x: Int64) { x + 1 }))
funcDecl.identifier = Token(TokenKind.IDENTIFIER, "foo")
println("Number of parameters: ${funcDecl.funcParams.size}")
funcDecl.funcParams[0].identifier = Token(TokenKind.IDENTIFIER, "a")
println("Number of nodes in body: ${funcDecl.block.nodes.size}")
let binExpr = (funcDecl.block.nodes[0] as BinaryExpr).getOrThrow()
binExpr.leftExpr = parseExpr(quote(a))
println(funcDecl.toTokens())

In this example, a FuncDecl node is first constructed through parsing. The function name, parameter name, and part of the expression in the function body are then modified. Output:

Number of parameters: 1
Number of nodes in body: 1
func foo(a: Int64) {
    a + 1
}

Interpolating Syntax Nodes Using quote

Any syntax node can be interpolated within a quote statement. Some ArrayList lists of syntax nodes can also be interpolated (primarily corresponding to scenarios where such node lists are encountered in practice). Interpolation is achieved via $(node), where node is an instance of any node type.

The following examples demonstrate node interpolation.

var binExpr = BinaryExpr(quote(1 + 2))
let a = quote($(binExpr))
let b = quote($binExpr)
let c = quote($(binExpr.leftExpr))
let d = quote($binExpr.leftExpr)
println("a: ${a.toTokens()}")
println("b: ${b.toTokens()}")
println("c: ${c.toTokens()}")
println("d: ${d.toTokens()}")

Output:

a: 1 + 2
b: 1 + 2
c: 1
d: 1 + 2.leftExpr

Generally, the expression following the interpolation operator is enclosed in parentheses to define its scope, e.g., $(binExpr). However, when followed by a single identifier, parentheses can be omitted, as in $binExpr. Thus, in the example, both a and b interpolate the binExpr node within quote, resulting in 1 + 2. However, if the expression following the interpolation operator is more complex, omitting parentheses may lead to scope errors. For instance, the expression binExpr.leftExpr evaluates to the left expression of 1 + 2, i.e., 1, so c is correctly assigned 1. However, in d, the interpolation is interpreted as ($binExpr).leftExpr, resulting in 1 + 2.leftExpr. To clarify the scope of interpolation, it is recommended to use parentheses with the interpolation operator.

The following example demonstrates interpolation of node lists (ArrayList).

var incrs = ArrayList<Node>()
for (i in 1..=5) {
    incrs.add(parseExpr(quote(x += $(i))))
}
var foo = quote(
    func foo(n: Int64) {
        let x = n
        $(incrs)
        x
    })
println(foo)

Output:

func foo(n: Int64) {
    let x = n
    x += 1
    x += 2
    x += 3
    x += 4
    x += 5
    x
}

In this example, a node list incrs is created, containing expressions x += 1, …, x += 5. Interpolating incrs lists the nodes sequentially, with line breaks after each node. This is useful for inserting expressions and declarations that need to be executed sequentially.

The following example demonstrates cases where parentheses are necessary around interpolations to ensure correctness.

var binExpr1 = BinaryExpr(quote(x + y))
var binExpr2 = BinaryExpr(quote($(binExpr1) * z))       // Incorrect: yields x + y * z
println("binExpr2: ${binExpr2.toTokens()}")
println("binExpr2.leftExpr: ${binExpr2.leftExpr.toTokens()}")
println("binExpr2.rightExpr: ${binExpr2.rightExpr.toTokens()}")
var binExpr3 = BinaryExpr(quote(($(binExpr1)) * z))     // Correct: yields (x + y) * z
println("binExpr3: ${binExpr3.toTokens()}")

Output:

binExpr2: x + y * z
binExpr2.leftExpr: x
binExpr2.rightExpr: y * z
binExpr3: (x + y) * z

First, the expression x + y is constructed and then interpolated into the template $(binExpr1) * z. The intention is to obtain an expression that first computes x + y and then multiplies by z. However, the interpolation yields x + y * z, which computes y * z first and then adds x. This occurs because interpolation does not automatically add parentheses to ensure the atomicity of the interpolated expression (unlike the replacement of leftExpr described earlier). Thus, parentheses must be added around $(binExpr1) to ensure the correct result.

Macro Implementation

This chapter introduces the definition and usage of Cangjie macros, which can be categorized into Non-Attribute Macros and Attribute Macros. Additionally, this chapter will cover the behavior when macros are nested.

Non-Attribute Macros

Non-attribute macros only accept the code to be transformed and do not take other parameters (attributes). Their definition format is as follows:

import std.ast.*

public macro MacroName(args: Tokens): Tokens {
    ... // Macro body
}

The macro invocation format is as follows:

@MacroName(...)

Macro invocations are enclosed in (). The content inside the parentheses can be any valid Tokens or empty.

When a macro is applied to a declaration, the parentheses can generally be omitted. Refer to the following examples:

@MacroName func name() {}        // Before a FuncDecl
@MacroName struct name {}        // Before a StructDecl
@MacroName class name {}         // Before a ClassDecl
@MacroName var a = 1             // Before a VarDecl
@MacroName enum e {}             // Before a Enum
@MacroName interface i {}        // Before a InterfaceDecl
@MacroName extend e <: i {}      // Before a ExtendDecl
class C {
    @MacroName prop i: Int64 {   // Before a PropDecl
        get() { 0 }
    }
} 
@MacroName @AnotherMacro(input)  // Before a macro call

Special notes on the legality of Tokens within parentheses:

• The input must consist of a sequence of valid Tokens. Symbols like “#”, “`”, “\”, etc., when used alone, are not valid Cangjie Tokens and are not supported as input values.

• If the input contains unmatched parentheses, they must be escaped using the escape symbol “\”.

• If the input contains “@” as a Token, it must be escaped using the escape symbol “\”.