dbc_rs/dbc/builder/impls.rs
1use super::DbcBuilder;
2use crate::{
3 Dbc, ExtendedMultiplexingBuilder, MessageBuilder, NodesBuilder, Receivers, ReceiversBuilder,
4 SignalBuilder, ValueDescriptionsBuilder, VersionBuilder,
5};
6use std::collections::BTreeMap;
7
8impl DbcBuilder {
9 /// Creates a new empty `DbcBuilder`.
10 ///
11 /// # Examples
12 ///
13 /// ```rust,no_run
14 /// use dbc_rs::{DbcBuilder, VersionBuilder, NodesBuilder, MessageBuilder};
15 ///
16 /// let dbc = DbcBuilder::new()
17 /// .version(VersionBuilder::new().version("1.0"))
18 /// .nodes(NodesBuilder::new().add_node("ECM"))
19 /// .add_message(MessageBuilder::new()
20 /// .id(512)
21 /// .name("Brake")
22 /// .dlc(4)
23 /// .sender("ECM"))
24 /// .build()?;
25 /// # Ok::<(), dbc_rs::Error>(())
26 /// ```
27 pub fn new() -> Self {
28 Self::default()
29 }
30
31 /// Sets the version for the DBC file.
32 ///
33 /// # Examples
34 ///
35 /// ```rust,no_run
36 /// use dbc_rs::{DbcBuilder, VersionBuilder};
37 ///
38 /// let vb = VersionBuilder::new().version("1.0");
39 /// let builder = DbcBuilder::new()
40 /// .version(vb);
41 /// # Ok::<(), dbc_rs::Error>(())
42 /// ```
43 #[must_use = "builder method returns modified builder"]
44 pub fn version(mut self, version: VersionBuilder) -> Self {
45 self.version = version;
46 self
47 }
48
49 /// Sets the nodes (ECUs) for the DBC file.
50 ///
51 /// # Examples
52 ///
53 /// ```rust,no_run
54 /// use dbc_rs::{DbcBuilder, NodesBuilder};
55 ///
56 /// let builder = DbcBuilder::new()
57 /// .nodes(NodesBuilder::new().add_node("ECM"));
58 /// # Ok::<(), dbc_rs::Error>(())
59 /// ```
60 #[must_use = "builder method returns modified builder"]
61 pub fn nodes(mut self, nodes: NodesBuilder) -> Self {
62 self.nodes = nodes;
63 self
64 }
65
66 /// Adds a message to the DBC file.
67 ///
68 /// # Examples
69 ///
70 /// ```rust,no_run
71 /// use dbc_rs::{DbcBuilder, MessageBuilder};
72 ///
73 /// let message = MessageBuilder::new()
74 /// .id(256)
75 /// .name("EngineData")
76 /// .dlc(8)
77 /// .sender("ECM");
78 ///
79 /// let builder = DbcBuilder::new()
80 /// .add_message(message);
81 /// # Ok::<(), dbc_rs::Error>(())
82 /// ```
83 #[must_use = "builder method returns modified builder"]
84 pub fn add_message(mut self, message: MessageBuilder) -> Self {
85 self.messages.push(message);
86 self
87 }
88
89 /// Adds multiple messages to the DBC file.
90 ///
91 /// # Examples
92 ///
93 /// ```rust,no_run
94 /// use dbc_rs::{DbcBuilder, MessageBuilder};
95 ///
96 /// let msg1 = MessageBuilder::new().id(256).name("Msg1").dlc(8).sender("ECM");
97 /// let msg2 = MessageBuilder::new().id(512).name("Msg2").dlc(4).sender("TCM");
98 ///
99 /// let builder = DbcBuilder::new()
100 /// .add_messages(vec![msg1, msg2]);
101 /// # Ok::<(), dbc_rs::Error>(())
102 /// ```
103 #[must_use = "builder method returns modified builder"]
104 pub fn add_messages(mut self, messages: impl IntoIterator<Item = MessageBuilder>) -> Self {
105 self.messages.extend(messages);
106 self
107 }
108
109 /// Clears all messages from the builder.
110 ///
111 /// # Examples
112 ///
113 /// ```rust,no_run
114 /// use dbc_rs::DbcBuilder;
115 ///
116 /// let builder = DbcBuilder::new()
117 /// .clear_messages();
118 /// ```
119 #[must_use = "builder method returns modified builder"]
120 pub fn clear_messages(mut self) -> Self {
121 self.messages.clear();
122 self
123 }
124
125 /// Adds value descriptions for a signal in a message.
126 ///
127 /// Value descriptions (VAL_) map numeric signal values to human-readable text.
128 ///
129 /// # Arguments
130 ///
131 /// * `message_id` - The CAN message ID containing the signal
132 /// * `signal_name` - The name of the signal
133 /// * `value_descriptions` - The value descriptions builder
134 ///
135 /// # Examples
136 ///
137 /// ```rust,no_run
138 /// use dbc_rs::{DbcBuilder, ValueDescriptionsBuilder};
139 ///
140 /// let value_desc = ValueDescriptionsBuilder::new()
141 /// .add_entry(0, "Park")
142 /// .add_entry(1, "Drive");
143 ///
144 /// let builder = DbcBuilder::new()
145 /// .add_value_description(256, "Gear", value_desc);
146 /// # Ok::<(), dbc_rs::Error>(())
147 /// ```
148 #[must_use = "builder method returns modified builder"]
149 pub fn add_value_description(
150 mut self,
151 message_id: u32,
152 signal_name: impl AsRef<str>,
153 value_descriptions: ValueDescriptionsBuilder,
154 ) -> Self {
155 self.value_descriptions.insert(
156 (Some(message_id), signal_name.as_ref().to_string()),
157 value_descriptions,
158 );
159 self
160 }
161
162 /// Adds global value descriptions for a signal (applies to all messages with this signal).
163 ///
164 /// Global value descriptions (VAL_ with message_id -1) apply to signals with the given
165 /// name in any message.
166 ///
167 /// # Arguments
168 ///
169 /// * `signal_name` - The name of the signal
170 /// * `value_descriptions` - The value descriptions builder
171 ///
172 /// # Examples
173 ///
174 /// ```rust,no_run
175 /// use dbc_rs::{DbcBuilder, ValueDescriptionsBuilder};
176 ///
177 /// let value_desc = ValueDescriptionsBuilder::new()
178 /// .add_entry(0, "Off")
179 /// .add_entry(1, "On");
180 ///
181 /// let builder = DbcBuilder::new()
182 /// .add_global_value_description("Status", value_desc);
183 /// # Ok::<(), dbc_rs::Error>(())
184 /// ```
185 #[must_use = "builder method returns modified builder"]
186 pub fn add_global_value_description(
187 mut self,
188 signal_name: impl AsRef<str>,
189 value_descriptions: ValueDescriptionsBuilder,
190 ) -> Self {
191 self.value_descriptions
192 .insert((None, signal_name.as_ref().to_string()), value_descriptions);
193 self
194 }
195
196 /// Clears all value descriptions from the builder.
197 ///
198 /// # Examples
199 ///
200 /// ```rust,no_run
201 /// use dbc_rs::DbcBuilder;
202 ///
203 /// let builder = DbcBuilder::new()
204 /// .clear_value_descriptions();
205 /// ```
206 #[must_use = "builder method returns modified builder"]
207 pub fn clear_value_descriptions(mut self) -> Self {
208 self.value_descriptions.clear();
209 self
210 }
211
212 /// Adds an extended multiplexing entry to the DBC file.
213 ///
214 /// Extended multiplexing (SG_MUL_VAL_) entries define which multiplexer switch
215 /// values activate specific multiplexed signals, allowing for range-based activation.
216 ///
217 /// # Examples
218 ///
219 /// ```rust,no_run
220 /// use dbc_rs::{DbcBuilder, ExtendedMultiplexingBuilder};
221 ///
222 /// let ext_mux = ExtendedMultiplexingBuilder::new()
223 /// .message_id(500)
224 /// .signal_name("Signal_A")
225 /// .multiplexer_switch("Mux1")
226 /// .add_value_range(0, 5);
227 ///
228 /// let builder = DbcBuilder::new()
229 /// .add_extended_multiplexing(ext_mux);
230 /// # Ok::<(), dbc_rs::Error>(())
231 /// ```
232 #[must_use = "builder method returns modified builder"]
233 pub fn add_extended_multiplexing(mut self, ext_mux: ExtendedMultiplexingBuilder) -> Self {
234 self.extended_multiplexing.push(ext_mux);
235 self
236 }
237
238 /// Adds multiple extended multiplexing entries to the DBC file.
239 ///
240 /// # Examples
241 ///
242 /// ```rust,no_run
243 /// use dbc_rs::{DbcBuilder, ExtendedMultiplexingBuilder};
244 ///
245 /// let ext_mux1 = ExtendedMultiplexingBuilder::new()
246 /// .message_id(500)
247 /// .signal_name("Signal_A")
248 /// .multiplexer_switch("Mux1")
249 /// .add_value_range(0, 5);
250 /// let ext_mux2 = ExtendedMultiplexingBuilder::new()
251 /// .message_id(500)
252 /// .signal_name("Signal_B")
253 /// .multiplexer_switch("Mux1")
254 /// .add_value_range(10, 15);
255 ///
256 /// let builder = DbcBuilder::new()
257 /// .add_extended_multiplexings(vec![ext_mux1, ext_mux2]);
258 /// # Ok::<(), dbc_rs::Error>(())
259 /// ```
260 #[must_use = "builder method returns modified builder"]
261 pub fn add_extended_multiplexings(
262 mut self,
263 ext_muxes: impl IntoIterator<Item = ExtendedMultiplexingBuilder>,
264 ) -> Self {
265 self.extended_multiplexing.extend(ext_muxes);
266 self
267 }
268
269 /// Clears all extended multiplexing entries from the builder.
270 ///
271 /// # Examples
272 ///
273 /// ```rust,no_run
274 /// use dbc_rs::DbcBuilder;
275 ///
276 /// let builder = DbcBuilder::new()
277 /// .clear_extended_multiplexing();
278 /// ```
279 #[must_use = "builder method returns modified builder"]
280 pub fn clear_extended_multiplexing(mut self) -> Self {
281 self.extended_multiplexing.clear();
282 self
283 }
284
285 /// Creates a `DbcBuilder` from an existing `Dbc`.
286 ///
287 /// This allows you to modify an existing DBC file by creating a builder
288 /// initialized with all data from the provided DBC.
289 ///
290 /// # Arguments
291 ///
292 /// * `dbc` - The existing `Dbc` to create a builder from
293 ///
294 /// # Examples
295 ///
296 /// ```rust,no_run
297 /// use dbc_rs::{Dbc, DbcBuilder, MessageBuilder};
298 ///
299 /// let original = Dbc::parse(r#"VERSION "1.0"\nBU_: ECM\n"#)?;
300 /// let modified = DbcBuilder::from_dbc(&original)
301 /// .add_message(MessageBuilder::new().id(256).name("Msg").dlc(8).sender("ECM"))
302 /// .build()?;
303 /// # Ok::<(), dbc_rs::Error>(())
304 /// ```
305 pub fn from_dbc(dbc: &Dbc) -> Self {
306 // Convert version to builder (store builder, not final type)
307 let version = if let Some(v) = dbc.version() {
308 VersionBuilder::new().version(v.as_str())
309 } else {
310 VersionBuilder::new()
311 };
312
313 // Convert nodes to builder (store builder, not final type)
314 // Note: We unwrap here because we're converting from a valid Dbc, so names should already fit MAX_NAME_SIZE
315 let nodes = {
316 let mut builder = NodesBuilder::new();
317 for node in dbc.nodes().iter() {
318 // Convert compat::String to std::string::String for the builder
319 let node_str = node.to_string();
320 // Should never fail for valid Dbc - unwrap is safe
321 builder = builder.add_node(node_str);
322 }
323 builder
324 };
325
326 // Convert messages to builders (store builders, not final types)
327 let messages: Vec<MessageBuilder> = dbc
328 .messages()
329 .iter()
330 .map(|msg| {
331 let mut msg_builder = MessageBuilder::new()
332 .id(msg.id())
333 .name(msg.name())
334 .dlc(msg.dlc())
335 .sender(msg.sender());
336
337 // Convert signals using SignalBuilder
338 for sig in msg.signals().iter() {
339 let mut sig_builder = SignalBuilder::new()
340 .name(sig.name())
341 .start_bit(sig.start_bit())
342 .length(sig.length())
343 .byte_order(sig.byte_order())
344 .unsigned(sig.is_unsigned())
345 .factor(sig.factor())
346 .offset(sig.offset())
347 .min(sig.min())
348 .max(sig.max());
349
350 if let Some(unit) = sig.unit() {
351 sig_builder = sig_builder.unit(unit);
352 }
353
354 // Convert receivers using ReceiversBuilder
355 let receivers_builder = match sig.receivers() {
356 Receivers::None => ReceiversBuilder::new().none(),
357 Receivers::Nodes(nodes) => {
358 let mut rb = ReceiversBuilder::new();
359 // nodes is Vec<String<{MAX_NAME_SIZE}>>, iterate directly
360 for receiver in nodes.iter() {
361 // receiver is &String<{MAX_NAME_SIZE}>, clone it
362 let receiver_str = receiver.clone();
363 // Should never fail for valid Dbc - unwrap is safe
364 rb = rb.add_node(receiver_str);
365 }
366 rb
367 }
368 };
369 sig_builder = sig_builder.receivers(receivers_builder);
370
371 msg_builder = msg_builder.add_signal(sig_builder);
372 }
373
374 msg_builder
375 })
376 .collect();
377
378 // Convert value descriptions from Dbc to builder format (store builders, not final types)
379 let mut value_descriptions: BTreeMap<(Option<u32>, String), ValueDescriptionsBuilder> =
380 BTreeMap::new();
381 for ((message_id, signal_name), vd) in dbc.value_descriptions().iter() {
382 // Store as String and ValueDescriptionsBuilder (no leak)
383 let mut builder = ValueDescriptionsBuilder::new();
384 for (value, desc) in vd.iter() {
385 builder = builder.add_entry(value, desc);
386 }
387 value_descriptions.insert((message_id, signal_name.to_string()), builder);
388 }
389
390 // Convert extended multiplexing entries to builders
391 let extended_multiplexing: Vec<ExtendedMultiplexingBuilder> = dbc
392 .extended_multiplexing()
393 .iter()
394 .map(|ext_mux| {
395 let mut builder = ExtendedMultiplexingBuilder::new()
396 .message_id(ext_mux.message_id())
397 .signal_name(ext_mux.signal_name())
398 .multiplexer_switch(ext_mux.multiplexer_switch());
399
400 // Add all value ranges
401 for (min, max) in ext_mux.value_ranges() {
402 builder = builder.add_value_range(*min, *max);
403 }
404
405 builder
406 })
407 .collect();
408
409 Self {
410 version,
411 nodes,
412 messages,
413 value_descriptions,
414 extended_multiplexing,
415 }
416 }
417}
418
419#[cfg(test)]
420mod tests {
421 #![allow(clippy::float_cmp)]
422 use super::DbcBuilder;
423 use crate::{
424 ByteOrder, Dbc, ExtendedMultiplexingBuilder, MessageBuilder, NodesBuilder,
425 ReceiversBuilder, SignalBuilder, VersionBuilder,
426 };
427
428 #[test]
429 fn test_dbc_builder_add_messages() {
430 let version = VersionBuilder::new().version("1.0");
431 let nodes = NodesBuilder::new().add_nodes(["ECM"]);
432 let signal1 = SignalBuilder::new()
433 .name("RPM")
434 .start_bit(0)
435 .length(16)
436 .byte_order(ByteOrder::BigEndian)
437 .unsigned(true)
438 .factor(1.0)
439 .offset(0.0)
440 .min(0.0)
441 .max(100.0)
442 .receivers(ReceiversBuilder::new().none());
443 let signal2 = SignalBuilder::new()
444 .name("RPM")
445 .start_bit(0)
446 .length(16)
447 .byte_order(ByteOrder::BigEndian)
448 .unsigned(true)
449 .factor(1.0)
450 .offset(0.0)
451 .min(0.0)
452 .max(100.0)
453 .receivers(ReceiversBuilder::new().none());
454 let message1 = MessageBuilder::new()
455 .id(256)
456 .name("EngineData")
457 .dlc(8)
458 .sender("ECM")
459 .add_signal(signal1);
460 let message2 = MessageBuilder::new()
461 .id(512)
462 .name("BrakeData")
463 .dlc(4)
464 .sender("ECM")
465 .add_signal(signal2);
466
467 let dbc = DbcBuilder::new()
468 .version(version)
469 .nodes(nodes)
470 .add_messages(vec![message1, message2])
471 .build()
472 .unwrap();
473
474 assert_eq!(dbc.messages().len(), 2);
475 }
476
477 #[test]
478 fn test_dbc_builder_messages() {
479 let version = VersionBuilder::new().version("1.0");
480 let nodes = NodesBuilder::new().add_nodes(["ECM"]);
481
482 let signal1 = SignalBuilder::new()
483 .name("RPM")
484 .start_bit(0)
485 .length(16)
486 .byte_order(ByteOrder::BigEndian)
487 .unsigned(true)
488 .factor(1.0)
489 .offset(0.0)
490 .min(0.0)
491 .max(100.0)
492 .receivers(ReceiversBuilder::new().none());
493 let message1 = MessageBuilder::new()
494 .id(256)
495 .name("EngineData")
496 .dlc(8)
497 .sender("ECM")
498 .add_signal(signal1);
499
500 let signal2 = SignalBuilder::new()
501 .name("RPM")
502 .start_bit(0)
503 .length(16)
504 .byte_order(ByteOrder::BigEndian)
505 .unsigned(true)
506 .factor(1.0)
507 .offset(0.0)
508 .min(0.0)
509 .max(100.0)
510 .receivers(ReceiversBuilder::new().none());
511 let message2 = MessageBuilder::new()
512 .id(512)
513 .name("EngineData2")
514 .dlc(8)
515 .sender("ECM")
516 .add_signal(signal2);
517
518 let dbc = DbcBuilder::new()
519 .version(version)
520 .nodes(nodes)
521 .add_message(message1)
522 .add_message(message2)
523 .build()
524 .unwrap();
525
526 assert_eq!(dbc.messages().len(), 2);
527 }
528
529 #[test]
530 fn test_dbc_builder_clear_messages() {
531 let version = VersionBuilder::new().version("1.0");
532 let nodes = NodesBuilder::new().add_nodes(["ECM"]);
533 let signal = SignalBuilder::new()
534 .name("RPM")
535 .start_bit(0)
536 .length(16)
537 .byte_order(ByteOrder::BigEndian)
538 .unsigned(true)
539 .factor(1.0)
540 .offset(0.0)
541 .min(0.0)
542 .max(100.0)
543 .receivers(ReceiversBuilder::new().none());
544 let message = MessageBuilder::new()
545 .id(256)
546 .name("EngineData")
547 .dlc(8)
548 .sender("ECM")
549 .add_signal(signal);
550
551 let dbc = DbcBuilder::new()
552 .version(version)
553 .nodes(nodes)
554 .add_message(message)
555 .clear_messages()
556 .build()
557 .unwrap();
558
559 assert_eq!(dbc.messages().len(), 0);
560 }
561
562 #[test]
563 fn test_dbc_builder_from_dbc() {
564 // Parse an existing DBC
565 let dbc_content = r#"VERSION "1.0"
566
567BU_: ECM TCM
568
569BO_ 256 Engine : 8 ECM
570 SG_ RPM : 0|16@1+ (0.25,0) [0|8000] "rpm"
571"#;
572 let original_dbc = Dbc::parse(dbc_content).unwrap();
573
574 // Create builder from existing DBC
575 let modified_dbc = DbcBuilder::from_dbc(&original_dbc)
576 .add_message(MessageBuilder::new().id(512).name("Brake").dlc(4).sender("TCM"))
577 .build()
578 .unwrap();
579
580 // Verify original data is preserved
581 assert_eq!(modified_dbc.version().map(|v| v.as_str()), Some("1.0"));
582 assert_eq!(modified_dbc.nodes().len(), 2);
583 assert!(modified_dbc.nodes().contains("ECM"));
584 assert!(modified_dbc.nodes().contains("TCM"));
585
586 // Verify original message is present
587 assert_eq!(modified_dbc.messages().len(), 2);
588 assert!(modified_dbc.messages().iter().any(|m| m.id() == 256));
589 assert!(modified_dbc.messages().iter().any(|m| m.id() == 512));
590
591 // Verify original message's signal is preserved
592 let engine_msg = modified_dbc.messages().iter().find(|m| m.id() == 256).unwrap();
593 assert_eq!(engine_msg.signals().len(), 1);
594 assert_eq!(engine_msg.signals().at(0).unwrap().name(), "RPM");
595 }
596
597 #[test]
598 fn test_dbc_builder_from_dbc_empty() {
599 // Parse a minimal DBC
600 let dbc_content = r#"VERSION "1.0"
601
602BU_:
603"#;
604 let original_dbc = Dbc::parse(dbc_content).unwrap();
605
606 // Create builder from existing DBC
607 let modified_dbc = DbcBuilder::from_dbc(&original_dbc)
608 .add_message(MessageBuilder::new().id(256).name("Test").dlc(8).sender("ECM"))
609 .build()
610 .unwrap();
611
612 // Verify version is preserved
613 assert_eq!(modified_dbc.version().map(|v| v.as_str()), Some("1.0"));
614 // Empty nodes are preserved
615 assert!(modified_dbc.nodes().is_empty());
616 // New message is added
617 assert_eq!(modified_dbc.messages().len(), 1);
618 }
619
620 #[test]
621 fn test_dbc_builder_from_dbc_with_extended_multiplexing() {
622 // Parse a DBC with extended multiplexing
623 let dbc_content = r#"VERSION "1.0"
624
625BU_: ECM
626
627BO_ 500 MuxMessage : 8 ECM
628 SG_ Mux1 M : 0|8@1+ (1,0) [0|255] ""
629 SG_ SignalA m0 : 16|16@1+ (0.1,0) [0|100] ""
630
631SG_MUL_VAL_ 500 SignalA Mux1 0-5,10-15 ;
632"#;
633 let original_dbc = Dbc::parse(dbc_content).unwrap();
634
635 // Verify original has extended multiplexing
636 assert_eq!(original_dbc.extended_multiplexing().len(), 1);
637
638 // Create builder from existing DBC and modify it
639 let modified_dbc = DbcBuilder::from_dbc(&original_dbc)
640 .add_extended_multiplexing(
641 ExtendedMultiplexingBuilder::new()
642 .message_id(500)
643 .signal_name("SignalA")
644 .multiplexer_switch("Mux1")
645 .add_value_range(20, 25),
646 )
647 .build()
648 .unwrap();
649
650 // Verify extended multiplexing is preserved and new one added
651 assert_eq!(modified_dbc.extended_multiplexing().len(), 2);
652
653 // Check original entry
654 let original_entry = &modified_dbc.extended_multiplexing()[0];
655 assert_eq!(original_entry.signal_name(), "SignalA");
656 assert_eq!(original_entry.value_ranges().len(), 2);
657 assert_eq!(original_entry.value_ranges()[0], (0, 5));
658 assert_eq!(original_entry.value_ranges()[1], (10, 15));
659
660 // Check new entry
661 let new_entry = &modified_dbc.extended_multiplexing()[1];
662 assert_eq!(new_entry.signal_name(), "SignalA");
663 assert_eq!(new_entry.value_ranges().len(), 1);
664 assert_eq!(new_entry.value_ranges()[0], (20, 25));
665 }
666}