PktCDateLib
[ Functions ]
[ Using PktCDateLib ]
[ Additional Information ]
[ History ]
PktCDateLib is a native library for
PocketC for Palm
that is free to use for PocketC users. The program is
not in the public domain however.
Introduction
This module gives your PocketC program the ability to:
- Use the PalmOS Date Selector
- Compute the difference between two dates and return an answer in days
- Compute a new date based on a date and difference in days.
Functions added to PocketC by PktCDateLib
(in alphabetical order)
Several functions get added to PocketC when you use
PktCDateLib. Here is a description of each function, the parameters
the functions take, and values returned.
Several functions are demonstrated in the Sample
Source below.
- CalcDate - int CalcDate(int date, int days)
CalcDate takes two integers, one in date format YYYYMMDD and a number
of days (positive for later dates, negative for earlier dates) and
returns a newly calculated date in YYYYMMDD format. This function
correctly handles dates that go across leap years.
Like DeltaDays(), this function only works for dates in the range
supported by PalmOS and calculated dates or dates used outside of the
valid ranges will lead to unexpected results. Generally you should do
appropriate range checking before using these functions which can be
totally implemented using the functions provided by PktCDateLib.
- DeltaDays - int DeltaDays(int date1, int date2)
DeltaDays takes two dates passed as integers in YYYYMMDD format and
returns the difference between the dates in days. If date2 is later than
date1, the answer returned will be negative indicating that date1 was in
the past.
This function is limited to the valid dates supported by
PalmOS which are 1 January 1904 until 12 December 2031. Dates used
outside of this range will cause unexpected results.
- ExtractYMD - int ExtractYMD(int date, int component)
ExtractYMD allows easy access to the year, month
and day components of a date stored in an integer in YYYYMMDD format.
The extracted component is returned as an integer.
- Use a component value of 0 to extract the year
- Use a component value of 1 to extract the month
- Use a component value of 2 to extract the day
- MakeYMD - int MakeYMD(int year, int month, int day)
MakeYMD takes three integers that represent year, month and day and
creates a composite integer in YYYYMMDD format suitable for use with
other functions that require a date in this format, such as SelectFromDate.
For example: puts(MakeYMD(1998,3,17)); prints the integer 19980317 on the console output screen.
- PCDLVersion - int PCDLVersion()
PCDLVersion returns the version of PktCDateLib that is installed on the Palm device. This can be used by your program to make sure that features you want to use in PktCDateLib are available. See the release history below to see what features were added with which version.
- SelectFromDate - int SelectFromDate(int date)
SelectFromDate takes an integer in YYYYMMDD format and presets the
PalmOS pop up date selector to that value. An integer is returned in
YYYYMMDD format if a valid date is selected or -1 is returned if the Cancel button is pressed.
- SelectFromToday - int SelectFromToday(int parameter)
SelectFromToday takes a single integer parameter, with a value of
0 (zero) and then pops up the PalmOS Date Selector with the current
date selected. The user can then select a date or cancel. The answer is
returned as an integer having the value of -1 if Cancel was
pressed, or as an integer in YYYYMMDD format.
Additional parameters are under consideration.
Using PktCDateLib in your programs
Download PktCDateLib.prc and install it
on your Palm device using the Palm Intall tool. Then HotSync your Palm
device.
If you're using a version of PktCDateLib prior to version 1.1.1, please remove the old version BEFORE installing the new version.
To use PktCDateLib in your PocketC program, you need to include
the compiler directive that tells the PocketC compiler to link in the
library when compiling and executing your code.
To do that, simply include the line: library "PktCDateLib" in
your program before using any of the functions defined by
PktCDateLib. Keep in mind that you must use the exact case as
specified in the library line above and in the example below.
Example Source Code and Output
|
// PktCDateTest
library "PktCDateLib"
main() {
int adate;
adate = SelectFromToday(0);
puts("Date = ");
puts(adate);
puts('\n');
puts("Year = ");
puts(ExtractYMD(adate,0));
puts('\n');
puts("Month = ");
puts(ExtractYMD(adate,1));
puts('\n');
puts("Day = ");
puts(ExtractYMD(adate,2));
puts('\n');
puts("DeltaDays test = ");
puts(DeltaDays(20311231,19040101));
puts('\n');
puts("CalcDate test = ");
puts(CalcDate(19640317,12345));
puts('\n');
}
|
 |
Possible Enhancements
The following "wish list" may be implemented in a future release of PktCDateLib.
- Pass string to PalmOS date selector so that the user can specify
something other than the hard coded "Select Date" string that currently
pops up.
Additional Information
I can't call this a FAQ (frequently asked questions) because no one
has asked these questions frequently, but the answers may still be
useful.
- Why are dates in YYYYMMDD format?
I chose this format because:
- PocketC's int data type has plenty of room to store all the
information about a date, specifically the year, month and day without
having to worry about overflow or underflow conditions on the Palm
device (i.e. dates that are too big or too small to fit in the data
type).
- Dates in this format are easily compared to see which is
earlier, later or the same using the standard comparison operators.
Because of this...
- Dates in this format are easily sorted.
- It's easy to represent negative years by making the entire value negative. Comparisons of negative values is still trivial.
- For year 10000 compliance, the format simply becomes YYYYYMMDD.
For example, consider the comparison of these two dates: 20000101
and 19981231. It is obvious that the first date is later (greater) than
the second date.
However, consider the comparison of dates in MMDDYYYY format:
01012000 and 12311998. Now it is no longer obvious that the first date
is later (greater) than the second date. We can tell by looking at it
that it is later, but a program would have to use a much more complex
process of comparison by extracting the year component and making the
comparions of the years and month-day components separately. However
this format works fine for easy comparions if the year is the same in
both dates. Other problems with this format are it's not as easy to use
it to represent negative years, and to change to 5 digit years requires
a format change--although this probably isn't an issue for most people.
- What is a Palm device?
Any upgraded Pilot 1000, 5000, or any PalmPilot Personal,
Professional, PalmIII, IBM Workpad or other Palm clone that is running
PalmOS 2.0 or later and PocketC.
Release History
- 5 February 2006 Version 1.1.1 - rerelease
- This software has been made available again.
- 15 September 1998 Version 1.1.1
- Function PCLDVersion renamed to PCDLVersion, and now returns the value 111
- The Creator ID (CRID) for this application was wrong. It is now set correctly to PCDL.
- 14 September 1998 Version 1.1.0
- Added PCLDVersion() to allow the user to test what version of the
library they're using. PCLDVersion() returns the integer value 110 for release 1.1.0
- Added MakeYMD() to allow the user to create a composite date based on passing year, month and day components.
- Added SelectFromDate() to allow specifying which date the PalmOS pop up date selector should start with.
- 14 September 1998 Version 1.0.0
|
|
