KPublicTransport

journey.h
1 /*
2  SPDX-FileCopyrightText: 2018 Volker Krause <[email protected]>
3 
4  SPDX-License-Identifier: LGPL-2.0-or-later
5 */
6 
7 #ifndef KPUBLICTRANSPORT_JOURNEY_H
8 #define KPUBLICTRANSPORT_JOURNEY_H
9 
10 #include "datatypes.h"
11 #include "disruption.h"
12 #include "individualtransport.h"
13 #include "line.h"
14 #include "load.h"
15 #include "location.h"
16 #include "path.h"
17 #include "platform.h"
18 #include "vehicle.h"
19 
20 #include <QDateTime>
21 
22 #include <vector>
23 
24 namespace KPublicTransport {
25 
26 class JourneySectionPrivate;
27 class RentalVehicle;
28 class Stopover;
29 
30 /** A segment of a journey plan. */
31 class KPUBLICTRANSPORT_EXPORT JourneySection
32 {
33  KPUBLICTRANSPORT_GADGET(JourneySection)
34 
35 public:
36  /** Mode of transport.
37  * These categories are fairly coarse, for a more detailed break-down of PublicTransport see Line::Mode.
38  */
39  enum Mode {
40  Invalid = 0,
41  PublicTransport = 1,
42  Transfer = 2,
43  Walking = 4,
44  Waiting = 8,
45  RentedVehicle = 16, ///< free floating or dock-based rental bike service, electric scooters, car sharing services, ie. any vehicle you drive yourself but that isn't your own
46  IndividualTransport = 32, ///< using your own vehicle (bike, car, etc).
47  };
48  Q_ENUM(Mode)
49  Q_DECLARE_FLAGS(Modes, Mode)
50  Q_FLAG(Modes)
51 
52  /** Mode of transport for this section. */
53  KPUBLICTRANSPORT_PROPERTY(Mode, mode, setMode)
54 
55  /** Planned departure time. */
56  KPUBLICTRANSPORT_PROPERTY(QDateTime, scheduledDepartureTime, setScheduledDepartureTime)
57  /** Actual departure time, if available.
58  * Set to invalid to indicate real-time data is not available.
59  */
60  KPUBLICTRANSPORT_PROPERTY(QDateTime, expectedDepartureTime, setExpectedDepartureTime)
61  /** @c true if this has real-time data. */
62  Q_PROPERTY(bool hasExpectedDepartureTime READ hasExpectedDepartureTime STORED false)
63  /** Difference to schedule in minutes. */
64  Q_PROPERTY(int departureDelay READ departureDelay STORED false)
65 
66  /** Planned arrival time. */
67  KPUBLICTRANSPORT_PROPERTY(QDateTime, scheduledArrivalTime, setScheduledArrivalTime)
68  /** Actual arrival time, if available.
69  * Set to invalid to indicate real-time data is not available.
70  */
71  KPUBLICTRANSPORT_PROPERTY(QDateTime, expectedArrivalTime, setExpectedArrivalTime)
72  /** @c true if this has real-time data. */
73  Q_PROPERTY(bool hasExpectedArrivalTime READ hasExpectedArrivalTime STORED false)
74  /** Difference to schedule in minutes. */
75  Q_PROPERTY(int arrivalDelay READ arrivalDelay STORED false)
76 
77  /** Duration of the section in seconds. */
78  Q_PROPERTY(int duration READ duration STORED false)
79  /** Distance of the section in meter. */
80  KPUBLICTRANSPORT_PROPERTY(int, distance, setDistance)
81 
82  /** Departure location of this segment. */
83  KPUBLICTRANSPORT_PROPERTY(KPublicTransport::Location, from, setFrom)
84  /** Arrival location of this segment. */
85  KPUBLICTRANSPORT_PROPERTY(KPublicTransport::Location, to, setTo)
86  /** Route to take on this segment. */
87  KPUBLICTRANSPORT_PROPERTY(KPublicTransport::Route, route, setRoute)
88 
89  /** Planned departure platform. */
90  KPUBLICTRANSPORT_PROPERTY(QString, scheduledDeparturePlatform, setScheduledDeparturePlatform)
91  /** Actual departure platform, in case real-time information are available. */
92  KPUBLICTRANSPORT_PROPERTY(QString, expectedDeparturePlatform, setExpectedDeparturePlatform)
93  /** @c true if real-time platform information are available. */
94  Q_PROPERTY(bool hasExpectedDeparturePlatform READ hasExpectedDeparturePlatform STORED false)
95  /** @c true if we have real-time platform information and the platform changed. */
96  Q_PROPERTY(bool departurePlatformChanged READ departurePlatformChanged STORED false)
97 
98  /** Planned arrival platform. */
99  KPUBLICTRANSPORT_PROPERTY(QString, scheduledArrivalPlatform, setScheduledArrivalPlatform)
100  /** Actual arrival platform, in case real-time information are available. */
101  KPUBLICTRANSPORT_PROPERTY(QString, expectedArrivalPlatform, setExpectedArrivalPlatform)
102  /** @c true if real-time platform information are available. */
103  Q_PROPERTY(bool hasExpectedArrivalPlatform READ hasExpectedArrivalPlatform STORED false)
104  /** @c true if we have real-time platform information and the platform changed. */
105  Q_PROPERTY(bool arrivalPlatformChanged READ arrivalPlatformChanged STORED false)
106 
107  /** Disruption effect on this section, if any. */
108  KPUBLICTRANSPORT_PROPERTY(KPublicTransport::Disruption::Effect, disruptionEffect, setDisruptionEffect)
109  /** General human-readable notes on this service, e.g. details about a disruption. */
110  KPUBLICTRANSPORT_PROPERTY(QStringList, notes, setNotes)
111 
112  /** Intermediate stops for consumption by QML. */
113  Q_PROPERTY(QVariantList intermediateStops READ intermediateStopsVariant)
114 
115  /** All departure information represented as Stopover object. */
116  Q_PROPERTY(KPublicTransport::Stopover departure READ departure STORED false)
117  /** All arrival information represented as Stopover object. */
118  Q_PROPERTY(KPublicTransport::Stopover arrival READ arrival STORED false)
119 
120  /** CO₂ emission during this journey section, in gram.
121  * In case the backend doesn't provide this value, it is estimated based on the
122  * distance travelled during this section and the mode of transport, based on
123  * average emission values from https://en.wikipedia.org/wiki/Environmental_impact_of_transport
124  * This value can be 0 (e.g. in case of walk or wait sections), or -1 if no
125  * information is available.
126  */
127  KPUBLICTRANSPORT_PROPERTY(int, co2Emission, setCo2Emission)
128 
129  /** Vehicle load information for this journey section.
130  * Contains LoadInfo objects for consumption by QML.
131  */
132  Q_PROPERTY(QVariantList loadInformation READ loadInformationVariant STORED false)
133 
134  /** Information about a rental vehicle, for sections using one. */
135  KPUBLICTRANSPORT_PROPERTY(KPublicTransport::RentalVehicle, rentalVehicle, setRentalVehicle)
136 
137  /** Movement path for this journey section.
138  * This can be navigation instructions for individual transport modes and transfers,
139  * or the path a public transport vehicle takes.
140  */
141  KPUBLICTRANSPORT_PROPERTY(KPublicTransport::Path, path, setPath)
142 
143  /** Vehicle coach layout information at departure. */
144  KPUBLICTRANSPORT_PROPERTY(KPublicTransport::Vehicle, departureVehicleLayout, setDepartureVehicleLayout)
145  /** Platform layout information at departure. */
146  KPUBLICTRANSPORT_PROPERTY(KPublicTransport::Platform, departurePlatformLayout, setDeparturePlatformLayout)
147  /** Vehicle coach layout information at arrival.
148  * Note that this does not necessarily need to be the same as departureVehicleLayout, as e.g. trains
149  * can be split up or merged along the way.
150  */
151  KPUBLICTRANSPORT_PROPERTY(KPublicTransport::Vehicle, arrivalVehicleLayout, setArrivalVehicleLayout)
152  /** Platform layout information at arrival. */
153  KPUBLICTRANSPORT_PROPERTY(KPublicTransport::Platform, arrivalPlatformLayout, setArrivalPlatformLayout)
154 
155  /** Individual transport details for sections using your own vehicle. */
156  KPUBLICTRANSPORT_PROPERTY(KPublicTransport::IndividualTransport, individualTransport, setIndividualTransport)
157 
158 public:
159  bool hasExpectedDepartureTime() const;
160  int departureDelay() const;
161  bool hasExpectedArrivalTime() const;
162  int arrivalDelay() const;
163 
164  int duration() const;
165 
166  bool hasExpectedDeparturePlatform() const;
167  bool departurePlatformChanged() const;
168  bool hasExpectedArrivalPlatform() const;
169  bool arrivalPlatformChanged() const;
170 
171  /** Adds a note. This will check for duplicates and normalize the notes. */
172  void addNote(const QString &note);
173  void addNotes(const QStringList &notes);
174 
175  /** Intermediate stop-overs along this journey section.
176  * This does not include the departure and arrival stops, and might be empty on backends not providing this information.
177  */
178  const std::vector<Stopover>& intermediateStops() const;
179  /** Moves the intermediate stops out of this object. */
180  std::vector<Stopover>&& takeIntermediateStops();
181  /** Set the intermediate stops. */
182  void setIntermediateStops(std::vector<Stopover> &&stops);
183 
184  /** Returns the departure stopover of this journey section.
185  * This is the same information as accessible by individual properties,
186  * so this is mainly useful if you have to interface with code expecting a Stopover object.
187  */
188  Stopover departure() const;
189  /** Returns the arrival stopover of this journey section.
190  * This is the same information as accessible by individual properties,
191  * so this is mainly useful if you have to interface with code expecting a Stopover object.
192  */
193  Stopover arrival() const;
194 
195  /** Vehicle load information for this journey section, if available. */
196  const std::vector<LoadInfo>& loadInformation() const;
197  /** Moves the load information out of this object for modification. */
198  std::vector<LoadInfo>&& takeLoadInformation();
199  /** Set the vehicle load information for this journey section. */
200  void setLoadInformation(std::vector<LoadInfo>&& loadInfo);
201 
202  /** Checks if two instances refer to the same journey section (which does not necessarily mean they are exactly equal). */
203  static bool isSame(const JourneySection &lhs, const JourneySection &rhs);
204 
205  /** Merge two instances.
206  * This assumes isSame(lhs, rhs) and tries to preserve the most detailed information.
207  */
208  static JourneySection merge(const JourneySection &lhs, const JourneySection &rhs);
209 
210  /** Serializes one journey section to JSON. */
211  static QJsonObject toJson(const JourneySection &section);
212  /** Serializes a vector of journey sections to JSON. */
213  static QJsonArray toJson(const std::vector<JourneySection> &sections);
214  /** Deserialize an object from JSON. */
215  static JourneySection fromJson(const QJsonObject &obj);
216  /** Deserialize a vector of journey sections from JSON. */
217  static std::vector<JourneySection> fromJson(const QJsonArray &array);
218 
219 private:
220  QVariantList intermediateStopsVariant() const;
221  QVariantList loadInformationVariant() const;
222 };
223 
224 Q_DECLARE_OPERATORS_FOR_FLAGS(JourneySection::Modes)
225 
226 class JourneyPrivate;
227 
228 /** A journey plan. */
229 class KPUBLICTRANSPORT_EXPORT Journey
230 {
231  KPUBLICTRANSPORT_GADGET(Journey)
232  /** Journey sections for consumption by QML. */
233  Q_PROPERTY(QVariantList sections READ sectionsVariant)
234  /** Departure time of the journey, according to schedule. */
235  Q_PROPERTY(QDateTime scheduledDepartureTime READ scheduledDepartureTime STORED false)
236  /** @c true if this has real-time data. */
237  Q_PROPERTY(bool hasExpectedDepartureTime READ hasExpectedDepartureTime STORED false)
238  /** Difference to schedule in minutes. */
239  Q_PROPERTY(int departureDelay READ departureDelay STORED false)
240 
241  /** Arrival time of the journey, according to schedule. */
242  Q_PROPERTY(QDateTime scheduledArrivalTime READ scheduledArrivalTime STORED false)
243  /** @c true if this has real-time data. */
244  Q_PROPERTY(bool hasExpectedArrivalTime READ hasExpectedArrivalTime STORED false)
245  /** Difference to schedule in minutes. */
246  Q_PROPERTY(int arrivalDelay READ arrivalDelay STORED false)
247 
248  /** Duration of the entire journey in seconds. */
249  Q_PROPERTY(int duration READ duration STORED false)
250  /** Number of changes on this journey. */
251  Q_PROPERTY(int numberOfChanges READ numberOfChanges STORED false)
252  /** Worst disruption effect of any of the journey sections. */
253  Q_PROPERTY(KPublicTransport::Disruption::Effect disruptionEffect READ disruptionEffect STORED false)
254 
255 public:
256  /** The journey sections. */
257  const std::vector<JourneySection>& sections() const;
258  /** Moves the journey sections out of this object. */
259  std::vector<JourneySection>&& takeSections();
260  /** Sets the journey sections. */
261  void setSections(std::vector<JourneySection> &&sections);
262 
263  QDateTime scheduledDepartureTime() const;
264  bool hasExpectedDepartureTime() const;
265  int departureDelay() const;
266 
267  QDateTime scheduledArrivalTime() const;
268  bool hasExpectedArrivalTime() const;
269  int arrivalDelay() const;
270 
271  int duration() const;
272  int numberOfChanges() const;
273  Disruption::Effect disruptionEffect() const;
274 
275  /** Checks if two instances refer to the same journey (which does not necessarily mean they are exactly equal). */
276  static bool isSame(const Journey &lhs, const Journey &rhs);
277 
278  /** Merge two instances.
279  * This assumes isSame(lhs, rhs) and tries to preserve the most detailed information.
280  */
281  static Journey merge(const Journey &lhs, const Journey &rhs);
282 
283  /** Serializes one journey object to JSON. */
284  static QJsonObject toJson(const Journey &journey);
285  /** Serializes a vector of journey objects to JSON. */
286  static QJsonArray toJson(const std::vector<Journey> &journeys);
287  /** Deserialize an object from JSON. */
288  static Journey fromJson(const QJsonObject &obj);
289  /** Deserialize a list of journey from JSON. */
290  static std::vector<Journey> fromJson(const QJsonArray &array);
291 
292 private:
293  QVariantList sectionsVariant() const;
294 };
295 
296 }
297 
298 Q_DECLARE_METATYPE(KPublicTransport::JourneySection)
299 Q_DECLARE_METATYPE(KPublicTransport::Journey)
300 
301 #endif // KPUBLICTRANSPORT_JOURNEY_H
Query operations and data types for accessing realtime public transport information from online servi...
Definition: attribution.cpp:16
Vehicle load information.
Definition: load.h:37
Individual transport mode details for a journey section, and for specifying journey requests...
A segment of a journey plan.
Definition: journey.h:31
A route of a public transport line.
Definition: line.h:120
Mode
Mode of transport.
Definition: journey.h:39
Information about the vehicle used on a journey.
Definition: vehicle.h:140
A journey plan.
Definition: journey.h:229
Information about an arrival and/or departure of a vehicle at a stop area.
Definition: stopover.h:25
Information about the layout of a station platform.
Definition: platform.h:44
A path followed by any kind of location change.
Definition: path.h:88
An individual rental vehicle used on a JourneySection, ie.
Definition: rentalvehicle.h:27
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Sun Oct 24 2021 23:05:21 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.