list

Lists in Soul are ordered collections of elements that can hold values of any type. They are created using square brackets [] and provide dynamic resizing and various methods for manipulation.

Basic List Creation

Create lists with square bracket notation:

// Empty list
empty = []

// List with elements
numbers = [1, 2, 3, 4, 5]
names = ["Alice", "Bob", "Charlie"]
mixed = [1, "hello", true, null]

List with Different Data Types

Lists can contain mixed data types:

mixedList = [
    42,
    "string",
    true,
    null,
    [1, 2, 3],
    {"key": "value"}
]

Accessing List Elements

Use index notation to access elements:

fruits = ["apple", "banana", "cherry"]

first = fruits[0]        // "apple"
second = fruits[1]       // "banana"
last = fruits[2]         // "cherry"

// Using length for last element
lastIndex = fruits.length() - 1
lastFruit = fruits[lastIndex]

Modifying List Elements

Change elements using index assignment:

colors = ["red", "green", "blue"]

colors[0] = "yellow"     // ["yellow", "green", "blue"]
colors[2] = "purple"     // ["yellow", "green", "purple"]

List Methods

Common list operations:

items = [1, 2, 3]

// Add elements
items.push(4)           // [1, 2, 3, 4]
items.push(5, 6)        // [1, 2, 3, 4, 5, 6]

// Remove elements
last = items.pop()      // Returns 6, list becomes [1, 2, 3, 4, 5]
first = items.shift()   // Returns 1, list becomes [2, 3, 4, 5]

// Add to beginning
items.unshift(0)        // [0, 2, 3, 4, 5]

// Get length
length = items.length() // 5

List Concatenation

Combine lists together:

list1 = [1, 2, 3]
list2 = [4, 5, 6]

// Concatenate lists
combined = list1 + list2        // [1, 2, 3, 4, 5, 6]

// Using concat method (if available)
combined = list1.concat(list2)  // [1, 2, 3, 4, 5, 6]

List Slicing

Extract portions of lists:

numbers = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]

// Slice methods (if available)
portion = numbers.slice(2, 5)   // [2, 3, 4]
fromIndex = numbers.slice(3)    // [3, 4, 5, 6, 7, 8, 9]

Nested Lists

Lists can contain other lists:

matrix = [
    [1, 2, 3],
    [4, 5, 6],
    [7, 8, 9]
]

// Access nested elements
element = matrix[1][2]  // 6
row = matrix[0]         // [1, 2, 3]

// Modify nested elements
matrix[0][0] = 10       // Changes 1 to 10

List Iteration

Iterate through list elements:

items = ["apple", "banana", "cherry"]

// For-in loop
for (item in items) {
    println("Item: " + item)
}

// Traditional for loop
for (i = 0; i < items.length(); i++) {
    println("Index " + i + ": " + items[i])
}

List Searching

Find elements in lists:

numbers = [10, 20, 30, 40, 50]

// Linear search
soul findElement(list, target) {
    for (i = 0; i < list.length(); i++) {
        if (list[i] == target) {
            return i
        }
    }
    return -1
}

index = findElement(numbers, 30)  // 2

List Filtering

Filter elements based on conditions:

numbers = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]

// Filter even numbers
soul filterEven(list) {
    result = []
    for (num in list) {
        if (num % 2 == 0) {
            result.push(num)
        }
    }
    return result
}

evenNumbers = filterEven(numbers)  // [2, 4, 6, 8, 10]

List Mapping

Transform list elements:

numbers = [1, 2, 3, 4, 5]

// Double each number
soul doubleNumbers(list) {
    result = []
    for (num in list) {
        result.push(num * 2)
    }
    return result
}

doubled = doubleNumbers(numbers)  // [2, 4, 6, 8, 10]

List Reduction

Reduce list to a single value:

numbers = [1, 2, 3, 4, 5]

// Sum all numbers
soul sum(list) {
    total = 0
    for (num in list) {
        total += num
    }
    return total
}

total = sum(numbers)  // 15

List Sorting

Sort list elements:

numbers = [3, 1, 4, 1, 5, 9, 2, 6]

// Simple bubble sort
soul bubbleSort(list) {
    n = list.length()
    for (i = 0; i < n - 1; i++) {
        for (j = 0; j < n - i - 1; j++) {
            if (list[j] > list[j + 1]) {
                // Swap elements
                temp = list[j]
                list[j] = list[j + 1]
                list[j + 1] = temp
            }
        }
    }
    return list
}

sorted = bubbleSort(numbers)  // [1, 1, 2, 3, 4, 5, 6, 9]

List of Objects

Work with lists containing objects:

users = [
    {"name": "Alice", "age": 25},
    {"name": "Bob", "age": 30},
    {"name": "Charlie", "age": 35}
]

// Access object properties
firstName = users[0]["name"]        // "Alice"
firstAge = users[0]["age"]          // 25

// Modify object properties
users[1]["age"] = 31

// Filter objects
soul findUsersByAge(users, minAge) {
    result = []
    for (user in users) {
        if (user["age"] >= minAge) {
            result.push(user)
        }
    }
    return result
}

adults = findUsersByAge(users, 30)

List Validation

Validate list contents:

soul validateNumberList(list) {
    if (list == null) {
        return false
    }
    
    for (item in list) {
        if (typeof item != "number") {
            return false
        }
    }
    
    return true
}

soul validateNonEmpty(list) {
    return list != null && list.length() > 0
}

List Utilities

Common list utility functions:

// Check if list contains element
soul contains(list, element) {
    for (item in list) {
        if (item == element) {
            return true
        }
    }
    return false
}

// Get unique elements
soul unique(list) {
    result = []
    for (item in list) {
        if (!contains(result, item)) {
            result.push(item)
        }
    }
    return result
}

// Reverse list
soul reverse(list) {
    result = []
    for (i = list.length() - 1; i >= 0; i--) {
        result.push(list[i])
    }
    return result
}

List Performance

Optimize list operations:

// Pre-allocate known size (if supported)
largeList = []

// Cache length in loops
items = getItems()
length = items.length()

for (i = 0; i < length; i++) {
    processItem(items[i])
}

// Batch operations
soul batchProcess(items) {
    results = []
    for (item in items) {
        result = processItem(item)
        results.push(result)
    }
    return results
}

Best Practices

Check for null/empty: Always validate lists before use
Use appropriate methods: Choose the right operation for your needs
Cache length: Store list length in variables for performance
Handle bounds: Check indices before accessing elements
Use meaningful names: Make list purpose clear

// Good - clear and safe
soul processUserData(users) {
    if (users == null || users.length() == 0) {
        return []
    }
    
    processedUsers = []
    
    for (user in users) {
        if (user != null && user.isValid()) {
            processedUser = processUser(user)
            processedUsers.push(processedUser)
        }
    }
    
    return processedUsers
}

// Better - with error handling
soul processUserData(users) {
    if (users == null || users.length() == 0) {
        return { success: false, error: "No users provided" }
    }
    
    processedUsers = []
    errors = []
    
    for (user in users) {
        try {
            if (user != null && user.isValid()) {
                processedUser = processUser(user)
                processedUsers.push(processedUser)
            }
        } catch (error) {
            errors.push("Error processing user: " + error)
        }
    }
    
    return { 
        success: true, 
        users: processedUsers, 
        errors: errors 
    }
}

Lists are fundamental data structures in Soul, providing flexible and powerful ways to store and manipulate collections of data.

CLI Usage

Modules

Syntaxes

list

list

Basic List Creation

List with Different Data Types

Accessing List Elements

Modifying List Elements

List Methods

List Concatenation

List Slicing

Nested Lists

List Iteration

List Searching

List Filtering

List Mapping

List Reduction

List Sorting

List of Objects

List Validation

List Utilities

List Performance

Best Practices

​list

​Basic List Creation

​List with Different Data Types

​Accessing List Elements

​Modifying List Elements

​List Methods

​List Concatenation

​List Slicing

​Nested Lists

​List Iteration

​List Searching

​List Filtering

​List Mapping

​List Reduction

​List Sorting

​List of Objects

​List Validation

​List Utilities

​List Performance

​Best Practices

list

Basic List Creation

List with Different Data Types

Accessing List Elements

Modifying List Elements

List Methods

List Concatenation

List Slicing

Nested Lists

List Iteration

List Searching

List Filtering

List Mapping

List Reduction

List Sorting

List of Objects

List Validation

List Utilities

List Performance

Best Practices