Category : C Source Code
Archive   : C-DATES.ZIP
Filename : C_DATES.DOC

- Hi there -

Finally, there is a quick and easy way to manipulate dates in
the "C" programming language; that is what this package is all
about.

The "C" programming language is, in this authors humble
opinion, the best programming language ever invented by man. Among
its weaker points, however, is its inability ( at least in its
most basic form ) to handle any sort of date variable. This is an
important capability in most business applications, which still
constitutes the majority of the programming effort in America, and
yet there hasn't been ( until now ) an acceptable way of dealing
with this problem. This has always struck me as somewhat of an
injustice to the power of "C", so I decided to write a library for
the general public that would "do the trick".

Manipulating dates in an effective manner involves converting
what we normally think of as a "date" into a single number that
represents the number of days since some arbitrary point in time.
For these routines, that arbitrary point in time is simply January
0, year 0000. January 2nd, year 0000, for example, would be
represented as the number 2, January 3rd, year 0000, as the number
3, and so on. Once the conversion is performed, calculating such
things as the day of the week, or the number of days between two
dates, becomes possible.

This numerical representation of a date is called the
"julian" representation, and the proper name of the equivalent
colloquial date, ie: one expressed in terms of the month, day and
year, is called the "gregorian" representation. These names are
worth remembering, as the documentation in this package refers to
all dates as either one or the other.

All of the routines in this library, with the exception of
the actual conversion routines themselves, manipulate only the
julian form of the date, the idea being that to manipulate a date,
the user first converts it to a number, performs the required
calculations, then converts it back to the readable ( gregorian )
form.

There are only nine functions in this library, three of which
are implemented as rather trivial macros. With these nine, it is
hoped that the user can accomplish almost any kind of date
calculation required. The names and a brief description of these
functions are as follows:

compiled functions:
======== =========

gtoj - to convert gregorian dates to julian dates
jtog - to convert julian dates to gregorian dates
dow - to find the numerical day of the week from a julian
date
fulldte - to express a julian date as a verbose gregorian date
daycnt - to compute the days between two dates, with or without
weekends
newdate - to compute a new date by adding or subtracting
weekdays, weekends, or both







macro functions:
===== =========

suncnt - to compute the number of Sundays occurring between two
julian dates
satcnt - to compute the number of Saturdays occurring between
two julian dates
wkend - to find the week-ending date ( ie: the date of the
following Saturday ) for a given julian date

I have not included any of the fancier stuff, such as perhaps
a macro that calculates the date for Thanksgiving for any given
year, for that, I think, is best left up to the user as an
exercise.

For a full description of each of the above compiled
functions, please refer to the source file, "C_dATES.C", where
each particular module's code is prefaced by a collection of C
comment lines containing the associated usage summary.

The macro functions are documented at the end of this
document, in what I have called "Appendix A".

These routines can handle any date, regardless of
chronological magnitude, from January 1st, year 0000 to December
31st, 9999, and the source ( included ) for these routines can be
re-compiled using any ANSI C compiler, on virtually any machine.
The jtog and fulldte functions, however, assume an ASCII based
machine, but the source can easily be modified to employ almost
any type of character set ( with maybe a little forethought... ).

The actual object module library that is included with this
package, "C_dATES.LIB", was created using the Microsoft C
compiler, version 4.0. There is no particular reason for choosing
this particular implementation, other than the fact that it is the
one that I use all the time. ( It is actually quite good )

With this package I have also included two example programs,
written in MSC v 4.0, that employ most of the functions contained
in this library, so that the user can get a feel for some of the
practical applications of these functions. The name of the first
program is "DAYS.EXE", and all it does, really, is compute the
days that exist between the two dates input on the command line.
The second program, called "DATE.EXE", simply returns a new date
that is computed using a start date and adding a number of days of
a specified type. For an more detailed explanation of their
usage, simply type in their respective names with no parameters.

Should you have any questions, comments, suggestions,
contributions, expletives, marriage proposals, or hate mail, I can
be reached at my home address, 2841 Clydedale, apt #345, Dallas,
TX 75220, ( via U.S. mail! ) or alternatively, you can leave a
message for me at one or more of the following ( excellent )
public BBS's:

DOUBLE D (214) 492-8090 1200-N-8-1
SUPERCOMPUTER (214) 270-6755 1200-N-8-1
INSIDE TRACK (214) 422-4772 2400-N-8-1

You will need to know my name; it's James Seed...






A P P E N D I X A
===================

- Macro Function Usage -
====================


suncnt( julian1, julian2 ) - this function returns the number of
Sundays that exist between the two
julian dates input, expressed as a
signed long integer. The input
types are as follows:

julian1 - unsigned long integer
julian date
julian2 - unsigned long integer
julian date

satcnt( julian1, julian2 ) - this function returns the number of
Saturdays that exist between the
two julian dates input, expressed
as a signed long integer. The
input types are as follows:

julian1 - unsigned long integer
julian date
julian2 - unsigned long integer
julian date

wkend( julian ) - this function finds the week-ending date,
expressed as an unsigned long integer julian
Saturday, that represents the week that
includes the unsigned long julian date input.



*** IMPORTANT NOTE ***

The author assumes no responsibility for any loss or damage
arising out of the use, misuse, or inability to use this product.