return

The return statement is used to exit a function and optionally return a value to the caller. It immediately terminates function execution and passes control back to the calling code.

Basic Return Statement

Return values from functions:

soul add(a, b) {
    return a + b
}

soul greet(name) {
    return "Hello, " + name
}

// Usage
result = add(5, 3)      // 8
message = greet("Alice") // "Hello, Alice"

Return Without Value

Return without a specific value (returns null):

soul printMessage(message) {
    println(message)
    return  // Explicit return without value
}

soul processData(data) {
    if (data == null) {
        return  // Early return
    }
    
    // Process data here
    println("Processing: " + data)
}

Early Return

Use return for early exit from functions:

soul validateUser(user) {
    if (user == null) {
        return "User is null"
    }
    
    if (user.name == null || user.name == "") {
        return "Name is required"
    }
    
    if (user.age < 0 || user.age > 150) {
        return "Invalid age"
    }
    
    return "Valid user"
}

Return with Expressions

Return the result of expressions:

soul calculateDiscount(price, percentage) {
    return price * (percentage / 100)
}

soul isAdult(age) {
    return age >= 18
}

soul getFullName(firstName, lastName) {
    return firstName + " " + lastName
}

Return with Complex Values

Return objects, arrays, and complex data structures:

soul createUser(name, email) {
    return {
        "name": name,
        "email": email,
        "isActive": true,
        "createdAt": new Date()
    }
}

soul getNumbers(start, end) {
    numbers = []
    for (i = start; i <= end; i++) {
        numbers.push(i)
    }
    return numbers
}

Return in Conditional Statements

Return different values based on conditions:

soul getGrade(score) {
    if (score >= 90) {
        return "A"
    } else if (score >= 80) {
        return "B"
    } else if (score >= 70) {
        return "C"
    } else if (score >= 60) {
        return "D"
    } else {
        return "F"
    }
}

soul processResult(success, data, error) {
    if (success) {
        return {
            "status": "success",
            "data": data
        }
    } else {
        return {
            "status": "error",
            "error": error
        }
    }
}

Return in Loops

Return from within loops:

soul findUser(users, id) {
    for (user in users) {
        if (user.id == id) {
            return user  // Found user, return immediately
        }
    }
    return null  // User not found
}

soul findFirstEven(numbers) {
    for (num in numbers) {
        if (num % 2 == 0) {
            return num
        }
    }
    return null
}

Return with Error Handling

Return error states and success states:

soul divide(a, b) {
    if (b == 0) {
        return {
            "success": false,
            "error": "Division by zero"
        }
    }
    
    return {
        "success": true,
        "result": a / b
    }
}

soul parseNumber(str) {
    if (str == null || str == "") {
        return {
            "success": false,
            "error": "Empty string"
        }
    }
    
    try {
        num = Number(str)
        return {
            "success": true,
            "value": num
        }
    } catch (error) {
        return {
            "success": false,
            "error": "Invalid number format"
        }
    }
}

Return in Async Functions

Return values from async functions:

async soul fetchUserData(userId) {
    response = await http.get("/api/users/" + userId)
    return response.json()
}

async soul processAsync(data) {
    if (data == null) {
        return {
            "success": false,
            "error": "No data provided"
        }
    }
    
    result = await processData(data)
    return {
        "success": true,
        "result": result
    }
}

Return in Class Methods

Return values from class methods:

sanctuary User {
    soul __genesis__(name, email) {
        this.name = name
        this.email = email
        this.isActive = true
    }
    
    soul getName() {
        return this.name
    }
    
    soul getInfo() {
        return {
            "name": this.name,
            "email": this.email,
            "isActive": this.isActive
        }
    }
    
    soul activate() {
        this.isActive = true
        return this  // Return self for chaining
    }
}

Return for Method Chaining

Return objects to enable method chaining:

sanctuary Builder {
    soul __genesis__() {
        this.data = {}
    }
    
    soul setName(name) {
        this.data.name = name
        return this  // Enable chaining
    }
    
    soul setAge(age) {
        this.data.age = age
        return this  // Enable chaining
    }
    
    soul build() {
        return this.data
    }
}

// Usage with method chaining
user = Builder.new()
    .setName("Alice")
    .setAge(30)
    .build()

Return with Validation

Return validation results:

soul validateEmail(email) {
    if (email == null || email == "") {
        return {
            "valid": false,
            "error": "Email is required"
        }
    }
    
    if (!email.contains("@")) {
        return {
            "valid": false,
            "error": "Email must contain @"
        }
    }
    
    if (!email.contains(".")) {
        return {
            "valid": false,
            "error": "Email must contain domain"
        }
    }
    
    return {
        "valid": true,
        "email": email.toLowerCase()
    }
}

Return with Computed Values

Return computed or calculated values:

soul calculateStatistics(numbers) {
    if (numbers == null || numbers.length() == 0) {
        return {
            "count": 0,
            "sum": 0,
            "average": 0,
            "min": 0,
            "max": 0
        }
    }
    
    sum = 0
    min = numbers[0]
    max = numbers[0]
    
    for (num in numbers) {
        sum += num
        if (num < min) min = num
        if (num > max) max = num
    }
    
    return {
        "count": numbers.length(),
        "sum": sum,
        "average": sum / numbers.length(),
        "min": min,
        "max": max
    }
}

Return with Resource Cleanup

Return after cleaning up resources:

soul processFile(filename) {
    file = null
    
    try {
        file = openFile(filename)
        
        if (file == null) {
            return {
                "success": false,
                "error": "Could not open file"
            }
        }
        
        data = file.read()
        result = processData(data)
        
        return {
            "success": true,
            "result": result
        }
    } catch (error) {
        return {
            "success": false,
            "error": error.toString()
        }
    } finally {
        if (file != null) {
            file.close()
        }
    }
}

Return Best Practices

Guidelines for using return statements:

// Good - clear return values
soul calculatePrice(quantity, unitPrice) {
    if (quantity <= 0) {
        return 0
    }
    
    if (unitPrice <= 0) {
        return 0
    }
    
    return quantity * unitPrice
}

// Better - comprehensive return structure
soul calculatePrice(quantity, unitPrice) {
    // Validate inputs
    if (quantity == null || unitPrice == null) {
        return {
            "success": false,
            "error": "Missing required parameters",
            "price": 0
        }
    }
    
    if (quantity <= 0) {
        return {
            "success": false,
            "error": "Quantity must be positive",
            "price": 0
        }
    }
    
    if (unitPrice <= 0) {
        return {
            "success": false,
            "error": "Unit price must be positive",
            "price": 0
        }
    }
    
    // Calculate price
    totalPrice = quantity * unitPrice
    
    return {
        "success": true,
        "price": totalPrice,
        "quantity": quantity,
        "unitPrice": unitPrice
    }
}

Best Practices

Return early: Use early returns to avoid deep nesting
Return meaningful values: Make return values clear and useful
Be consistent: Use consistent return patterns throughout your code
Handle all cases: Ensure all code paths return appropriate values
Document return values: Make it clear what functions return

// Good - early return pattern
soul processUser(user) {
    if (user == null) {
        return null
    }
    
    if (!user.isActive) {
        return null
    }
    
    if (user.age < 18) {
        return null
    }
    
    return {
        "name": user.name,
        "email": user.email,
        "status": "processed"
    }
}

// Better - descriptive return values
soul processUser(user) {
    if (user == null) {
        return { success: false, error: "User is null" }
    }
    
    if (!user.isActive) {
        return { success: false, error: "User is inactive" }
    }
    
    if (user.age < 18) {
        return { success: false, error: "User is under 18" }
    }
    
    return {
        success: true,
        user: {
            name: user.name,
            email: user.email,
            status: "processed"
        }
    }
}

The return statement is essential for controlling function flow and providing results to calling code. Use it effectively to create clear, predictable, and maintainable functions.

CLI Usage

Modules

Syntaxes

return

return

Basic Return Statement

Return Without Value

Early Return

Return with Expressions

Return with Complex Values

Return in Conditional Statements

Return in Loops

Return with Error Handling

Return in Async Functions

Return in Class Methods

Return for Method Chaining

Return with Validation

Return with Computed Values

Return with Resource Cleanup

Return Best Practices

Best Practices

​return

​Basic Return Statement

​Return Without Value

​Early Return

​Return with Expressions

​Return with Complex Values

​Return in Conditional Statements

​Return in Loops

​Return with Error Handling

​Return in Async Functions

​Return in Class Methods

​Return for Method Chaining

​Return with Validation

​Return with Computed Values

​Return with Resource Cleanup

​Return Best Practices

​Best Practices

return

Basic Return Statement

Return Without Value

Early Return

Return with Expressions

Return with Complex Values

Return in Conditional Statements

Return in Loops

Return with Error Handling

Return in Async Functions

Return in Class Methods

Return for Method Chaining

Return with Validation

Return with Computed Values

Return with Resource Cleanup

Return Best Practices

Best Practices