gistools/readers/gtfs/realtime/trip/update.rs
1use crate::readers::{
2 GTFSRealtimeStopTimeUpdate, GTFSRealtimeTripDescriptor, GTFSRealtimeTripProperties,
3 GTFSRealtimeVehicleDescriptor,
4};
5use alloc::vec::Vec;
6use pbf::{ProtoRead, Protobuf};
7
8/// Realtime update of the progress of a vehicle along a trip.
9/// Depending on the value of ScheduleRelationship, a TripUpdate can specify:
10/// - A trip that proceeds along the schedule.
11/// - A trip that proceeds along a route but has no fixed schedule.
12/// - A trip that have been added or removed with regard to schedule.
13///
14/// The updates can be for future, predicted arrival/departure events, or for
15/// past events that already occurred.
16/// Normally, updates should get more precise and more certain (see
17/// uncertainty below) as the events gets closer to current time.
18/// Even if that is not possible, the information for past events should be
19/// precise and certain. In particular, if an update points to time in the past
20/// but its update's uncertainty is not 0, the client should conclude that the
21/// update is a (wrong) prediction and that the trip has not completed yet.
22///
23/// Note that the update can describe a trip that is already completed.
24/// To this end, it is enough to provide an update for the last stop of the trip.
25/// If the time of that is in the past, the client will conclude from that that
26/// the whole trip is in the past (it is possible, although inconsequential, to
27/// also provide updates for preceding stops).
28/// This option is most relevant for a trip that has completed ahead of schedule,
29/// but according to the schedule, the trip is still proceeding at the current
30/// time. Removing the updates for this trip could make the client assume
31/// that the trip is still proceeding.
32/// Note that the feed provider is allowed, but not required, to purge past
33/// updates - this is one case where this would be practically useful.
34#[derive(Debug, Default, Clone, PartialEq)]
35pub struct GTFSRealtimeTripUpdate {
36 /// The Trip that this message applies to. There can be at most one
37 /// TripUpdate entity for each actual trip instance.
38 /// If there is none, that means there is no prediction information available.
39 /// It does *not* mean that the trip is progressing according to schedule.
40 pub trip: GTFSRealtimeTripDescriptor, // 1 [message]
41 /// Updates to StopTimes for the trip (both future, i.e., predictions, and in
42 /// some cases, past ones, i.e., those that already happened).
43 /// The updates must be sorted by stop_sequence, and apply for all the
44 /// following stops of the trip up to the next specified one.
45 ///
46 /// Example 1:
47 ///
48 /// For a trip with 20 stops, a StopTimeUpdate with arrival delay and departure
49 /// delay of 0 for stop_sequence of the current stop means that the trip is
50 /// exactly on time.
51 ///
52 /// Example 2:
53 ///
54 /// For the same trip instance, 3 StopTimeUpdates are provided:
55 /// - delay of 5 min for stop_sequence 3
56 /// - delay of 1 min for stop_sequence 8
57 /// - delay of unspecified duration for stop_sequence 10
58 ///
59 /// This will be interpreted as:
60 /// - stop_sequences 3,4,5,6,7 have delay of 5 min.
61 /// - stop_sequences 8,9 have delay of 1 min.
62 /// - stop_sequences 10,... have unknown delay.
63 pub stop_time_update: Vec<GTFSRealtimeStopTimeUpdate>, // 2 [message]
64 /// Additional information on the vehicle that is serving this trip.
65 pub vehicle: Option<GTFSRealtimeVehicleDescriptor>, // 3 [message]
66 /// The most recent moment at which the vehicle's real-time progress was measured
67 /// to estimate StopTimes in the future. When StopTimes in the past are provided,
68 /// arrival/departure times may be earlier than this value. In POSIX
69 /// time (i.e., the number of seconds since January 1st 1970 00:00:00 UTC).
70 pub timestamp: Option<u64>, // 4 [uint64]
71 /// The current schedule deviation for the trip. Delay should only be
72 /// specified when the prediction is given relative to some existing schedule
73 /// in GTFS.
74 ///
75 /// Delay (in seconds) can be positive (meaning that the vehicle is late) or
76 /// negative (meaning that the vehicle is ahead of schedule). Delay of 0
77 /// means that the vehicle is exactly on time.
78 ///
79 /// Delay information in StopTimeUpdates take precedent of trip-level delay
80 /// information, such that trip-level delay is only propagated until the next
81 /// stop along the trip with a StopTimeUpdate delay value specified.
82 ///
83 /// Feed providers are strongly encouraged to provide a TripUpdate.timestamp
84 /// value indicating when the delay value was last updated, in order to
85 /// evaluate the freshness of the data.
86 ///
87 /// NOTE: This field is still experimental, and subject to change. It may be
88 /// formally adopted in the future.
89 pub delay: Option<i32>, // 5 [int32]
90 /// Additional information about the trip.
91 pub trip_properties: Option<GTFSRealtimeTripProperties>, // 6 [message]
92}
93/// Read in the contents of the GTFSRealtimeTripUpdate
94impl ProtoRead for GTFSRealtimeTripUpdate {
95 fn read(&mut self, tag: u64, pb: &mut Protobuf) {
96 match tag {
97 1 => {
98 let mut trip = GTFSRealtimeTripDescriptor::default();
99 pb.read_message(&mut trip);
100 self.trip = trip;
101 }
102 2 => {
103 let mut stop_time_update = GTFSRealtimeStopTimeUpdate::default();
104 pb.read_message(&mut stop_time_update);
105 self.stop_time_update.push(stop_time_update);
106 }
107 3 => {
108 let mut vehicle = GTFSRealtimeVehicleDescriptor::default();
109 pb.read_message(&mut vehicle);
110 self.vehicle = Some(vehicle);
111 }
112 4 => self.timestamp = Some(pb.read_varint()),
113 5 => self.delay = Some(pb.read_s_varint()),
114 6 => {
115 let mut trip_properties = GTFSRealtimeTripProperties::default();
116 pb.read_message(&mut trip_properties);
117 self.trip_properties = Some(trip_properties);
118 }
119 _ => panic!("unknown tag {}", tag),
120 }
121 }
122}