/* -*- Mode: idl; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsISupports.idl"

interface calIDateTime;
interface calIItemBase;

[scriptable, uuid(69741510-5f5d-11e4-9803-0800200c9a66)]
interface calIDateTimeFormatter : nsISupports
{
    /**
     * Format a date in either short or long format, depending on the
     * users preference
     *
     * @see
     *     formatDateShort
     *     formatDateLong
     */
    AString formatDate(in calIDateTime aDate);

    /**
     * Format a date into a short format, for example
     * "12/17/2005"
     *
     * @param aDate
     *      the datetime to format
     * @returns
     *      a string representing the date part of the datetime
     */
    AString formatDateShort(in calIDateTime aDate);

    /**
     * Format a date into a long format, for example
     * "Sat Dec 17 2005"
     *
     * @param aDate
     *      the datetime to format
     * @returns
     *      a string representing the date part of the datetime
     */
    AString formatDateLong(in calIDateTime aDate);

    /**
     * Format a date into a short format without mentioning the year, for
     * example "Dec 17"
     *
     * @param aDate
     *      the datetime to format
     * @returns
     *      a string representing the date part of the datetime
     */
    AString formatDateWithoutYear(in calIDateTime aDate);

    /**
     * Format a time into the format specified by the OS settings.
     * Will omit the seconds from the output.
     *
     * @param aDate
     *      the datetime to format
     * @returns
     *      a string representing the time part of the datetime
     */
    AString formatTime(in calIDateTime aDate);

    /**
     * Format a datetime into the format specified by the OS settings.
     * Will omit the seconds from the output.
     *
     * @param aDateTime
     *      the datetime to format
     * @returns
     *      a string representing the datetime
     */
    AString formatDateTime(in calIDateTime aDate);

    /**
     * Format a time interval that is defined by an item with the default
     * timezone Internally it calls "formatInterval" after retrieving 
     * the start/entry and end/due date of the item.
     *
     * @param aItem 
     *      The item describing the interval
     */
    AUTF8String formatItemInterval(in calIItemBase aItem);

    /**
     * Format a time interval like formatItemInterval, but only show times.
     *
     * @param aItem     The item providing the interval
     * @return          The string describing the interval
     */
     AUTF8String formatItemTimeInterval(in calIItemBase aItem);

    /**
     * Format a date/time interval. The returned string may assume that the
     * dates are so close to each other, that it can leave out some parts of the
     * part string denoting the end date.
     *
     * @param aStartDate        The start of the interval
     * @param aEndDate          The end of the interval
     * @return                  A String describing the interval in a legible form
     */
    AUTF8String formatInterval(in calIDateTime aStartDate,
                               in calIDateTime aEndDate);

    /**
     * Format a time interval like formatInterval, but show only the time.
     *
     * @param aStartDate        The start of the interval.
     * @param aEndDate          The end of the interval.
     * @return                  The formatted time interval.
     */
    AUTF8String formatTimeInterval(in calIDateTime aStartTime,
                                   in calIDateTime aEndTime);

    /**
     * Get the monthday followed by its ordinal symbol in the current locale.
     * e.g.  monthday 1 -> 1st
     *       monthday 2 -> 2nd etc.
     *
     * @param aMonthdayIndex
     *      a number from 1 to 31
     * @returns
     *      the monthday number in ordinal format in the current locale
     */
    AUTF8String formatDayWithOrdinal(in unsigned long aMonthdayIndex);

    /**
     * Get the month name
     *
     * @param aMonthIndex
     *     zero-based month number (0 is january, 11 is december)
     * @returns
     *      the month name in the current locale
     */
    AString monthName(in unsigned long aMonthIndex);

    /**
     * Get the abbrevation of the month name
     *
     * @see monthName
     */
    AString shortMonthName(in unsigned long aMonthIndex);

    /**
     * Get the day name
     * @param aMonthIndex
     *     zero-based month number (0 is sunday, 6 is saturday)
     * @returns
     *      the day name in the current locale
     */
    AString dayName(in unsigned long aDayIndex);

    /**
     * Get the abbrevation of the day name
     * @see dayName
     */
    AString shortDayName(in unsigned long aDayIndex);
};