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
//! Internal finite-state machine for implementing decoders.
//!
//! This module is intended for advanced applications that need fine control
//! over decoder internals. See [`crate::avec`] for implementations covering
//! common decoding patterns.
//!
//! **Documentation for this module is incomplete, and the API is likely to
//! undergo significant changes before a full release. Implementing a custom
//! decoder requires a basic understanding of the structure of FIT protocol
//! data.**
//!
//! # Architecture
//!
//! All states are represented by a zero-size, non-copy token. Once enough bytes
//! are ready, transition to another state by calling the token's `advance`
//! method. This will return a successor state token, along with any extracted
//! data.
//!
//! When decoding a data record, the finite-state machine performs a second,
//! interwoven pass over the definition record. This frees implementations to
//! choose how they manage memory constraints. The bytes used to advance a
//! sequence of these `Alt`-suffixed definition states must match those used to
//! advance through their first-pass counterparts with the same field number.
//!
//! Only the initial state, re-exported for convenience as [`Decoder`], can be
//! constructed.
//!
//! This architecture enables the compiler and type system to guide applications
//! toward a correct implementation. However, some areas of the decoding process
//! are not represented in the finite-state machine and must be carefully
//! written:
//!
//! - Reading bytes from the correct place in the document, including buffering
//! or seeking as necessary.
//!
//! - Ending decoding once the specified number of document bytes have been
//! read.
//!
//! - Applying cyclic redundancy checks. A helper function is provided in the
//! [`check`] module.
//!
//! Implementers are recommended to begin by studying and modifying a decoder
//! from the [`crate::avec`] module.
/// Entrypoint to the finite-state machine.
pub type Decoder = DocumentHeader;