aether/builtins/
array.rs

1// src/builtins/array.rs
2//! Array manipulation built-in functions
3
4use crate::evaluator::RuntimeError;
5use crate::value::Value;
6
7/// 生成数字范围数组
8///
9/// # 功能
10/// 生成一个数字序列数组，支持三种调用方式：
11/// - `Range(end)`: 生成从 0 到 end（不含）的数组
12/// - `Range(start, end)`: 生成从 start 到 end（不含）的数组
13/// - `Range(start, end, step)`: 生成从 start 到 end（不含），步长为 step 的数组
14///
15/// # 参数
16/// - `end`: Number - 结束值（不包含），当只有一个参数时
17/// - `start`: Number - 起始值（包含），当有两个或三个参数时
18/// - `end`: Number - 结束值（不包含）
19/// - `step`: Number - 步长（可选，默认为 1），可以为负数
20///
21/// # 返回值
22/// Array - 包含生成的数字序列的数组
23///
24/// # 错误
25/// - 步长为 0 时抛出错误
26/// - 参数类型不是 Number 时抛出类型错误
27///
28/// # 示例
29/// ```aether
30/// Set nums Range(5)           # [0, 1, 2, 3, 4]
31/// Set nums Range(2, 8)        # [2, 3, 4, 5, 6, 7]
32/// Set nums Range(0, 10, 2)    # [0, 2, 4, 6, 8]
33/// Set nums Range(10, 0, -2)   # [10, 8, 6, 4, 2]
34/// ```
35pub fn range(args: &[Value]) -> Result<Value, RuntimeError> {
36    let (start, end, step) = match args.len() {
37        1 => {
38            // range(end) -> 0..end
39            match &args[0] {
40                Value::Number(n) => (0.0, *n, 1.0),
41                _ => {
42                    return Err(RuntimeError::TypeErrorDetailed {
43                        expected: "Number".to_string(),
44                        got: format!("{:?}", args[0]),
45                    });
46                }
47            }
48        }
49        2 => {
50            // range(start, end) -> start..end
51            match (&args[0], &args[1]) {
52                (Value::Number(s), Value::Number(e)) => (*s, *e, 1.0),
53                _ => {
54                    return Err(RuntimeError::TypeErrorDetailed {
55                        expected: "Number, Number".to_string(),
56                        got: format!("{:?}, {:?}", args[0], args[1]),
57                    });
58                }
59            }
60        }
61        3 => {
62            // range(start, end, step) -> start..end by step
63            match (&args[0], &args[1], &args[2]) {
64                (Value::Number(s), Value::Number(e), Value::Number(st)) => (*s, *e, *st),
65                _ => {
66                    return Err(RuntimeError::TypeErrorDetailed {
67                        expected: "Number, Number, Number".to_string(),
68                        got: format!("{:?}, {:?}, {:?}", args[0], args[1], args[2]),
69                    });
70                }
71            }
72        }
73        n => {
74            return Err(RuntimeError::WrongArity {
75                expected: 1,
76                got: n,
77            });
78        }
79    };
80
81    if step == 0.0 {
82        return Err(RuntimeError::InvalidOperation(
83            "Range step cannot be zero".to_string(),
84        ));
85    }
86
87    let mut result = Vec::new();
88    let mut current = start;
89
90    if step > 0.0 {
91        while current < end {
92            result.push(Value::Number(current));
93            current += step;
94        }
95    } else {
96        while current > end {
97            result.push(Value::Number(current));
98            current += step;
99        }
100    }
101
102    Ok(Value::Array(result))
103}
104
105/// 添加元素到数组末尾
106///
107/// # 功能
108/// 在数组末尾添加一个新元素，返回新的数组。原数组不会被修改。
109///
110/// # 参数
111/// - `array`: Array - 原始数组
112/// - `value`: Any - 要添加的元素（任意类型）
113///
114/// # 返回值
115/// Array - 包含新元素的新数组
116///
117/// # 示例
118/// ```aether
119/// Set arr [1, 2, 3]
120/// Set newArr Push(arr, 4)     # [1, 2, 3, 4]
121/// Println(arr)                # [1, 2, 3] (原数组不变)
122/// ```
123pub fn push(args: &[Value]) -> Result<Value, RuntimeError> {
124    if args.len() != 2 {
125        return Err(RuntimeError::WrongArity {
126            expected: 2,
127            got: args.len(),
128        });
129    }
130
131    match &args[0] {
132        Value::Array(arr) => {
133            let mut new_arr = arr.clone();
134            new_arr.push(args[1].clone());
135            Ok(Value::Array(new_arr))
136        }
137        _ => Err(RuntimeError::TypeErrorDetailed {
138            expected: "Array".to_string(),
139            got: format!("{:?}", args[0]),
140        }),
141    }
142}
143
144/// 移除并返回数组的最后一个元素
145///
146/// # 功能
147/// 移除数组的最后一个元素，返回一个包含两个元素的数组：
148/// - 第一个元素：移除最后元素后的新数组
149/// - 第二个元素：被移除的元素
150///
151/// # 参数
152/// - `array`: Array - 要操作的数组
153///
154/// # 返回值
155/// Array - `[新数组, 被移除的元素]`
156///
157/// # 错误
158/// - 空数组时抛出错误
159///
160/// # 示例
161/// ```aether
162/// Set arr [1, 2, 3, 4]
163/// Set result Pop(arr)          # [[1, 2, 3], 4]
164/// Set newArr result[0]         # [1, 2, 3]
165/// Set popped result[1]         # 4
166/// ```
167pub fn pop(args: &[Value]) -> Result<Value, RuntimeError> {
168    if args.len() != 1 {
169        return Err(RuntimeError::WrongArity {
170            expected: 1,
171            got: args.len(),
172        });
173    }
174
175    match &args[0] {
176        Value::Array(arr) => {
177            if arr.is_empty() {
178                return Err(RuntimeError::InvalidOperation(
179                    "Cannot pop from empty array".to_string(),
180                ));
181            }
182            let mut new_arr = arr.clone();
183            let popped = new_arr.pop().unwrap();
184            Ok(Value::Array(vec![Value::Array(new_arr), popped]))
185        }
186        _ => Err(RuntimeError::TypeErrorDetailed {
187            expected: "Array".to_string(),
188            got: format!("{:?}", args[0]),
189        }),
190    }
191}
192
193/// 将数组元素连接成字符串
194///
195/// # 功能
196/// 将数组中的所有元素转换为字符串，并用指定的分隔符连接。
197///
198/// # 参数
199/// - `array`: Array - 要连接的数组
200/// - `separator`: String - 分隔符
201///
202/// # 返回值
203/// String - 连接后的字符串
204///
205/// # 示例
206/// ```aether
207/// Set arr [1, 2, 3, 4]
208/// Set str Join(arr, ", ")      # "1, 2, 3, 4"
209/// Set str Join(arr, "-")       # "1-2-3-4"
210/// Set words ["Hello", "World"]
211/// Set str Join(words, " ")     # "Hello World"
212/// ```
213pub fn join(args: &[Value]) -> Result<Value, RuntimeError> {
214    if args.len() != 2 {
215        return Err(RuntimeError::WrongArity {
216            expected: 2,
217            got: args.len(),
218        });
219    }
220
221    match (&args[0], &args[1]) {
222        (Value::Array(arr), Value::String(sep)) => {
223            let strings: Vec<String> = arr.iter().map(|v| v.to_string()).collect();
224            Ok(Value::String(strings.join(sep)))
225        }
226        _ => Err(RuntimeError::TypeErrorDetailed {
227            expected: "Array, String".to_string(),
228            got: format!("{:?}, {:?}", args[0], args[1]),
229        }),
230    }
231}
232
233/// 反转数组
234///
235/// # 功能
236/// 返回一个新数组，元素顺序与原数组相反。原数组不会被修改。
237///
238/// # 参数
239/// - `array`: Array - 要反转的数组
240///
241/// # 返回值
242/// Array - 反转后的新数组
243///
244/// # 示例
245/// ```aether
246/// Set arr [1, 2, 3, 4, 5]
247/// Set reversed Reverse(arr)    # [5, 4, 3, 2, 1]
248/// Println(arr)                 # [1, 2, 3, 4, 5] (原数组不变)
249/// ```
250pub fn reverse(args: &[Value]) -> Result<Value, RuntimeError> {
251    if args.len() != 1 {
252        return Err(RuntimeError::WrongArity {
253            expected: 1,
254            got: args.len(),
255        });
256    }
257
258    match &args[0] {
259        Value::Array(arr) => {
260            let mut new_arr = arr.clone();
261            new_arr.reverse();
262            Ok(Value::Array(new_arr))
263        }
264        _ => Err(RuntimeError::TypeErrorDetailed {
265            expected: "Array".to_string(),
266            got: format!("{:?}", args[0]),
267        }),
268    }
269}
270
271/// 对数字数组进行排序
272///
273/// # 功能
274/// 对数字数组进行升序排序，返回新的已排序数组。原数组不会被修改。
275///
276/// # 参数
277/// - `array`: Array - 要排序的数字数组
278///
279/// # 返回值
280/// Array - 升序排列的新数组
281///
282/// # 错误
283/// - 数组包含非数字元素时抛出类型错误
284///
285/// # 示例
286/// ```aether
287/// Set nums [3, 1, 4, 1, 5, 9, 2, 6]
288/// Set sorted Sort(nums)        # [1, 1, 2, 3, 4, 5, 6, 9]
289/// Println(nums)                # [3, 1, 4, 1, 5, 9, 2, 6] (原数组不变)
290/// ```
291pub fn sort(args: &[Value]) -> Result<Value, RuntimeError> {
292    if args.len() != 1 {
293        return Err(RuntimeError::WrongArity {
294            expected: 1,
295            got: args.len(),
296        });
297    }
298
299    match &args[0] {
300        Value::Array(arr) => {
301            let mut numbers: Vec<f64> = Vec::new();
302            for val in arr {
303                match val {
304                    Value::Number(n) => numbers.push(*n),
305                    _ => {
306                        return Err(RuntimeError::TypeErrorDetailed {
307                            expected: "Array of Numbers".to_string(),
308                            got: format!("Array containing {:?}", val),
309                        });
310                    }
311                }
312            }
313            numbers.sort_by(|a, b| a.partial_cmp(b).unwrap());
314            Ok(Value::Array(
315                numbers.into_iter().map(Value::Number).collect(),
316            ))
317        }
318        _ => Err(RuntimeError::TypeErrorDetailed {
319            expected: "Array".to_string(),
320            got: format!("{:?}", args[0]),
321        }),
322    }
323}
324
325/// 计算数字数组的总和
326///
327/// # 功能
328/// 计算数字数组中所有元素的和。
329///
330/// # 参数
331/// - `array`: Array - 数字数组
332///
333/// # 返回值
334/// Number - 数组元素的总和
335///
336/// # 错误
337/// - 数组包含非数字元素时抛出类型错误
338///
339/// # 示例
340/// ```aether
341/// Set nums [1, 2, 3, 4, 5]
342/// Set total Sum(nums)          # 15
343/// Set prices [10.5, 20.0, 5.5]
344/// Set total Sum(prices)        # 36.0
345/// ```
346pub fn sum(args: &[Value]) -> Result<Value, RuntimeError> {
347    if args.len() != 1 {
348        return Err(RuntimeError::WrongArity {
349            expected: 1,
350            got: args.len(),
351        });
352    }
353
354    match &args[0] {
355        Value::Array(arr) => {
356            let mut total = 0.0;
357            for val in arr {
358                match val {
359                    Value::Number(n) => total += n,
360                    _ => {
361                        return Err(RuntimeError::TypeErrorDetailed {
362                            expected: "Array of Numbers".to_string(),
363                            got: format!("Array containing {:?}", val),
364                        });
365                    }
366                }
367            }
368            Ok(Value::Number(total))
369        }
370        _ => Err(RuntimeError::TypeErrorDetailed {
371            expected: "Array".to_string(),
372            got: format!("{:?}", args[0]),
373        }),
374    }
375}
376
377/// 获取数组中的最大值
378///
379/// # 功能
380/// 返回数字数组中的最大值。
381///
382/// # 参数
383/// - `array`: Array - 数字数组
384///
385/// # 返回值
386/// Number - 数组中的最大值
387///
388/// # 错误
389/// - 空数组时抛出错误
390/// - 数组包含非数字元素时抛出类型错误
391///
392/// # 示例
393/// ```aether
394/// Set nums [3, 7, 2, 9, 1]
395/// Set maximum Max(nums)        # 9
396/// Set scores [85.5, 92.0, 78.5, 95.5]
397/// Set highest Max(scores)      # 95.5
398/// ```
399pub fn max(args: &[Value]) -> Result<Value, RuntimeError> {
400    if args.len() != 1 {
401        return Err(RuntimeError::WrongArity {
402            expected: 1,
403            got: args.len(),
404        });
405    }
406
407    match &args[0] {
408        Value::Array(arr) => {
409            if arr.is_empty() {
410                return Err(RuntimeError::InvalidOperation(
411                    "Cannot get max of empty array".to_string(),
412                ));
413            }
414
415            let mut max_val = f64::NEG_INFINITY;
416            for val in arr {
417                match val {
418                    Value::Number(n) => {
419                        if *n > max_val {
420                            max_val = *n;
421                        }
422                    }
423                    _ => {
424                        return Err(RuntimeError::TypeErrorDetailed {
425                            expected: "Array of Numbers".to_string(),
426                            got: format!("Array containing {:?}", val),
427                        });
428                    }
429                }
430            }
431            Ok(Value::Number(max_val))
432        }
433        _ => Err(RuntimeError::TypeErrorDetailed {
434            expected: "Array".to_string(),
435            got: format!("{:?}", args[0]),
436        }),
437    }
438}
439
440/// 获取数组中的最小值
441///
442/// # 功能
443/// 返回数字数组中的最小值。
444///
445/// # 参数
446/// - `array`: Array - 数字数组
447///
448/// # 返回值
449/// Number - 数组中的最小值
450///
451/// # 错误
452/// - 空数组时抛出错误
453/// - 数组包含非数字元素时抛出类型错误
454///
455/// # 示例
456/// ```aether
457/// Set nums [3, 7, 2, 9, 1]
458/// Set minimum Min(nums)        # 1
459/// Set temps [18.5, 22.0, 15.5, 20.5]
460/// Set lowest Min(temps)        # 15.5
461/// ```
462pub fn min(args: &[Value]) -> Result<Value, RuntimeError> {
463    if args.len() != 1 {
464        return Err(RuntimeError::WrongArity {
465            expected: 1,
466            got: args.len(),
467        });
468    }
469
470    match &args[0] {
471        Value::Array(arr) => {
472            if arr.is_empty() {
473                return Err(RuntimeError::InvalidOperation(
474                    "Cannot get min of empty array".to_string(),
475                ));
476            }
477
478            let mut min_val = f64::INFINITY;
479            for val in arr {
480                match val {
481                    Value::Number(n) => {
482                        if *n < min_val {
483                            min_val = *n;
484                        }
485                    }
486                    _ => {
487                        return Err(RuntimeError::TypeErrorDetailed {
488                            expected: "Array of Numbers".to_string(),
489                            got: format!("Array containing {:?}", val),
490                        });
491                    }
492                }
493            }
494            Ok(Value::Number(min_val))
495        }
496        _ => Err(RuntimeError::TypeErrorDetailed {
497            expected: "Array".to_string(),
498            got: format!("{:?}", args[0]),
499        }),
500    }
501}
502
503/// Map 函数
504///
505/// # 功能
506/// 将函数应用到数组的每个元素，返回新数组。
507///
508/// # 参数
509/// - `array`: Array - 输入数组
510/// - `func`: Function - 转换函数
511///
512/// # 返回值
513/// Array - 转换后的新数组
514///
515/// # 注意
516/// 此函数期望在求值器上下文中调用，但由于实现限制，
517/// 建议在 Aether 标准库中使用循环来实现 map 功能。
518///
519/// # 示例
520/// ```aether
521/// Set doubled Map([1, 2, 3], Fun(x) { Return x * 2 })  # [2, 4, 6]
522/// ```
523pub fn map(_args: &[Value]) -> Result<Value, RuntimeError> {
524    // 注意：真正的 map 实现应该在求值器层面，因为需要调用用户定义的函数
525    // 这里提供一个占位符实现，建议在 stdlib 中实现
526    Err(RuntimeError::InvalidOperation(
527        "MAP requires function evaluation context. Use stdlib implementation or manual loops instead.".to_string(),
528    ))
529}
530
531/// Filter 函数
532///
533/// # 功能
534/// 筛选数组中满足条件的元素，返回新数组。
535///
536/// # 参数
537/// - `array`: Array - 输入数组
538/// - `predicate`: Function - 判断函数，返回布尔值
539///
540/// # 返回值
541/// Array - 筛选后的新数组
542///
543/// # 注意
544/// 此函数期望在求值器上下文中调用，但由于实现限制，
545/// 建议在 Aether 标准库中使用循环来实现 filter 功能。
546///
547/// # 示例
548/// ```aether
549/// Set evens Filter([1, 2, 3, 4], Fun(x) { Return x % 2 == 0 })  # [2, 4]
550/// ```
551pub fn filter(_args: &[Value]) -> Result<Value, RuntimeError> {
552    // 注意：真正的 filter 实现应该在求值器层面，因为需要调用用户定义的函数
553    // 这里提供一个占位符实现，建议在 stdlib 中实现
554    Err(RuntimeError::InvalidOperation(
555        "FILTER requires function evaluation context. Use stdlib implementation or manual loops instead.".to_string(),
556    ))
557}
558
559/// Reduce 函数（占位符）
560///
561/// # 功能
562/// 此函数为占位符，实际的 Reduce 功能由求值器（evaluator）实现。
563/// Reduce 用于将数组归约为单个值。
564///
565/// # 注意
566/// 不应直接调用此函数，应使用语言层面的 Reduce 语法。
567///
568/// # 示例
569/// ```aether
570/// # 实际使用（由求值器处理，参数顺序：array, func, initial）:
571/// # 回调可选第三参数索引 (acc, item, index)
572/// Set sum REDUCE([1, 2, 3, 4], Fun(acc, x, i) { Return acc + x + i }, 0)  # 16
573/// ```
574pub fn reduce(_args: &[Value]) -> Result<Value, RuntimeError> {
575    Err(RuntimeError::InvalidOperation(
576        "Reduce requires function evaluation context - use evaluator's reduce implementation"
577            .to_string(),
578    ))
579}
aether/builtins/array.rs

aether/builtins/
array.rs
