aether-azathoth 0.5.3

// stdlib/queue.aether
// Aether 队列（Queue）数据结构库
// 实现先进先出（FIFO）队列，使用数组实现

// ==================== 创建队列 ====================

// 创建一个空队列
Func QUEUE_NEW() {
    Return []
}

// 从数组创建队列
Func QUEUE_FROM_ARRAY(ARR) {
    Return ARR
}

// ==================== 基本操作 ====================

// 入队：在队尾添加元素
// 返回新的队列
Func QUEUE_ENQUEUE(QUEUE, ITEM) {
    Return PUSH(QUEUE, ITEM)
}

// 出队：移除并返回队首元素
// 返回一个字典：{"queue": 新队列, "value": 出队的值}
// 如果队列为空，返回 {"queue": [], "value": Null}
Func QUEUE_DEQUEUE(QUEUE) {
    If (QUEUE_IS_EMPTY(QUEUE)) {
        Return {"queue": [], "value": Null}
    }
    
    Set FIRST QUEUE[0]
    Set NEW_QUEUE []
    Set LEN_ LEN(QUEUE)
    Set I 1
    
    While (I < LEN_) {
        Set NEW_QUEUE PUSH(NEW_QUEUE, QUEUE[I])
        Set I (I + 1)
    }
    
    Return {"queue": NEW_QUEUE, "value": FIRST}
}

// 查看队首元素（不移除）
Func QUEUE_PEEK(QUEUE) {
    If (QUEUE_IS_EMPTY(QUEUE)) {
        Return Null
    }
    Return QUEUE[0]
}

// 查看队尾元素
Func QUEUE_PEEK_BACK(QUEUE) {
    If (QUEUE_IS_EMPTY(QUEUE)) {
        Return Null
    }
    Set LEN_ LEN(QUEUE)
    Return QUEUE[LEN_ - 1]
}

// 获取队列大小
Func QUEUE_SIZE(QUEUE) {
    Return LEN(QUEUE)
}

// 检查队列是否为空
Func QUEUE_IS_EMPTY(QUEUE) {
    Return LEN(QUEUE) == 0
}

// 清空队列
Func QUEUE_CLEAR() {
    Return []
}

// ==================== 高级操作 ====================

// 检查队列是否包含元素
Func QUEUE_CONTAINS(QUEUE, ITEM) {
    Set LEN_ LEN(QUEUE)
    Set I 0
    
    While (I < LEN_) {
        If (QUEUE[I] == ITEM) {
            Return True
        }
        Set I (I + 1)
    }
    
    Return False
}

// 获取元素在队列中的位置（从0开始），如果不存在返回 -1
Func QUEUE_INDEX_OF(QUEUE, ITEM) {
    Set LEN_ LEN(QUEUE)
    Set I 0
    
    While (I < LEN_) {
        If (QUEUE[I] == ITEM) {
            Return I
        }
        Set I (I + 1)
    }
    
    Return -1
}

// 将队列转换为数组
Func QUEUE_TO_ARRAY(QUEUE) {
    Return QUEUE
}

// 反转队列
Func QUEUE_REVERSE(QUEUE) {
    Set RESULT []
    Set LEN_ LEN(QUEUE)
    Set I (LEN_ - 1)
    
    While (I >= 0) {
        Set RESULT PUSH(RESULT, QUEUE[I])
        Set I (I - 1)
    }
    
    Return RESULT
}

// ==================== 批量操作 ====================

// 批量入队：将数组中的所有元素加入队列
Func QUEUE_ENQUEUE_ALL(QUEUE, ARR) {
    Set RESULT QUEUE
    Set LEN_ LEN(ARR)
    Set I 0
    
    While (I < LEN_) {
        Set RESULT PUSH(RESULT, ARR[I])
        Set I (I + 1)
    }
    
    Return RESULT
}

// 批量出队：移除并返回指定数量的元素
// 返回一个字典：{"queue": 新队列, "values": 出队的元素数组}
Func QUEUE_DEQUEUE_N(QUEUE, N) {
    If (N <= 0) {
        Return {"queue": QUEUE, "values": []}
    }
    
    Set MAX_N N
    Set LEN_ LEN(QUEUE)
    If (N > LEN_) {
        Set MAX_N LEN_
    }
    
    Set VALUES []
    Set I 0
    
    While (I < MAX_N) {
        Set VALUES PUSH(VALUES, QUEUE[I])
        Set I (I + 1)
    }
    
    Set NEW_QUEUE []
    Set J MAX_N
    
    While (J < LEN_) {
        Set NEW_QUEUE PUSH(NEW_QUEUE, QUEUE[J])
        Set J (J + 1)
    }
    
    Return {"queue": NEW_QUEUE, "values": VALUES}
}

// ==================== 实用函数 ====================

// 遍历队列，对每个元素应用函数
// FUNC 应该接受两个参数（索引，元素）
Func QUEUE_FOREACH(QUEUE, FUNC) {
    Set LEN_ LEN(QUEUE)
    Set I 0
    
    While (I < LEN_) {
        FUNC(I, QUEUE[I])
        Set I (I + 1)
    }
}

// 过滤队列，返回满足条件的元素组成的新队列
// PREDICATE 应该接受一个参数并返回 True/False
Func QUEUE_FILTER(QUEUE, PREDICATE) {
    Set RESULT []
    Set LEN_ LEN(QUEUE)
    Set I 0
    
    While (I < LEN_) {
        Set ITEM QUEUE[I]
        If (PREDICATE(ITEM)) {
            Set RESULT PUSH(RESULT, ITEM)
        }
        Set I (I + 1)
    }
    
    Return RESULT
}

// 映射队列，对每个元素应用函数，返回新队列
// MAPPER 应该接受一个参数并返回转换后的值
Func QUEUE_MAP(QUEUE, MAPPER) {
    Set RESULT []
    Set LEN_ LEN(QUEUE)
    Set I 0
    
    While (I < LEN_) {
        Set RESULT PUSH(RESULT, MAPPER(QUEUE[I]))
        Set I (I + 1)
    }
    
    Return RESULT
}

// 将队列转换为字符串表示
Func QUEUE_TO_STRING(QUEUE) {
    If (QUEUE_IS_EMPTY(QUEUE)) {
        Return "Queue[]"
    }
    
    Set RESULT "Queue["
    Set LEN_ LEN(QUEUE)
    Set I 0
    
    While (I < LEN_) {
        Set RESULT (RESULT + TO_STRING(QUEUE[I]))
        If (I < (LEN_ - 1)) {
            Set RESULT (RESULT + ", ")
        }
        Set I (I + 1)
    }
    
    Set RESULT (RESULT + "]")
    Return RESULT
}

// 合并两个队列
Func QUEUE_CONCAT(QUEUE1, QUEUE2) {
    Return QUEUE_ENQUEUE_ALL(QUEUE1, QUEUE2)
}