/**
 * Gets the number of days in the year
 * 
 * @param date	The date to check
 * 
 * @return		The total number of days in the year
 */
public static function daysInYear( date:Date ):Number {
	return DateUtils.dateDiff(
				DateUtils.DAY_OF_MONTH,
				new Date( date.fullYear, DateUtils.monthAsNumber( DateUtils.JANUARY ), 1 ),
				DateUtils.dateAdd( DateUtils.YEAR, 1, new Date( date.fullYear, DateUtils.monthAsNumber( DateUtils.JANUARY ), 1 ) ) );
}

Very straight forward method. This calculates how many days are in the year that is passed in. Essentially I’m doing a date difference between the first of January of the requested year, and the first of January of the next year. The method returns the number of days for that year.

So in order to use this method, first import the package

import com.flexoop.utilities.dateutils.DateUtils;

and then:

private var _total:Number = DateUtils.daysInYear( new Date( 2009, DateUtils.monthAsNumber( DateUtils.JANUARY ) ) );

This would return 365.

/**
 * Determines whether the year is a leap year or not
 * 
 * @param date	The date to check
 * 
 * @return		<code>true</code> means it is a leap year, <code>false</code> means it is not a leap year.
 */
public static function isLeapYear( date:Date ):Boolean {
	return daysInYear( date ) > 365;
}

Another very straight forward method. It accepts a date and determines if the year is a leap year.

So in order to use this method, first import the package

import com.flexoop.utilities.dateutils.DateUtils;

and then:

private var _isLeapYear:Boolean = DateUtils.isLeapYear( new Date( 2009, DateUtils.monthAsNumber( DateUtils.JANUARY ) ) );

This would return false as 2009 is not a leap year.

All methods in this series are describing code in the FlexDateUtils package I put on Google code.

I hope that this wasn’t too dry a topic for everyone that followed along. I just get excited when I’m describing code I have written and as much as my wife looks like she’s interested in what I’m saying, I see her eyes glazing over every now and then , and I hope that others find new code as interesting as I do. I wanted to make sure I got descriptions of everything in the DateUtils library to make it easier for anyone trying to figure out a use for it. I think I’ll leave the library descriptions alone and go back to posting solutions to problems I’ve faced at work/home or interesting tidbits I’ve come across. Perhaps I can revisit any new items I add in the future.

/**
 * Gets the total number of dayOfWeek in the month
 * 
 * @param strDayOfWeek	The day of week to check
 * @param date			The date containing the month and year
 * 
 * @return				The number of <code>strDayOfWeek</code> in that month and year
 */
public static function totalDayOfWeekInMonth( strDayOfWeek:String, date:Date ):Number {
	var _startDate:Date = DateUtils.dayOfWeekIterationOfMonth( 1, strDayOfWeek, date );
	var _totalDays:Number = DateUtils.dateDiff( DateUtils.DAY_OF_MONTH, _startDate, new Date( date.fullYear, date.month, DateUtils.daysInMonth( date ) ) );
	// have to add 1 because have to include first day that is found i.e. if wed is on 2nd of 31 day month, would total 5, of if wed on 6th, would total 4
	return Math.floor( _totalDays / 7 ) + 1;
}

This method calculates the total number of a specific day of the week for a specified month. The method accepts dayOfWeek as a string (use one the constants to make this easier) and a date containing the month and year requested. It then returns a number with the total number of that day of the week for that month.

So in order to use this method, first import the package

import com.flexoop.utilities.dateutils.DateUtils;

and then:

private var _total:Number = DateUtils.totalDayOfWeekInMonth( DateUtils.Wednesday, new Date( 2009, DateUtils.monthAsNumber( JANUARY ) ) );

which would return 4, as there are 4 Wednesdays in January 2009

/**
 * Formats a month to the numeric version of the month
 * 
 * @param strMonth	The month to convert
 * 
 * @return			A formatted month or -1 if month not found
 */
public static function monthAsNumber( strMonth:String ):Number {
	return ( objMonth[ strMonth ] >= 0 ) ? objMonth[ strMonth ] : -1;
}

This method takes a string version of the month, and then converts it to the numeric version of that month. I use objMonth[ strMonth ] >= 0 rather than just objMonth[ strMonth ], as 0 is also “false” and was returning -1 instead of 0 (for January). This is quite a useful method for me, and, even though it is more typing, I feel it makes more sense to someone skimming/reading the code, which prevents headaches in the future. I even found one example I gave that was using 1, when I actually meant 0, for January, so I altered the example to use this method to remove all confusion.

All methods in this series are describing code in the FlexDateUtils package I put on Google code.

/**
 * Gets the Xth day of the month.
 * e.g. get the 3rd Wednesday of the month
 * 
 * @param iteration		The iteration of the month to get e.g. 4th or Last
 * @param strDayOfWeek	The day of the week as a string
 * @param date			The date containing the month and year
 * 
 * @return				The date of the xth dayOfWeek of the month 
 */
public static function dayOfWeekIterationOfMonth( iteration:Number, strDayOfWeek:String, date:Date ):Date {
	// get the numeric day of the week for the requested day
	var _dayOfWeek:Number = dayOfWeekAsNumber( strDayOfWeek );
	// get the date for the first of the month
	var _firstOfMonth:Date = new Date( date.fullYear, date.month, 1 );
	// calculate how many days to add to get to the requested day from the first of the month
	var _daysToAdd:Number = _dayOfWeek - DateUtils.dayOfWeek( _firstOfMonth );
	// if dayOfWeek is before the first of the month, get the dayOfWeek for the following week
	if ( _daysToAdd < 0 ) {
		_daysToAdd += 7;
	}
	// set the date to the first day of the week for the requested date
	var _firstDayOfWeekOfMonth:Date = DateUtils.dateAdd( DateUtils.DAY_OF_MONTH, _daysToAdd, _firstOfMonth );
	// return the date if iteration is 1
	if ( iteration == 1 ) {
		return _firstDayOfWeekOfMonth;
	} else {
		// if requesting an iteration that is more than is in that month or requesting the last day of week of month
		// return last date for that day of week of month
		if ( ( DateUtils.totalDayOfWeekInMonth( strDayOfWeek, date ) < iteration ) || ( iteration == DateUtils.LAST ) ) {
			iteration = DateUtils.totalDayOfWeekInMonth( strDayOfWeek, date );
		}
		// subtract 1 as it starts from the first dayOfWeek of month
		return DateUtils.dateAdd( DateUtils.WEEK, iteration - 1, _firstDayOfWeekOfMonth );
	}
}

The name is a little cryptic, but it returns the total number of a day of the week in a specified month. I heavily commented this method in order to be less confusing for anyone who might be trying to decipher what is going on, so I won’t go over what is being done within the method. The method accepts 3 parameters: iteration which represents which dayofweek for a month to get, 1, 2, 3, 4, 5, or LAST (if using the constant), the string representation of the day of the week, and the date containing the month and year to query. It returns the date for the specified iteration.

To implement, first import the package:

import com.flexoop.utilities.dateutils.DateUtils;

then:

private var _dateOfIteration:Date = DateUtils.dayOfWeekIterationOfMonth( 3, DateUtils.TUESDAY, new Date( 2008, DateUtils.monthAsNumber( DateUtils.MAY ) ) );

This will return May 20th, 2008, the 3rd Tuesday in May.

All methods in this series are describing code in the FlexDateUtils package I put on Google code.

/**
 * Gets the days in the month
 * 
 * @param date	The date to check
 * 
 * @return		The number of days in the month
 */
public static function daysInMonth( date:Date ):Number {
	// get the first day of the next month
	var _localDate:Date = new Date( date.fullYear, DateUtils.dateAdd( DateUtils.MONTH, 1, date ).month, 1 );
	// subtract 1 day to get the last day of the requested month
	return DateUtils.dateAdd( DateUtils.DAY_OF_MONTH, -1, _localDate ).date;
}

This method calculates how many days are in the month for the date passed in to the method. It takes the date parameter and sets a temporary date to the first day of the next month. Then it subtracts 1 day from that date to get the last day of the requested month.

So in order to use this method, first import the package

import com.flexoop.utilities.dateutils.DateUtils;

and then:

private var _total:Number = DateUtils.daysInMonth( new Date( 2009, DateUtils.monthAsNumber( DateUtils.JANUARY ), 1 ) );

This would return 31 to _total.

/**
 * Formats a date to the string version of the day of the week
 * 
 * @param date	The date to format
 * 
 * @return		A formatted day of week
 */
public static function dayOfWeekAsString( date:Date ):String {
	return DateUtils.dateFormat( date, "EEEE" );
}

This method returns a formatted date for the day of week. Nothing crazy here.

So in order to use this method, first import the package

import com.flexoop.utilities.dateutils.DateUtils;

and then:

private var _dow:String = DateUtils.dayOfWeekAsString( new Date( 2009, DateUtils.monthAsNumber( DateUtils.JANUARY ), 1 ) );

And this would return, Thursday

All methods in this series are describing code in the FlexDateUtils package I put on Google code.

/**
 * Gets the ordinal value or day of the year
 *
 * @param date	The date for which to get the day of the year
 * 
 * @return		A number representing the day of the year, 1 to 365 or 366 for a leap year
 */
public static function dayOfYear( date:Date ):Number {
	// add one as it has to include first of year
	return DateUtils.dateDiff( DateUtils.DAY_OF_MONTH, new Date( date.fullYear, DateUtils.monthAsNumber( DateUtils.JANUARY ), 1 ), date ) + 1;
}

This method takes a date and calculates the ordinal day of the year that that date represents, from 1 to 365 or 366 in a leap year. This just uses the dateDiff method to subtract the number of days between the 1st of the year, and the date parameter (and adds one to include the first day of the year).

To implement, first import the package:

import com.flexoop.utilities.dateutils.DateUtils;

then:

private var _dayOfYear:Number = DateUtils.dayOfYear( new Date() );

/**
 * Gets the week of the year
 * 
 * @param date	The date for which to get the week of the year
 * 
 * @return		A number representing the week of the year, 1 to 53 ( as there are slightly more than 52 weeks of days in a year)
 */
public static function weekOfYear( date:Date ):Number {
	return Math.ceil( DateUtils.dayOfYear( date ) / 7 );
}

This method works very similarly to the dayOfYear method except that it calculates which week of the year the date falls in, and returns a number from 1 to 53.

To implement, first import the package:

import com.flexoop.utilities.dateutils.DateUtils;

then:

private var _weekOfYear:Number = DateUtils.weekOfYear( new Date() );

All methods in this series are describing code in the FlexDateUtils package I put on Google code.

The main issue that cropped up was that to get the year, I was just subtracting the endDate year from the startDate year. However, when you think about this, it is a very inaccurate way of treating year. As year and months can vary in length, I couldn’t just use the Milliseconds contained within it to determine whether a year or month had occurred. I had to just subtract one year or month from another. However, if 2 months fall on separate years, but are not > 1 year apart, it will return 1, even though they could only be a month or so apart. e.g. December 2008 to February 2009 is nowhere near 1 year apart, but subtracting 2008 from 2009, returns 1.

In order to fix this problem, I decided to check the total months that had passed also. I then ran into yet another snag. What if the month was the same, but the day of the month had not passed. e.g. July 16 2007 to July 5 2008 would not be 1 year, although if just using the months and year, it might suggest that it was 1 year apart. To fix this problem, I decided to also check the milliseconds difference between the 2 dates. This now fixes any dates that have different times within them also.

The dateDiff( MONTH ) was having a similar issue so this now fixes that problem also.

I put this fix up on the FlexDateUtils code and also updated the demo so that the issue would be fixed there also.

Make sure to download the latest code and you shouldn’t have any more issues with the dateDiff.

// Date masks
public static const SHORT_DATE_MASK:String	= "MM/DD/YY";
public static const MEDIUM_DATE_MASK:String	= "MMM D, YYYY";
public static const LONG_DATE_MASK:String	= "MMMM D, YYYY";
public static const FULL_DATE_MASK:String	= "EEEE, MMMM D, YYYY";
 
// Time masks
public static const SHORT_TIME_MASK:String	= "L:NN A";
public static const MEDIUM_TIME_MASK:String	= "L:NN:SS A";
// TZD = TimeZoneDesignation = GMT + or - X hours, non-standard, requires a slight hack
public static const LONG_TIME_MASK:String	= MEDIUM_TIME_MASK + " TZD";

These are the constants that can be used to denote the masks to use when calling the date and time formatters. This makes the coder less prone to typing out incorrect values when entering a date. User defined masks can still be passed as parameters, but the predefined masks should cover 99% of everyone’s needs.

/**
 * Formats a time into a certain time format
 * 
 * @param date	The date to format
 * @param mask	How the date should be formatted
 * 
 * @return		A formatted time
 */
public static function timeFormat( date:Date, mask:String=DateUtils.SHORT_TIME_MASK ):String {
	return buildDateTime( date, mask, "(A|:|J|H|K|L|N|S|TZD|\\s)+", DateUtils.SHORT_TIME_MASK );
}

This method formats the date to a specified time. The standard output uses the SHORT_TIME_MASK (L:NN A which creates in the format 12:05 am), but can be altered to whatever format the programmer wants. I pass the date to the buildDateTime method (described in a previous post) to build the time, making sure to pass what constitutes a valid mask in the regular expression pattern. The default is the SHORT_TIME_MASK again.

To use this method, import the package:

import com.flexoop.utilities.dateutils.DateUtils;

then:

private var _formatted:String = DateUtils.timeFormat( new Date() );

This would take the current time and would output it like this: 11:16 pm

/**
 * Formats a date into a certain date format
 * 
 * @param date	The date to format
 * @param mask	How the date should be formatted
 * 
 * @return		A formatted date
 */
public static function dateFormat( date:Date, mask:String=DateUtils.SHORT_DATE_MASK ):String {
	return buildDateTime( date, mask, "(Y|M|D|E|\\W)+", DateUtils.SHORT_DATE_MASK );
}

This method formats the date to a specified time. The standard output uses the SHORT_DATE_MASK (MM/DD/YY which creates in the format 12/15/08), but can be altered to whatever format the programmer wants. I pass the date to the buildDateTime method (described in a previous post) to build the date, making sure to pass what constitutes a valid mask in the regular expression pattern. The default is the SHORT_DATE_MASK again.

To use this method, import the package:

import com.flexoop.utilities.dateutils.DateUtils;

then:

private var _formatted:String = DateUtils.dateFormat( new Date() );

This would take the current date and would output it like this: 12/15/08

/**
 * Formats a date into a certain date/time format
 * 
 * @param date	The date to format
 * @param mask	How the date should be formatted
 * 
 * @return		A formatted date
 */
public static function dateTimeFormat( date:Date, mask:String="MM/DD/YYYY L:NN:SS A" ):String {
	return buildDateTime( date, mask, "(Y|M|D|E|A|J|H|K|L|N|S|TZD|\\W)+", DateUtils.SHORT_DATE_MASK + ' ' + DateUtils.SHORT_TIME_MASK );
}

And finally,
This method formats the date to a specified date and time. The standard output uses a combination of the SHORT_DATE_MASK (MM/DD/YY which creates in the format 12/15/08) and the SHORT_TIME_MASK (L:NN A which creates in the format 12:05 am), but can be altered to whatever format the programmer wants. I pass the date to the buildDateTime method (described in a previous post) to build the date and time, making sure to pass what constitutes a valid mask in the regular expression pattern. The default is the SHORT_DATE_MASK and the DateUtils.SHORT_TIME_MASK again.

To use this method, import the package:

import com.flexoop.utilities.dateutils.DateUtils;

then:

private var _formatted:String = DateUtils.dateTimeFormat( new Date() );

This would take the current date and would output it like this: 12/15/08 11:20 pm

Once again, a very useful function that did not get included in the Flex framework for whatever reason, but now can easily be include in anyone’s code.

All methods in this series are describing code in the FlexDateUtils package I put on Google code.

// Internal variable used in date/time formatting
private static var _dateFormatter:DateFormatter;
private static function get dateFormatter():DateFormatter {
	if ( !_dateFormatter ) {
		_dateFormatter = new DateFormatter;
	}
	return _dateFormatter;
}

I use a static getter for a DateFormatter instantiation so that I can use the built in features of the DateFormatter class to format my dates. I figure, why reinvent the wheel, when it has been done so well in Flex already

/**
 * @private
 * 
 * Calculates a timeZoneOffset, and converts it to a string, in standard GMT XX:XX format
 * 
 * @param date	The date on which to calculate the offset
 * 
 * @return		The formatted time zone designation
 */
private static function buildTimeZoneDesignation( date:Date ):String {
	if ( !date ) {
		return "";
	}
	var timeZoneAsString:String = "GMT ";
	// timezoneoffset is the number that needs to be added to the local time to get to GMT, so
	// a positive number would actually be GMT -X hours
	if ( date.getTimezoneOffset() / 60 > 0 && date.getTimezoneOffset() / 60 < 10 ) {
		timeZoneAsString += "-0" + ( date.getTimezoneOffset() / 60 ).toString();
	} else if ( date.getTimezoneOffset() < 0 && date.timezoneOffset / 60 > -10 ) {
		timeZoneAsString += "0" + ( -1 * date.getTimezoneOffset() / 60 ).toString();
	}
	// add zeros to match standard format
	timeZoneAsString += "00";
	return timeZoneAsString;
}

As the description states, this method takes a date and builds the time zone designation in the GMT -XX:00 timezone offset. If date is null, then it returns an empty string.

/**
 * @private
 * 
 * This function will remove any invalid characters from the date/time mask based upon a pattern
 * 
 * @param mask			The string for matching
 * @param pattern		The valid characters for this mask
 * @param defaultValue	The default value to return to the calling page should the mask not match the pattern
 * 
 * @return				Returns a validated <code>mask</code> based upon the original pattern
 */
private static function removeInvalidDateTimeCharacters( mask:String, pattern:String, defaultValue:String ):String {
	// test for invalid date and time characters
	if ( mask.replace( new RegExp( pattern, "ig" ), "" ).length > 0 ) {
		// if user is passing an invalid mask, default to defaultValue
		mask = defaultValue;
	}
	// temporarily replace TZD with lowercase tzd for replacing later
	return mask.replace( new RegExp( "TZD", "i" ), "tzd" );
}

I use this method to remove any bad characters that may have been passed in to the date/time formatters. It takes a mask, a pattern, and a default value. The default value is my fallback in case an invalid characters have been passed in. First I replace all characters based upon the pattern passed to the method. If any characters are left, then it is a bad pattern, and it uses the default value. I then replace TZD and switch it to lowercase so that it can be replaced with the actual time zone designation at a later point (and the dateformatter does not balk at it when it comes across it).

/**
 * @private
 * 
 * Formats a date into a certain date/time format
 * 
 * @param date			The date to format
 * @param mask			The string for matching
 * @param pattern		The valid characters for this mask
 * @param defaultValue	The default value to return to the calling page should the mask not match the pattern
 * 
 * @return		A formatted date
 */
private static function buildDateTime( date:Date, mask:String, pattern:String, defaultValue:String ):String {
	dateFormatter.formatString = removeInvalidDateTimeCharacters( mask, pattern, defaultValue );
 
	return dateFormatter.format( date ).replace( new RegExp( "TZD", "i" ), buildTimeZoneDesignation( date ) );
}

This is where the dateformat “magic” happens The function receives a date, the mask of how to format the date, a pattern that determines which characters are valid characters, and a default value to use should there be any invalid characters.

This sets the formatString of the static dateFormatter and removes any invalid characters. Then it formats the date based upon that formatString, and finally replaces any TZD it finds (which would have been lowercased in the removeInvalidDateTimeCharacters method) with the actual timezone designation, if there was a time zone designation requested in the mask.

Even though none of these methods are available outside of the DateUtils class, I always like to know how things are working under the hood, and hopefully others do too.

All methods in this series are describing code in the FlexDateUtils package I put on Google code.

// Days of week
public static const MONDAY:String	= "monday";
public static const TUESDAY:String	= "tuesday";
public static const WEDNESDAY:String	= "wednesday";
public static const THURSDAY:String	= "thursday";
public static const FRIDAY:String	= "friday";
public static const SATURDAY:String	= "saturday";
public static const SUNDAY:String	= "sunday";
 
// a generic object for holding day of the week values
private static var _objDaysOfWeek:Object = null;
public static function get objDaysOfWeek():Object {
	if ( !_objDaysOfWeek ) {
		_objDaysOfWeek = {};
		_objDaysOfWeek[ DateUtils.SUNDAY ]	= 0;
		_objDaysOfWeek[ DateUtils.MONDAY ]	= 1;
		_objDaysOfWeek[ DateUtils.TUESDAY ]	= 2;
		_objDaysOfWeek[ DateUtils.WEDNESDAY ]	= 3;
		_objDaysOfWeek[ DateUtils.THURSDAY ]	= 4;
		_objDaysOfWeek[ DateUtils.FRIDAY ]	= 5;
		_objDaysOfWeek[ DateUtils.SATURDAY ]	= 6;
	}
	return _objDaysOfWeek;
}
 
/**
 * Formats a date to the numeric version of the day of the week
 * 
 * @param strDayOfWeek	The day of week to convert
 * 
 * @return		A formatted day of week or -1 if day not found
 */
public static function dayOfWeekAsNumber( strDayOfWeek:String ):Number {
	return ( objDaysOfWeek[ strDayOfWeek ] >= 0 ) ? objDaysOfWeek[ strDayOfWeek ] : -1;
}

This method will actually take a string that represents the day of the week, and will convert that to the numeric representation in Flex for that day of the week, ranging from 0-6.

I actually created a generic object that would hold all of the values for the days of the week to make my life easier when trying to return and reference values in it. I also created constants for all of the days of the week, so anyone calling any method that needs a string of the day of the week, can simply reference the constants, instead of trying to guess what I called the days of the week.

The method tries to reference whatever string is passed to it in the generic dayOfWeek object, and will return the value it finds, or if the object does not contain that string, it will return -1. As long as you use the constants, the -1 should never be returned.

So in order to use this method, first import the package

import com.flexoop.utilities.dateutils.DateUtils;

and then:

private var _dow:Number = DateUtils.dayOfWeekAsNumber( DateUtils.MONDAY );

_dow would now be 1, as _objDaysOfWeek[ DateUtils.MONDAY ] is equal to 1. I tend to use this method whenever I’m passing a day of the week value to one of my other methods, just so I don’t confuse the actual day value ( i.e. using 1-7 instead of 0-6 ).

All methods in this series are describing code in the FlexDateUtils package I put on Google code.

/**
 * Determines whether a value is actually a valid date
 * 
 * @param value	The date value
 * 
 * @return		<code>true</code> means this is a valid date, <code>false</code> means it is not a valid date
 */
public static function isDate( value:String ):Boolean {
	return Date.parse( value ) > 0;
}

My isDate method will check whether the value that is passed to it is actually a date or not. I was surprised to find this wasn’t included somewhere in the Flex framework, but quite happy at how easy it was to create it. All that needs to be done is to check whether the date can be parsed by the Date class. If yes, it’s a date, if not, it is not a date.

To implement, first import the package:

import com.flexoop.utilities.dateutils.DateUtils;

then:

private var _validDate:Boolean = DateUtils.isDate( 'this is not a date' );

Straight forward and simple

/**
 * Converts the month to a Flex month
 * 
 * @param date	The human readable month
 * 
 * @return		The Flex converted month or 0 aka January
 */
public static function toFlexMonth( localMonth:Number ):Number {
	return ( localMonth > 0 && localMonth < 13 ) ? localMonth - 1 : 0;
}

This method is another one that I created to try to make my life easier when thinking about months, so I didn’t get confused about using 0-11 instead of 1-12. I actually use another method I created instead of this one now, but I thought I should leave it in as it may be useful to someone, even if I don’t use it that much.

This accepts a month, 1-12, and returns the flex value for that month, 0-11.

Once again, to use, import the package:

import com.flexoop.utilities.dateutils.DateUtils;

and then:

private var _newMonth:Number = DateUtils.toFlexMonth( 6 );

And this would return 5. Nothing awe inspiring in that method, but perhaps useful to someone.

All methods in this series are describing code in the FlexDateUtils package I put on Google code.