6
6
//! weeks since the start of GPS time, and a time of week counting the number of
7
7
//! seconds since the beginning of the week. In GPS time the week begins at
8
8
//! midnight on Sunday.
9
+ //!
10
+ //! [`GpsTime`] is the primary representation used in swiftnav-rs. Other time bases
11
+ //! are available, such as [`Utctime`], [`GalTime`], [`BdsTime`], and [`GloTime`]
12
+ //! along with conversions for all of these to and from [`GpsTime`].
13
+ //! Not all functionality is available in these other representations, so it's
14
+ //! intended that all times are to converted to [`GpsTime`] before use with
15
+ //! swiftnav-rs.
16
+ //!
17
+ //! # ⚠️ 🦘 ⏱ ⚠️ - Leap Seconds
18
+ //! UTC time occasinally adds additional seconds to keep it synchronized with the
19
+ //! slowly changing spin of the earth. This complicates time keeping, so most
20
+ //! GNSS time bases ignore leap seconds and thus slowly grow out of sync with UTC.
21
+ //! This is fine when dealing with GNSS data, but it's common that people want time
22
+ //! to be represented as a UTC time since that's what people are more familiar with.
23
+ //! swiftnav-rs provides ways to convert to and from UTC synchronized time bases
24
+ //! and is able to correctly compensate for leap seconds in two ways.
25
+ //!
26
+ //! The first is by using the UTC conversion parameters broadcast by GNSS systems
27
+ //! that receivers can decode. [`UtcParams`] is how swiftnav-rs represents this
28
+ //! information, and [`UtcParams::decode()`] is provided for decoding the raw GPS
29
+ //! navigation subframe with this information. This is the prefered method since it
30
+ //! is usually available when processing raw GNSS data and ensures that the right
31
+ //! offset is applied at the right time.
32
+ //!
33
+ //! The second way is to use a table of historical leap seconds that is compiled
34
+ //! in to swftnav-rs. This list is kept up to date in the source code as new leap
35
+ //! seconds are announced, but once the code is compiled there is no way to update
36
+ //! this table with new leap seconds. This obviously means that sooner or later
37
+ //! the hard coded leap second information will become out of date and the
38
+ //! converted times will be inaccurate. This is fine if you are processing
39
+ //! historical data, but processing live data runs the risk of an incorrect time
40
+ //! conversion.
41
+ //!
42
+ //! When converting to or from a time base that uses leap seconds (i.e. [`UtcTime`]
43
+ //! and [`GloTime`]) two functions are always provided, one which takes a
44
+ //! [`UtcParams`] object to handle the leap second conversion and one which doesn't
45
+ //! take a [`UtcParams`] object but has `_hardcoded` appended to the function name.
9
46
10
47
use crate :: c_bindings;
11
48
use std:: error:: Error ;
@@ -34,9 +71,12 @@ pub const BDS_TIME_START: GpsTime = GpsTime::new_unchecked(
34
71
pub const GLO_TIME_START : GpsTime =
35
72
GpsTime :: new_unchecked ( c_bindings:: GLO_EPOCH_WN as i16 , c_bindings:: GLO_EPOCH_TOW ) ;
36
73
74
+ /// Error type when a given GPS time is not valid
37
75
#[ derive( Debug , Copy , Clone , PartialOrd , PartialEq ) ]
38
76
pub enum InvalidGpsTime {
77
+ /// Indicates an invalid week number was given, with the invalid value returned
39
78
InvalidWN ( i16 ) ,
79
+ /// Indicates an invalid time of week was given, with the invalid value returned
40
80
InvalidTOW ( f64 ) ,
41
81
}
42
82
@@ -121,7 +161,12 @@ impl GpsTime {
121
161
}
122
162
123
163
/// Converts the GPS time into UTC time
164
+ ///
165
+ /// # Panics
166
+ /// This function will panic if the GPS time is not valid
124
167
pub fn to_utc ( self , utc_params : & UtcParams ) -> UtcTime {
168
+ assert ! ( self . is_valid( ) ) ;
169
+
125
170
let mut utc = UtcTime :: default ( ) ;
126
171
unsafe {
127
172
c_bindings:: gps2utc ( self . c_ptr ( ) , utc. mut_c_ptr ( ) , utc_params. c_ptr ( ) ) ;
@@ -132,9 +177,15 @@ impl GpsTime {
132
177
/// Converts the GPS time into UTC time using the hardcoded list of leap
133
178
/// seconds.
134
179
///
135
- /// Note: The hard coded list of leap seconds will get out of date, it is
180
+ /// # ⚠️ 🦘 ⏱ ⚠️ - Leap Seconds
181
+ /// The hard coded list of leap seconds will get out of date, it is
136
182
/// preferable to use [`GpsTime::to_utc()`] with the newest set of UTC parameters
183
+ ///
184
+ /// # Panics
185
+ /// This function will panic if the GPS time is not valid
137
186
pub fn to_utc_hardcoded ( self ) -> UtcTime {
187
+ assert ! ( self . is_valid( ) ) ;
188
+
138
189
let mut utc = UtcTime :: default ( ) ;
139
190
unsafe {
140
191
c_bindings:: gps2utc ( self . c_ptr ( ) , utc. mut_c_ptr ( ) , std:: ptr:: null ( ) ) ;
@@ -150,8 +201,9 @@ impl GpsTime {
150
201
/// Gets the number of seconds difference between GPS and UTC using the hardcoded
151
202
/// list of leap seconds
152
203
///
153
- /// Note: The hard coded list of leap seconds will get out of date, it is
154
- /// preferable to use [`GpsTime::utc_offset_hardcoded()`] with the newest set
204
+ /// # ⚠️ 🦘 ⏱ ⚠️ - Leap Seconds
205
+ /// The hard coded list of leap seconds will get out of date, it is
206
+ /// preferable to use [`GpsTime::utc_offset()`] with the newest set
155
207
/// of UTC parameters
156
208
pub fn utc_offset_hardcoded ( & self ) -> f64 {
157
209
unsafe { c_bindings:: get_gps_utc_offset ( self . c_ptr ( ) , std:: ptr:: null ( ) ) }
@@ -165,8 +217,9 @@ impl GpsTime {
165
217
/// Checks to see if this point in time is a UTC leap second event using the
166
218
/// hardcoded list of leap seconds
167
219
///
168
- /// Note: The hard coded list of leap seconds will get out of date, it is
169
- /// preferable to use [`GpsTime::is_leap_second_event_hardcoded()`] with the newest
220
+ /// # ⚠️ 🦘 ⏱ ⚠️ - Leap Seconds
221
+ /// The hard coded list of leap seconds will get out of date, it is
222
+ /// preferable to use [`GpsTime::is_leap_second_event()`] with the newest
170
223
/// set of UTC parameters
171
224
pub fn is_leap_second_event_hardcoded ( & self ) -> bool {
172
225
unsafe { c_bindings:: is_leap_second_event ( self . c_ptr ( ) , std:: ptr:: null ( ) ) }
@@ -229,7 +282,8 @@ impl GpsTime {
229
282
/// Converts a GPS time into a Glonass time using the hardcoded list of leap
230
283
/// seconds.
231
284
///
232
- /// Note: The hard coded list of leap seconds will get out of date, it is
285
+ /// # ⚠️ 🦘 ⏱ ⚠️ - Leap Seconds
286
+ /// The hard coded list of leap seconds will get out of date, it is
233
287
/// preferable to use [`GpsTime::to_glo()`] with the newest set of UTC parameters
234
288
///
235
289
/// # Panics
@@ -486,7 +540,7 @@ impl GloTime {
486
540
}
487
541
}
488
542
489
- /// Structure containing GPS UTC correction parameters
543
+ /// GPS UTC correction parameters
490
544
#[ derive( Clone ) ]
491
545
pub struct UtcParams ( c_bindings:: utc_params_t ) ;
492
546
@@ -499,13 +553,13 @@ impl UtcParams {
499
553
& self . 0
500
554
}
501
555
502
- /// Decodes UTC parameters from GLS LNAV message subframe 4 words 6-10.
556
+ /// Decodes UTC parameters from GPS LNAV message subframe 4 words 6-10.
503
557
///
504
558
/// Note: Fills out the full time of week from current gps week cycle. Also
505
559
/// sets t_lse to the exact GPS time at the start of the leap second event.
506
560
///
507
- /// References:
508
- /// -# IS-GPS-200H, Section 20.3.3.5.1.6
561
+ /// # References
562
+ /// * IS-GPS-200H, Section 20.3.3.5.1.6
509
563
pub fn decode ( words : & [ u32 ; 8 ] ) -> Option < Self > {
510
564
let mut params = UtcParams :: default ( ) ;
511
565
let result = unsafe { c_bindings:: decode_utc_parameters ( words, params. mut_c_ptr ( ) ) } ;
@@ -518,6 +572,9 @@ impl UtcParams {
518
572
}
519
573
520
574
/// Build the UTC parameters from the already decoded parameters
575
+ ///
576
+ /// # Panics
577
+ /// This function will panic if either `tot` or `t_lse` are not valid
521
578
pub fn from_components (
522
579
a0 : f64 ,
523
580
a1 : f64 ,
@@ -527,6 +584,8 @@ impl UtcParams {
527
584
dt_ls : i8 ,
528
585
dt_lsf : i8 ,
529
586
) -> UtcParams {
587
+ assert ! ( tot. is_valid( ) && t_lse. is_valid( ) ) ;
588
+
530
589
let tot = tot. to_gps_time_t ( ) ;
531
590
let t_lse = t_lse. to_gps_time_t ( ) ;
532
591
UtcParams ( c_bindings:: utc_params_t {
@@ -576,7 +635,7 @@ impl Default for UtcParams {
576
635
}
577
636
}
578
637
579
- /// Structure representing UTC time
638
+ /// Representation of UTC time
580
639
///
581
640
/// Note: This implementation does not aim to be able to represent arbitrary dates and times.
582
641
/// It is only meant to represent dates and times over the period that GNSS systems have been
@@ -722,7 +781,7 @@ impl<Tz: chrono::offset::TimeZone> From<chrono::DateTime<Tz>> for UtcTime {
722
781
}
723
782
}
724
783
725
- /// Structure representing a modified julian date (MJD)
784
+ /// Representation of modified julian dates (MJD)
726
785
#[ derive( Copy , Clone , Debug , PartialEq , PartialOrd ) ]
727
786
pub struct MJD ( f64 ) ;
728
787
0 commit comments