tuioxide 0.3.1

A Rust implementation of the TUIO 1.1 and TUIO 2.0 protocols, providing both client and server components for sending and receiving multitouch and tangible object data over OSC.
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
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132

use rosc::{OscMessage, OscType};

use crate::core::{TuioError, TuioTime};

/// A cursor-style iterator over the arguments of an [`OscMessage`].
///
/// `ArgCursor` provides sequential, typed access to the OSC argument list of a
/// message. It keeps track of the current position and advances automatically
/// after each successful read, making it easy to decode structured TUIO messages
/// without manual index management.
///
/// # Example
///
/// ```ignore
/// let mut cursor = ArgCursor::new(&message, 1); // skip the message-type string at index 0
/// let session_id = cursor.next_int()?;
/// let x = cursor.next_float()?;
/// let y = cursor.next_float()?;
/// ```
#[derive(Debug, Clone, Copy)]
pub(crate) struct ArgCursor<'a> {
    message: &'a OscMessage,
    index: usize,
}

impl<'a> ArgCursor<'a> {
    /// Creates a new `ArgCursor` for the given `message`, starting at `start_index`.
    ///
    /// `start_index` is useful for skipping leading arguments such as the
    /// message-type string (e.g. `"set"`, `"alive"`) that TUIO prepends to most
    /// messages.
    pub(crate) fn new(message: &'a OscMessage, start_index: usize) -> Self {
        Self {
            message,
            index: start_index,
        }
    }

    /// Reads the next argument as an `i32` integer and advances the cursor.
    ///
    /// # Errors
    ///
    /// Returns [`TuioError::WrongArgumentType`] if the argument at the current
    /// position is not an [`OscType::Int`], or [`TuioError::MissingArguments`]
    /// if there are no more arguments.
    pub(crate) fn next_int(&mut self) -> Result<i32, TuioError> {
        match self.message.args.get(self.index) {
            Some(OscType::Int(value)) => {
                self.index += 1;
                Ok(*value)
            }
            Some(_) => Err(TuioError::WrongArgumentType(
                self.message.clone(),
                self.index,
            )),
            None => Err(TuioError::MissingArguments(self.message.clone())),
        }
    }

    /// Reads the next argument as an `f32` float and advances the cursor.
    ///
    /// # Errors
    ///
    /// Returns [`TuioError::WrongArgumentType`] if the argument at the current
    /// position is not an [`OscType::Float`], or [`TuioError::MissingArguments`]
    /// if there are no more arguments.
    pub(crate) fn next_float(&mut self) -> Result<f32, TuioError> {
        match self.message.args.get(self.index) {
            Some(OscType::Float(value)) => {
                self.index += 1;
                Ok(*value)
            }
            Some(_) => Err(TuioError::WrongArgumentType(
                self.message.clone(),
                self.index,
            )),
            None => Err(TuioError::MissingArguments(self.message.clone())),
        }
    }

    /// Reads the next argument as an owned [`String`] and advances the cursor.
    ///
    /// # Errors
    ///
    /// Returns [`TuioError::WrongArgumentType`] if the argument at the current
    /// position is not an [`OscType::String`], or [`TuioError::MissingArguments`]
    /// if there are no more arguments.
    pub(crate) fn next_string(&mut self) -> Result<String, TuioError> {
        match self.message.args.get(self.index) {
            Some(OscType::String(value)) => {
                self.index += 1;
                Ok(value.to_owned())
            }
            Some(_) => Err(TuioError::WrongArgumentType(
                self.message.clone(),
                self.index,
            )),
            None => Err(TuioError::MissingArguments(self.message.clone())),
        }
    }

    /// Reads the next argument as a [`TuioTime`] (converted from an OSC time tag)
    /// and advances the cursor.
    ///
    /// # Errors
    ///
    /// Returns [`TuioError::WrongArgumentType`] if the argument at the current
    /// position is not an [`OscType::Time`], or [`TuioError::MissingArguments`]
    /// if there are no more arguments.
    pub(crate) fn next_time(&mut self) -> Result<TuioTime, TuioError> {
        match self.message.args.get(self.index) {
            Some(OscType::Time(value)) => {
                self.index += 1;
                Ok(TuioTime::from(*value))
            }
            Some(_) => Err(TuioError::WrongArgumentType(
                self.message.clone(),
                self.index,
            )),
            None => Err(TuioError::MissingArguments(self.message.clone())),
        }
    }

    /// Returns the number of arguments remaining from the current cursor position
    /// to the end of the message's argument list.
    ///
    /// This is useful for decoding optional trailing arguments that may or may not
    /// be present in a message.
    pub(crate) fn remaining(&self) -> usize {
        self.message.args.len() - self.index
    }
}