[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[avr-libc-commit] [2366] Updated time.h for new function iso_weeknum(),
From: |
Mike Rice |
Subject: |
[avr-libc-commit] [2366] Updated time.h for new function iso_weeknum(), and made several parameters const. |
Date: |
Sat, 27 Apr 2013 15:38:00 +0000 |
Revision: 2366
http://svn.sv.gnu.org/viewvc/?view=rev&root=avr-libc&revision=2366
Author: swfltek
Date: 2013-04-27 15:37:57 +0000 (Sat, 27 Apr 2013)
Log Message:
-----------
Updated time.h for new function iso_weeknum(), and made several parameters
const. Expanded the overview with a more complete description, detailing the
few departures from the standard, and edited some comments for clarity.
Modified Paths:
--------------
trunk/avr-libc/include/time.h
Modified: trunk/avr-libc/include/time.h
===================================================================
--- trunk/avr-libc/include/time.h 2013-04-27 15:32:59 UTC (rev 2365)
+++ trunk/avr-libc/include/time.h 2013-04-27 15:37:57 UTC (rev 2366)
@@ -35,13 +35,65 @@
<h3>Introduction to the Time functions</h3>
This file declares the time functions implemented in \c avr-libc.
- The implementation attempts to conform to ISO/IEC 9899 (C90). However,
since there is no
- platform standard method to obtain the current time, time zone, or
daylight savings
- 'rules', the application must initialize the time system with this
information.
- The functions set_zone(), set_dst(), and set_system_time() are provided
for this intialization.
+ The implementation aspires to conform with ISO/IEC 9899 (C90). However,
due to limitations of the
+ target processor and the nature of its development environment, a
practical implementation must
+ of necessity deviate from the standard.
- Once initialized, system time may be maintained by calling system_tick()
at one
- second intervals.
+
+
+ Section 7.23.2.1 clock()
+ The type clock_t, the macro CLOCKS_PER_SEC, and the function clock() are
not implemented. We
+ consider these items belong to operating system code, or to application
code when no operating
+ system is present.
+
+ Section 7.23.2.3 mktime()
+ The standard specifies that mktime() should return (time_t) -1, if the
time cannot be represented.
+ This implementation always returns a 'best effort' representation.
+
+ Section 7.23.2.4 time()
+ The standard specifies that time() should return (time_t) -1, if the time
is not available.
+ Since the application must initialize the time system, this functionality
is not implemented.
+
+ Section 7.23.2.2, difftime()
+ Due to the lack of a 64 bit double, the function difftime() returns a long
integer. In most cases
+ this change will be invisible to the user, handled automatically by the
compiler.
+
+ Section 7.23.1.4 struct tm
+ Per the standard, struct tm->tm_isdst is greater than zero when Daylight
Saving time is in effect.
+ This implementation further specifies that, when positive, the value of
tm_isdst represents
+ the amount time is advanced during Daylight Saving time.
+
+ Section 7.23.3.5 strftime()
+ Only the 'C' locale is supported, therefore the modifiers 'E' and 'O' are
ignored.
+ The 'Z' conversion is also ignored, due to the lack of time zone name.
+
+ In addition to the above departures from the standard, there are some
behaviors which are different
+ from what is often expected, though allowed under the standard.
+
+ There is no 'platform standard' method to obtain the current time, time
zone, or
+ daylight savings 'rules' in the AVR environment. Therefore the application
must initialize
+ the time system with this information. The functions set_zone(),
set_dst(), and
+ set_system_time() are provided for initialization. Once initialized,
system time is maintained by
+ calling the function system_tick() at one second intervals.
+
+ Though not specified in the standard, it is often expected that time_t is
a signed integer
+ representing an offset in seconds from Midnight Jan 1 1970... i.e. 'Unix
time'. This implementation
+ uses an unsigned 32 bit integer offset from Midnight Jan 1 2000. The use
of this 'epoch' helps to
+ simplify the conversion functions, while the 32 bit value allows time to
be properly represented
+ until Tue Feb 7 06:28:15 2136 UTC. The macros UNIX_OFFSET and NTP_OFFSET
are defined to assist in
+ converting to and from Unix and NTP time stamps.
+
+ Unlike desktop counterparts, it is impractical to implement or maintain
the 'zoneinfo' database.
+ Therefore no attempt is made to account for time zone, daylight saving, or
leap seconds in past dates.
+ All calculations are made according to the currently configured time zone
and daylight saving 'rule'.
+
+ In addition to C standard functions, re-entrant versions of ctime(),
asctime(), gmtime() and
+ localtime() are provided which, in addition to being re-entrant, have the
property of claiming
+ less permanent storage in RAM. An additional time conversion, isotime()
and its re-entrant version,
+ uses far less storage than either ctime() or asctime().
+
+ Along with the usual smattering of utility functions, such as
is_leap_year(), this library includes
+ a set of functions related the sun and moon, as well as sidereal time
functions.
*/
#ifndef TIME_H
@@ -59,7 +111,7 @@
/**
time_t represents seconds elapsed from Midnight, Jan 1 2000 UTC (the
Y2K 'epoch').
- Its range allows time to be handled properly up to Tue Feb 7 06:28:15
2136.
+ Its range allows this implementation to represent time up to Tue Feb 7
06:28:15 2136 UTC.
*/
typedef uint32_t time_t;
@@ -67,7 +119,7 @@
The time function returns the systems current time stamp.
If timer is not a null pointer, the return value is also assigned to the
object it points to.
*/
- time_t time(time_t *);
+ time_t time(time_t *timer);
/**
The difftime function returns the difference between two binary time
stamps,
@@ -77,62 +129,67 @@
/**
- The tm structure contains a representation of time 'broken down' into
its components.
+ The tm structure contains a representation of time 'broken down' into
components of the
+ Gregorian calendar.
+
The normal ranges of the elements are..
\code
- tm_sec seconds after the minute - [0, 60]
- tm_min minutes after the hour - [0, 59]
- tm_hour hours since midnight - [0, 23]
- tm_mday day of the month - [1, 31]
- tm_wday days since Sunday - [0, 6]
- tm_mon months since January - [0, 11]
+ tm_sec seconds after the minute - [ 0 to 59 ]
+ tm_min minutes after the hour - [ 0 to 59 ]
+ tm_hour hours since midnight - [ 0 to 23 ]
+ tm_mday day of the month - [ 1 to 31 ]
+ tm_wday days since Sunday - [ 0 to 6 ]
+ tm_mon months since January - [ 0 to 11 ]
tm_year years since 1900
- tm_yday days since January 1 - [0, 365]
- tm_isdst Daylight Saving Time flag
+ tm_yday days since January 1 - [ 0 to 365 ]
+ tm_isdst Daylight Saving Time flag *
\endcode
- The value of tm_isdst is zero if Daylight Saving Time is not in effect,
- negative if the information is not available.
- If Daylight Saving Time is in effect, the value represents the number
of
+ *The value of tm_isdst is zero if Daylight Saving Time is not in
effect, and is negative if
+ the information is not available.
+
+ When Daylight Saving Time is in effect, the value represents the
number of
seconds the clock is advanced.
+ See the set_dst() function for more information about Daylight Saving.
+
*/
struct tm {
- int8_t tm_sec; /* seconds after the minute - [0, 60] */
- int8_t tm_min; /* minutes after the hour - [0, 59] */
- int8_t tm_hour; /* hours since midnight - [0,
- * 23] */
- int8_t tm_mday; /* day of the month - [1, 31]
*/
- int8_t tm_wday; /* days since Sunday - [0, 6]
*/
- int8_t tm_mon; /* months since January - [0, 11] */
- int16_t tm_year; /* years since 1900
*/
- int16_t tm_yday; /* days since January 1 - [0,
- * 365] */
- int16_t tm_isdst; /* Daylight Saving Time flag
*/
+ int8_t tm_sec;
+ int8_t tm_min;
+ int8_t tm_hour;
+ int8_t tm_mday;
+ int8_t tm_wday;
+ int8_t tm_mon;
+ int16_t tm_year;
+ int16_t tm_yday;
+ int16_t tm_isdst;
};
/**
- This function 'compiles' broken-down time, returning a time stamp.
+ This function 'compiles' the elements of a broken-down time structure,
returning a binary time stamp.
The elements of timeptr are interpreted as representing Local Time.
The original values of the tm_wday and tm_yday elements of the structure
are ignored,
- and the original values of the other elements are not restricted.
+ and the original values of the other elements are not restricted to the
ranges stated for struct tm.
- On successful completion, the values of all elements of the structure are
set to their appropriate ranges.
+ On successful completion, the values of all elements of timeptr are set to
the appropriate range.
*/
time_t mktime(struct tm * timeptr);
/**
- This function 'compiles' broken-down time, returning a time stamp.
+ This function 'compiles' the elements of a broken-down time structure,
returning a binary time stamp.
The elements of timeptr are interpreted as representing UTC.
The original values of the tm_wday and tm_yday elements of the structure
are ignored,
- and the original values of the other elements are not restricted.
+ and the original values of the other elements are not restricted to the
ranges stated for struct tm.
+
+ Unlike mktime(), this function DOES NOT modify the elements of timeptr.
*/
- time_t mk_gmtime(struct tm * timeptr);
+ time_t mk_gmtime(const struct tm * timeptr);
/**
The gmtime function converts the time stamp pointed to by timer into
broken-down time,
@@ -182,21 +239,19 @@
The isotime function constructs an ascii string in the form
\code2013-03-23 01:03:52\endcode
*/
- char *isotime(struct tm * tmptr);
+ char *isotime(const struct tm * tmptr);
/**
Re entrant version of isotime()
*/
- void isotime_r(struct tm *, char *);
+ void isotime_r(const struct tm *, char *);
/**
A complete description of strftime() is beyond the pale of this document.
Refer to ISO/IEC document 9899 for details.
- This implementation handles all conversions specified by the standard,
with the exception of g, G, V, and Z.
- Conversions not implemented are replaced in the output text with the
character '?'
-
- All conversions are made using the 'C Locale', ignoring the E or O
modifiers.
+ All conversions are made using the 'C Locale', ignoring the E or O
modifiers. Due to the lack of
+ a time zone 'name', the 'Z' conversion is also ignored.
*/
size_t strftime(char *s, size_t maxsize, const char *format,
const struct tm * timeptr);
@@ -245,7 +300,7 @@
From a UNIX time stamp:
\code
- set_system_time(ntp_timestamp - UNIX_OFFSET);
+ set_system_time(unix_timestamp - UNIX_OFFSET);
\endcode
*/
@@ -260,12 +315,13 @@
all the cpu registers.
Such an ISR may resemble the following example...
-
+ \code
ISR(RTC_OVF_vect, ISR_NAKED)
{
system_tick();
reti();
}
+ \endcode
*/
void system_tick(void);
@@ -311,12 +367,21 @@
uint8_t month_length(int16_t year, uint8_t month);
/**
- Return the calendar week of year, where the first week is considered
to begin on the
+ Return the calendar week of year, where week 1 is considered to begin
on the
day of week specified by 'start'. The returned value may range from
zero to 52.
*/
uint8_t week_of_year(const struct tm * timeptr, uint8_t start);
/**
+ Return the ISO 8601 week of year. Returned values are...
+
+ 0 : The final week of the previous year.
+ 1 ... 53 : The week number in the current year.
+ 54 : The first week of the following year.
+ */
+ uint8_t iso_week(const struct tm * timeptr, uint8_t start);
+
+ /**
Return the calendar week of month, where the first week is considered
to begin on the
day of week specified by 'start'. The returned value may range from
zero to 5.
*/
@@ -325,7 +390,7 @@
/**
Convert a Y2K time stamp into a FAT file system time stamp.
*/
- uint32_t fatfs_time(struct tm * timeptr);
+ uint32_t fatfs_time(const struct tm * timeptr);
/** One hour, expressed in seconds */
#define ONE_HOUR 3600
@@ -379,42 +444,42 @@
Computes the difference between apparent solar time and mean solar
time.
The returned value is in seconds.
*/
- int16_t equation_of_time(time_t * timer);
+ int16_t equation_of_time(const time_t * timer);
/**
Computes the amount of time the sun is above the horizon, at the
location of the observer.
- NOTE: At observer locations inside the polar circles, this value can
be zero during the winter,
+ NOTE: At observer locations inside a polar circle, this value can be
zero during the winter,
and can exceed ONE_DAY during the summer.
The returned value is in seconds.
*/
- int32_t daylight_seconds(time_t * timer);
+ int32_t daylight_seconds(const time_t * timer);
/**
Computes the time of solar noon, at the location of the observer.
*/
- time_t solar_noon(time_t * timer);
+ time_t solar_noon(const time_t * timer);
/**
Return the time of sunrise, at the location of the observer. See the
note about daylight_seconds().
*/
- time_t sun_rise(time_t * timer);
+ time_t sun_rise(const time_t * timer);
/**
Return the time of sunset, at the location of the observer. See the
note about daylight_seconds().
*/
- time_t sun_set(time_t * timer);
+ time_t sun_set(const time_t * timer);
/** Returns the declination of the sun in radians. */
- double solar_declination(time_t * timer);
+ double solar_declination(const time_t * timer);
/**
Returns an approximation to the phase of the moon.
The sign of the returned value indicates a waning or waxing phase.
The magnitude of the returned value indicates the percentage
illumination.
*/
- int8_t moon_phase(time_t * timer);
+ int8_t moon_phase(const time_t * timer);
/**
Returns Greenwich Mean Sidereal Time, as seconds into the sidereal day.
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [avr-libc-commit] [2366] Updated time.h for new function iso_weeknum(), and made several parameters const.,
Mike Rice <=