lib-tan-core 0.16.0

The core library
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110

// #todo Abbreviate to `buf`.
// #todo consider other names: `Buf`, `Byte-Buffer`, etc.

use std::sync::{Arc, RwLock};

use tan::{context::Context, error::Error, expr::Expr, util::module_util::require_module};

// #insight
// size -> in bytes (maybe size-in-bytes ?)
// length/count -> in items/elements (maybe size ?)

// #todo add support for u32, u64 and maybe even other types.
// #todo add support for little-endian/big-endian.

// #todo use array instead of vec? can we have dynamic array, probably a slice.

// #todo make buffer Iterable/Iterate

pub fn buffer_new(args: &[Expr]) -> Result<Expr, Error> {
    // #todo also support a default-element/fill option.

    let [length] = args else {
        return Err(Error::invalid_arguments("requires `length` argument", None));
    };

    // #todo create a helper.
    let Some(length) = length.as_int() else {
        return Err(Error::invalid_arguments(
            &format!("length=`{length}` is not Int"),
            length.range(),
        ));
    };

    let length = length as usize;
    // #todo allow for custom initial value.
    let buf: Vec<u8> = vec![0; length];

    Ok(Expr::Buffer(length, Arc::new(RwLock::new(buf))))
}

// (put buf index value)
pub fn buffer_put(args: &[Expr]) -> Result<Expr, Error> {
    // #todo enforce bounds!!

    let [buffer, index, value] = args else {
        return Err(Error::invalid_arguments(
            "requires `index` and `value` arguments",
            None,
        ));
    };

    let Some((length, mut buffer)) = buffer.as_buffer_mut() else {
        return Err(Error::invalid_arguments(
            &format!("buffer=`{buffer}` is not a Buffer"),
            buffer.range(),
        ));
    };

    let Some(i) = index.as_int() else {
        return Err(Error::invalid_arguments(
            &format!("index=`{index}` is not Int"),
            index.range(),
        ));
    };

    if i < 0 {
        // #todo use specialized error variant? e.g. invalid_argument_out_of_bounds?
        return Err(Error::invalid_arguments(
            &format!("buffer index=`{i}` cannot be negative"),
            index.range(),
        ));
    }

    let i = i as usize;

    if i >= length {
        return Err(Error::invalid_arguments(
            &format!("buffer index=`{i}` must be less than the buffer length=`{length}`"),
            index.range(),
        ));
    }

    let Some(value) = value.as_u8() else {
        return Err(Error::invalid_arguments(
            &format!("value=`{value}` is not U8"),
            value.range(),
        ));
    };

    buffer[i] = value;

    // #todo what should we return?
    Ok(Expr::None)
}

pub fn setup_lib_buffer(context: &mut Context) {
    // #todo put in 'buffer' path, and import selected functionality to prelude.
    let module = require_module("prelude", context);

    // #todo consider `Buf`.
    module.insert_invocable("Buffer", Expr::foreign_func(&buffer_new));

    // #todo also provide a put$$Int

    module.insert_invocable("put$$Buffer$$Int$$U8", Expr::foreign_func(&buffer_put));
}

// #todo Push with Int, reuse push with U8
// #todo Support 5u8.
// #todo Implement Eq.