/**
 * Trims all white space characters from both ends of a text string.
 * <p>
 * This function first attempts to caste whatever argument is given to a string before performing the trim.
 * If the toSting() fails, the function returns <code>false</code>.
 * 
 * @param string text
 * @returns string
 */
function trim(text) {
    try {
        return text.toString().replace(/^\s*(.*)$/, "$1").replace(/(.*?)\s*$/, "$1");
    } catch (cantDoToString) {
        return false;
    }
}

/**
 * This function returns an XMLHttpRequest instance for making AJAX requests. It is designed with various
 * fall-backs for older browser compatibility.
 * <p>
 * On failure, <code>null</code> is returned.
 * 
 * @returns XMLHttpRequest (or <code>null</code> on failure)
 */
function createAjaxRequest() {
    try {
        return new XMLHttpRequest();
    } catch (noDomLevel2Support) {
        try {
            return new ActiveXObject("Msxml12.XMLHTTP");
        } catch (noIE7ActiveXSupport) {
            try {
                return new ActiveXObject("Microsoft.XMLHTTP");
            } catch (noAjaxSupport) {
                // Return NULL on failure
                return null;
            }
        }
    }
}

/**
 * This function allows adding multiple event handlers to a single Element. It is designed with fall-backs
 * for compatibility with IE browsers.
 * <p>
 * If the fall-backs do not work, the event handler simply does not get set...
 * 
 * @param Element element
 * @param string eventName
 * @param function handler
 * @returns void
 */
function addEventHandler(element, eventName, handler) {
    // Check for the DOM Level 2 availability first (Firefox, Safari and IE 8)
    if (element.addEventListener) {
        element.addEventListener(eventName, handler, false);
    }
    // Alternatively, try older IE version's "attachEvent" method.
    else if (element.attachEvent) {
        element.attachEvent("on" + eventName, handler);
    }
}

/**
 * This function returns a reference to the Element that triggered the Event.
 * 
 * @param Event event (Represents "click", "change", "mouseover", etc.)
 * @returns Element
 */
function getActivatedObject(event) {
    // Early versions of IE do not even provide "event" to this function.
    if (!event) {
        // If it's available, pass window.event.srcElement instead.
        if (window.event && window.event.srcElement) {
            return window.event.srcElement;
        }
        
        // Return NULL on failure.
        return null;
    }
    
    // IE 7 uses event.srcElement instead of than event.target. Check this next.
    if (event.srcElement) {
        return event.srcElement;
    }
    
    // DOM Level 2 browsers (Firefox, Safari and IE 8) support event.target.
    if (event.target) {
        return event.target;
    }
    
    // Return NULL on failure.
    return null;
}

/**
 * A quick verification function to determine if a given e-mail address has the correct format to be a valid e-mail
 * address.
 * 
 * @param string email
 * @returns boolean <code>true</code> if the subject is in valid e-mail address format, <code>false</code> otherwise.
 */
function isEmailAddress(email) {
	var rx = new RegExp("^[a-z0-9!#$%&'*+/=?^_`{|}~-]+(?:\\.[a-z0-9!#$%&'*+/=?^_`{|}~-]+)*@(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\\.)+(?:[A-Z]{2}|com|org|net|edu|gov|mil|biz|info|mobi|name|aero|asia|jobs|museum)\\b$", "i");
	
	return rx.test(email);
}

/**
 * A quick verification function to determine if a give phone number has the correct area-code-plus-local-digits format.
 * 
 * @param string phone
 * @returns boolean <code>true</code> if the subject is in valid phone number format, <code>false</code> otherwise.
 */
function isUsPhoneNumber(phone) {
	return new RegExp("^\\D*1?\\D*[2-9][0-8]\\d\\D*[2-9]\\d{2}\\D*\\d{4}\\D*\\d*\\D*$").test(phone);
}

/**
 * A quick verification function to determine if a give zip code has the correct format.
 * 
 * @param string zip 
 * @returns boolean <code>true</code> if the subject is in valid zip code format, <code>false</code> otherwise.
 */
function isUsZipCode(zip) {
	return new RegExp("^\\d{5}\\D*\\d*$").test(zip);
}