CDate

Declared in: CDate.h

Library: Chronology.so

[method summary]

This class provides a huge amount of functions, many overloaded operators, that help greatly in dealing with dates and ensuring, that they are valid (and not "32 February"). Currently it works back until 1.1.1600 and is Y2K aware.

Unlike in the CTime class, not all functions leave the object with a valid value. This means that the date in your object may be invalid. If you're not sure, call IsValid() and/or NextValidDate() or PrevValidDate() to correct it. To make life easier, functions that can cause the date to be incorrect either due to bad user input, or calculation errors, are marked with *.


Constructor and Destructor


CDate()

      CDate()
      CDate(int32 days_since_1600)
      CDate(int32 day, int32 month, int32 year)*
      CDate(const CDate &date)*

These put up an instance of CDate.

The first constructor initialises the object with the current date.

days_since_1600 are the days since 1.1.1600 :-). You can get the number of days since 1600 with Since1600(). The resulting object contains a valid date.

day, month and year let you specify a date directly.

The last constructor initialises the object with the date from another CDate object.


~CDate()

The constructor is currently only the default constructor.


Member Functions


Day(int32), Month(int32), Year(int32)

      int32 Day(int32 day)*
      int32 Month(int32 month)*
      int32 Year(int32 year)*

Those put the day, month or year to the object and return the value.


Day(), Month(), Year()

      int32 Day()
      int32 Month()
      int32 Year()

Those functions simply return the current day, month or year.


DayNumber()

      int32 DayNumber()

Returns the number of days since the first January of the current year.


Weekday()

      int32 Weekday()

With this function you can get the weekday. A value between 0 and 6 is returned, where 0 means the current day was a sunday, 0 = Monday, and so on until 6 = Saturday.


PrevWeekday(), NextWeekday()

      CDate &NextWeekday( int16 weekday, int16 keepdate = 0 )
      CDate &PrevWeekday( int16 weekday, int16 keepdate = 0 )

These functions set the current date to the next or previous requested weekday. So For example you can calculate the next Sunday. weekday is a value between 0 and 6, starting with 0 as Sunday.

keepdate gives you the possibility to decide if you want the result be at least 1 day after/before the current date or not. If you set keepdate to 1, then the result may be the same date, if the current date was the requested weekday. If you set it to zero, the date would be a date before/after the current date in any case, no matter if the current date represents the requested weekday or not.

The result is a reference to the object.


Since1600()

      int32 Since1600()

Returns the number of days since 1.1.1600. This can be used to construct a new object, and as it's only an int32, it can easily be appended to BMessages and be posted to other apps.

As you might know, date calculations are often be done in Julian Calendar format, as it's very easy to handle (it's the number of days since 1.1.-4713). The Julian() function exists, but is currently private, as it returns wrong values for dates before the change to the Gregorian Calendar format (some October after 1500 I think). Due to this fact, the whole class currently onlycan Validate() dates after 1600. This might change in future, but only if there are many people who need dates before 1600.

Until then you can use Since1600() to do fast calculations with dates and times.


Easter()

      CDate &Easter()

This function sets the date to the EasterSunday of the current year and returns a reference to itself.

The Eastersunday is important to calculate many holidays. In future there will be functions like const char *HolidayName() to get the name of the holiday, if it's a holiday, or NULL if it's only a normal day. This is planned to be country-specific, so the user will have the choice which days are holidays, and how they are to be calculated. As this is already planned, you should not have to worry about making your own functions that do that kind of stuff.

It could be possible, that this function returns wrong results for years after 2040. I currently don't know this, but if it's true and I find a way out, this will of course be changed.


IsValidDay(), IsValidMonth(), IsValidYear(), IsValid()

      int16 IsValidDay()
      int16 IsValidMonth()
      int16 IsValidYear()
      int16 IsValid()

These functions let you test if a part of the date (or the whole date itself) is valid or invalid.

IsValidDay() returns false, if the day is lower than 1 or higher than the last day of the current month, else it returns true.

IsValidMonth() returns false if month is lower than 1 or higher than 12, else it returns true.

IsValidYear() returns false if the year is before 1600, else it returns true. If people want support for dates before 1600, this will hopefully change.

IsValid() returns false if one of the above functions returnes false. Thus it's just a shortcut to call all of the above functions. It should be the only IsValid() function you will ever need, but the others are provided. Just in case.

You can call these functions if you don't know if a CDate object contains a valid date, e.g. you initialised the object with data from the user, or you called a function that may leave the object with an invalid date.


PrevValidDate(), NextValidDate()

      void PrevValidDate()
      void NextValidDate()

These functions set the date to the next or previous valid date if the current one is invalid.


AddMonths()

      void AddMonths(int32 num, int16 prevnext = 0)

This function lets you add months to a date and ensures, that the result is still correct.

num is the number of months you want to add to the date. It can also be negative, if you want to subtract some months. If the month will be higher than 12 or lower than 1, the years are adjusted accordingly.

prevnext determines if PrevValidDate() or NextValiddate() will be called after adding the months. This is necessary, because if you add 1 month to January, and it was the 30th January, the date would be invalid. If you set prevnext to 0, PrevValidDate() will be called, else NextValidDate().


Overloaded Operators


= (assignment)*

Assigns a date to another.


+=, + (addition)

This add days to the date. Normally this is an int32, but if you use the operator +=, it can also be a CTime object. In this case, CTime.Day() is added.

It is not possible to add two date. This would also make no sense.


-=, - (subtraction)

Exactly like the additions, just it subtracts days from a date.


- (subtraction of two dates)

You can subtract two dates from each other to calculate the number of days between them.


==, != (equality and inequality)

Those operators let you test if two dates are equal or not.


>=, > (bigger than)

Use this to test if a date is after another (or the same).


<=, < (lesser than)

Tests if a date is before another (or the same).


! (leapyear)

This returns 1, if the stored year is a leapyear or 0, if it's not a leapyear.


Static Variables


const char *weekdays[], *weekdays2[], *weekdays3[]

This contains all names for the weekdays in full length (weekdays), two letter abbreviation, (weekdays2) and three letter abbreviations (weekdays3).

Notes:
In future, the strings will be localised to fit the users country. To stay compatible, you should create at least one instance of CDate before acessing the arrays, because if you don't, they will contain an empty string before the first instance is created.


const char *months[], *months3[]

Same as the weekdays arrays, just with months.

Notes:
Same as for weekdays.






The Cronology Library, in lovely HTML, for BeOS Release 4.

Copyright © 1999 Michael Praschl. All rights reserved.

Last modified: 18. Feb 1999