rtcc/
lib.rs

Help
1//! Data structures and traits to be implemented by real-time clock / calendar devices.
2//!
3//! Prefer to use only the methods from the `DateTimeAccess` rather than the individual
4//! methods from the `Rtcc` trait to avoid situations where the passing of time
5//! makes the results of the method calls inconsistent if you combine the results
6//! of several methods.
7//!
8//! For example, this can happen at certain timepoints:
9//! 1. The time is `01:59:59`
10//! 2. A call to `hours()` returns 1.
11//! 3. The time is increased to `02:00:00`.
12//! 4. A call to `minutes()` returns 0.
13//! 5. A call to `seconds()` returns 0.
14//! 6. Your system thinks it is `01:00:00`.
15//!
16//! The same applies to the date as well, as well as when calling setter methods.
17
18#![deny(unsafe_code, missing_docs)]
19#![no_std]
20
21pub use chrono::{DateTime, Datelike, NaiveDate, NaiveDateTime, NaiveTime, Timelike};
22
23/// Hours in either 12-hour (AM/PM) or 24-hour format
24#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
25pub enum Hours {
26    /// AM [1-12]
27    AM(u8),
28    /// PM [1-12]
29    PM(u8),
30    /// 24H format [0-23]
31    H24(u8),
32}
33
34/// Real-Time Clock / Calendar DateTimeAccess trait to read/write a complete
35/// date/time.
36///
37/// Prefer to use only these methods rather than the individual methods from the
38/// `Rtcc` trait to avoid situations where the passing of time makes the results
39/// of the method calls inconsistent if you combine the results of several methods.
40///
41/// For example, this can happen at certain timepoints:
42/// 1. The time is `01:59:59`
43/// 2. A call to `hours()` returns 1.
44/// 3. The time is increased to `02:00:00`.
45/// 4. A call to `minutes()` returns 0.
46/// 5. A call to `seconds()` returns 0.
47/// 6. Your system thinks it is `01:00:00`.
48///
49/// The same applies to the date as well, as well as when calling setter methods.
50pub trait DateTimeAccess {
51    /// Error type
52    type Error;
53
54    /// Read the date and time.
55    fn datetime(&mut self) -> Result<NaiveDateTime, Self::Error>;
56
57    /// Set the date and time.
58    ///
59    /// This will set the hour operating mode to 24h and the weekday to the
60    /// day number starting from Sunday = 1.
61    fn set_datetime(&mut self, datetime: &NaiveDateTime) -> Result<(), Self::Error>;
62}
63
64/// Real-Time Clock / Calendar trait
65///
66/// If you want to combine calls to these methods, prefer to use only
67/// the `DateTimeAccess` trait to avoid situations where the passing of time makes the results
68/// of the method calls inconsistent.
69///
70/// For example, this can happen at certain timepoints:
71/// 1. The time is `01:59:59`
72/// 2. A call to `hours()` returns 1.
73/// 3. The time is increased to `02:00:00`.
74/// 4. A call to `minutes()` returns 0.
75/// 5. A call to `seconds()` returns 0.
76/// 6. Your system thinks it is `01:00:00`.
77///
78/// The same applies to the date, as well as when calling setter methods.
79pub trait Rtcc: DateTimeAccess {
80    /// Read the seconds.
81    fn seconds(&mut self) -> Result<u8, Self::Error>;
82
83    /// Read the minutes.
84    fn minutes(&mut self) -> Result<u8, Self::Error>;
85
86    /// Read the hours.
87    fn hours(&mut self) -> Result<Hours, Self::Error>;
88
89    /// Read the time.
90    fn time(&mut self) -> Result<NaiveTime, Self::Error>;
91
92    /// Read the day of the week [1-7].
93    fn weekday(&mut self) -> Result<u8, Self::Error>;
94
95    /// Read the day of the month [1-31].
96    fn day(&mut self) -> Result<u8, Self::Error>;
97
98    /// Read the month [1-12].
99    fn month(&mut self) -> Result<u8, Self::Error>;
100
101    /// Read the year (e.g. 2000).
102    fn year(&mut self) -> Result<u16, Self::Error>;
103
104    /// Read the date.
105    fn date(&mut self) -> Result<NaiveDate, Self::Error>;
106
107    /// Set the seconds [0-59].
108    fn set_seconds(&mut self, seconds: u8) -> Result<(), Self::Error>;
109
110    /// Set the minutes [0-59].
111    fn set_minutes(&mut self, minutes: u8) -> Result<(), Self::Error>;
112
113    /// Set the hours.
114    ///
115    /// Changes the operating mode to 12h/24h depending on the parameter.
116    fn set_hours(&mut self, hours: Hours) -> Result<(), Self::Error>;
117
118    /// Set the time.
119    fn set_time(&mut self, time: &NaiveTime) -> Result<(), Self::Error>;
120
121    /// Set the day of week [1-7].
122    fn set_weekday(&mut self, weekday: u8) -> Result<(), Self::Error>;
123
124    /// Set the day of month [1-31].
125    fn set_day(&mut self, day: u8) -> Result<(), Self::Error>;
126
127    /// Set the month [1-12].
128    fn set_month(&mut self, month: u8) -> Result<(), Self::Error>;
129
130    /// Set the year. (e.g. 2000)
131    fn set_year(&mut self, year: u16) -> Result<(), Self::Error>;
132
133    /// Set the date.
134    fn set_date(&mut self, date: &NaiveDate) -> Result<(), Self::Error>;
135}
rtcc/lib.rs

rtcc/
lib.rs
