PowerTime Object: Managing Dates, Times, and Winning Numbers

You hit the LOTTO. Big Time. Millions waiting for you. But there's just one problem. You waited months to check your ticket... Is it still valid? Could it have expired? So, you check the rules. Lotto tickets are good for 180 days. The drawing was December 29. Today is June 27. You have six months, so there's still a few days.

Good news. Or is it? You just realized that the rules say 180 days, not six months. Some months have 30 days, some have 31. February has 28 days, or is it 29? Exactly when does your 180 days expire? Luckily, you were smart enough to buy one of the new PowerBASIC compilers. PowerBASIC 10.0 or PB/CC 6.0. Both have the brand new PowerTime Class. Date arithmetic just couldn't be any easier.

Where do you start? Well, you'd first create a PowerTime variable named MyTime. Now, what was that drawing date? December 29, 2010. OK, so let's save that date in MyTime:

MyTime.NewDate(2010, 12, 29)

That was easy. The NewDate Method lets you create and save any date by entering the year, month, and day. You could even add a time component (hours, minutes, etc.), but thankfully, that doesn't seem to be part of your current problem. Next, let's add 180 days, and see what we get:

MyTime.AddDays(180)

The AddDays Method adds 180 days to the date stored earlier. Not six months, but precisely 180 days, taking into account all of the variations of each month. So, what's the result? That's the easy part. Just display it in one more line of code.

PRINT MyTime.DateString

Just like that, you have your answer: 6/27/2011

A Closer Look at PowerTime

Here's the entire program described above:

FUNCTION PBMAIN()

  LOCAL MyTime as IPowerTime
  LET MyTime = CLASS "PowerTime"

  MyTime.NewDate(2010, 12, 29)
  MyTime.AddDays(180)
  PRINT MyTime.DateStringLong

END FUNCTION

It's just that simple. If you look carefully, you'll see one small change. The DateStringLong Method displays the date in traditional format instead: "June 27, 2011".

PowerTime objects are powerful and versatile. Each PowerTime object holds one Date/Time value. Each PowerTime object has access to any of the Methods in the PowerTime class. Most of these Methods are used to manipulate the stored Date/Time value... a few of them are also used to manipulate or compare another PowerTime object. You'll find all the options you need for most any Date/Time operation.

There are lots of other uses for PowerTime, as well. Calculate aging on your Accounts Receivable or Accounts Payable. Find out just how many hours it's been since you were married (delightful hours, that is). Convert the FILETIME structure in a directory entry to a readable Date and Time. Charge rental fees by the hour, week, or month. December 9, 1964. Was it a Tuesday? Was 2000 a leap year? Did that February in 1964 have 28 or 29 days? How are dates formatted in Germany? Which comes first there, the month, the day, or the year? Has your demo been used more than 30 days? How many days or hours has your program been executing? You'll find hundreds of uses for this powerful package.

PowerTime can express any value in one or more of eight components. Usually, it's expressed as a combination, so that mere humans can readily understand it comfortably. It's kind of difficult for us to visualize 2,437,814 seconds. Just how long is that, anyway?

Year
Month
Day
Hour
Minute
Second
MilliSecond
Tick (MSec/1000)

The first PowerTime need is to store a value. Just as in the above example, you can use the NewDate method to store a specific date by year, month, and day. Likewise, NewTime lets you add a specific time of day to it by hour, minute, second, etc. MyTime.Now stores the precise local Date/Time at this moment, while MyTime.NowUTC stores it in Coordinated Universal Time (GMT).

There's a complete set of methods for Date/Time arithmetic. You can add four hours to the stored date with MyTime.AddHours(4). AddYears, AddDays, AddSeconds, and more, work in the same fashion. What if you need to subtract a Date/Time? Just use an expression with a negative value.

Can you compare two PowerTime objects? Absolutely. The DateDiff method tells you the difference in whole years, months, and days, regardless of the days in the months measured. The TimeDiff method tells you the exact difference in days down to ticks. Measure the difference in days through ticks, or in any combination.

There are separate methods to retrieve any component of the stored value. Get just the year, the hour, the minute, or any other. You can get or set the stored value as a Windows FileTime structure. You can retrieve the month name or the day-of-week name. Display the time in 12-hour or 24-hour format. Display the date with full month name, or all numeric. This is one very special package.