Date Math / Overview
material theme

Date Math Overview

The Date Math is a package for JavaScript Date manipulations.

The package exports numerous functions that support the performing of different date manipulation tasks. For example, add and remove days or get the week number.

Basic Usage

The following example demonstrates the Date Math library in action.

import React from 'react';
import ReactDOM from 'react-dom';

import { addDays, addWeeks, addMonths, addYears, addDecades, addCenturies } from '@progress/kendo-date-math';
import { Calendar } from '@progress/kendo-react-dateinputs';
import { NumericTextBox } from '@progress/kendo-react-inputs';

class App extends React.Component {
    state = {
        startDate: new Date(),
        resultDate: new Date(),
        format: 'D',
        dateParts: {
            days: 1,
            weeks: 0,
            months: 0,
            years: 0,
            decades: 0,
            centuries: 0
        }
    };

    render() {
        const { startDate, format, dateParts, resultDate } = this.state;
        return (
            <div>
                The new date is {resultDate.toLocaleDateString()}
                <div className="row example-config">
                    <div className="col-sm-12 col-md-6 example-col">
                        <p>
                            Start Date
                    </p>
                        <Calendar
                            value={startDate}
                            onChange={this.changeStartDate}
                        />
                    </div>
                    <div className="col-sm-12 col-md-6 example-col">
                        <div className="row">
                            <div className="col-sm-4">
                                <p>
                                    Days
                                </p>
                                <NumericTextBox
                                    id="days"
                                    format="N0"
                                    width={80}
                                    value={dateParts.days}
                                    onChange={this.changePart}
                                />
                            </div>
                            <div className="col-sm-4">
                                <p>
                                    Weeks
                                </p>
                                <NumericTextBox
                                    id="weeks"
                                    format="N0"
                                    width={80}
                                    value={dateParts.weeks}
                                    onChange={this.changePart}
                                />
                            </div>
                            <div className="col-sm-4">
                                <p>
                                    Months
                                </p>
                                <NumericTextBox
                                    id="months"
                                    format="N0"
                                    width={80}
                                    value={dateParts.months}
                                    onChange={this.changePart}
                                />
                            </div>
                            <div className="col-sm-4">
                                <p>
                                    Years
                                </p>
                                <NumericTextBox
                                    id="years"
                                    format="N0"
                                    width={80}
                                    value={dateParts.years}
                                    onChange={this.changePart}
                                />
                            </div>
                            <div className="col-sm-4">
                                <p>
                                    Decades
                                </p>
                                <NumericTextBox
                                    id="decades"
                                    format="N0"
                                    width={80}
                                    value={dateParts.decades}
                                    onChange={this.changePart}
                                />
                            </div>
                            <div className="col-sm-4">
                                <p>
                                    Centuries
                                </p>
                                <NumericTextBox
                                    id="centuries"
                                    format="N0"
                                    width={80}
                                    value={dateParts.centuries}
                                    onChange={this.changePart}
                                />
                            </div>
                        </div>
                    </div>
                </div>
            </div>
        );
    }

    changeStartDate = ({ value }) => {
        this.setState({
            startDate: value,
            resultDate: value,
            dateParts: {
                days: 1,
                weeks: 0,
                months: 0,
                years: 0,
                decades: 0,
                centuries: 0
            }
        });
    }

    changePart = ({ value, target }) => {
        let { startDate, dateParts, resultDate } = this.state;
        const part = Object.keys(this.state.dateParts).find((key) => key === target.props.id);

        switch (part) {
            case 'days':
                resultDate = addDays(startDate, value);
                break;
            case 'weeks':
                resultDate = addWeeks(startDate, value);
                break;
            case 'months':
                resultDate = addMonths(startDate, value);
                break;
            case 'years':
                resultDate = addYears(startDate, value);
                break;
            case 'decades':
                resultDate = addDecades(startDate, value);
                break;
            case 'centuries':
                resultDate = addCenturies(startDate, value);
                break;
            default:
                resultDate = startDate;
        }

        dateParts[part] = value;

        this.setState({ resultDate, dateParts });
    }
}

ReactDOM.render(
    <App />,
    document.querySelector('my-app')
);

Installation

  1. Download and install the package:

    npm install --save @progress/kendo-date-math

  2. Once installed, individual functions can be imported and the Data Query component is ready to use.

    import { getDate, addDays } from '@progress/kendo-date-math';

Date Calculations

The Date Math provides date-calculation options for adding and removing:

The component also enables you to get the first or last:

In addition, by using the Date Math component you can create and compare dates and get the:

Days

To add or remove a conditional number of days from a Date object, use the addDays method.

import { addDays } from '@progress/kendo-date-math';

const date = new Date(2000, 10, 10);
const newDate = addDays(date, 10); //returns a new Date instance

Weeks

To add or remove a conditional number of weeks from a Date object, use the addWeeks method.

import { addWeeks } from '@progress/kendo-date-math';

const date = new Date(2000, 10, 10);
const newDate = addWeeks(date, 10); //returns a new Date instance

Months

To add or remove a conditional number of months from a Date object, use the addMonths method.

import { addMonths } from '@progress/kendo-date-math';

const date = new Date(2000, 10, 10);
const newDate = addMonths(date, 10); //returns a new Date instance `2001-9-10`

Years

To add or remove a conditional number of years from a Date object, use the addYears method.

import { addYears } from '@progress/kendo-date-math';

const date = new Date(2000, 10, 10);
const newDate = addYears(date, 10); //returns a new Date instance `2010-11-10`

Decades

To add or remove a conditional number of decades from a Date object, use the addDecades method.

import { addDecades } from '@progress/kendo-date-math';

const date = new Date(2000, 10, 10);
const newDate = addDecades(date, 10); //returns a new Date instance `2100-11-10`

Centuries

To add or remove a conditional number of centuries from a Date object, use the addCenturies method.

import { addCenturies } from '@progress/kendo-date-math';

const date = new Date(2000, 10, 10);
const newDate = addCenturies(date, 10); //returns a new Date instance `3000-11-10`

First and Last Dates in Months

To get the first and the last dates from a Date object, use the firstDayOfMonth and lastDayOfMonth functions respectively.

import { firstDayOfMonth, lastDayOfMonth } from '@progress/kendo-date-math';

const date = new Date(2000, 10, 10);
const firstDay = firstDayOfMonth(date); //returns first date of the month, `2000-11-1`
const lastDay = lastDayOfMonth(date); //returns last date of the month, `2000-11-30`

First and Last Months in Years

To get the first and the last months from a Date object, use the firstMonthOfYear and lastMonthOfYear functions respectively.

import { firstMonthOfYear, lastMonthOfYear } from '@progress/kendo-date-math';

const date = new Date(2000, 10, 10);
const firstDay = firstMonthOfYear(date); //returns first month of the year, `2000-1-10`
const lastDay = lastMonthOfYear(date); //returns last month of the year, `2000-12-10`

First and Last Years in Decades

To get the first and the last years from a Date object, use the firstYearOfDecade and lastYearOfDecade functions respectively.

import { firstYearOfDecade, lastYearOfDecade } from '@progress/kendo-date-math';

const date = new Date(2005, 10, 10);
const firstDay = firstYearOfDecade(date); //returns first year of the decade, `2000-11-10`
const lastDay = lastYearOfDecade(date); //returns last year of the decade, `2009-11-10`

First and Last Decades in Centuries

To get the first and the last decades from a Date object, use the firstDecadeOfCentury and lastDecadeOfCentury functions respectively.

import { firstDecadeOfCentury, lastDecadeOfCentury } from '@progress/kendo-date-math';

const date = new Date(2020, 10, 10);
const firstDay = firstDecadeOfCentury(date); //returns first decade of the century, `2000-11-10`
const lastDay = lastDecadeOfCentury(date); //returns last decade of the century, `2090-11-10`

Next and Previous Dates in Weeks

To get the next and the previous dates in a week based on a week day number, use the nextDayOfWeek and prevDayOfWeek functions respectively.

import { Day, prevDayOfWeek, nextDayOfWeek } from '@progress/kendo-date-math';

const nextDate = nextDayOfWeek(new Date(2016, 0, 1), Day.Wednesday); // 2016-01-06, Wednesday
const prevDate = prevDayOfWeek(new Date(2016, 0, 1), Day.Wednesday); // 2015-12-30, Wednesday

Week Numbers in Years

To calculate the week number of a date, use the weekInYear function.

import { weekInYear } from '@progress/kendo-date-math';

const date = new Date(2000, 10, 10);
const weekNumber = weekInYear(date); //returns the week number of the corresponding date

Date Ranges in Months

To get the duration in months between two Date objects, use the durationInMonths function.

import { durationInMonths } from '@progress/kendo-date-math';

const start = new Date(2020, 1, 20);
const end = new Date(2020, 10, 4);
const duration = durationInMonths(start, end); //returns the duration in months, `9`

Date Ranges in Years

To get the duration in years between two Date objects, use the durationInYears function.

import { durationInYears } from '@progress/kendo-date-math';

const start = new Date(2015, 1, 20);
const end = new Date(2020, 10, 4);
const duration = durationInYears(start, end); //returns the duration in years, `5`

Date Ranges in Decades

To get the duration in decades between two Date objects, use the durationInDecades function.

import { durationInDecades } from '@progress/kendo-date-math';

const start = new Date(2000, 1, 20);
const end = new Date(2020, 10, 4);
const duration = durationInDecades(start, end); //returns the duration in decades, `2`

Date Ranges in Centuries

To get the centuries in decades between two Date objects, use the durationInCenturies function.

import { durationInCenturies } from '@progress/kendo-date-math';

const start = new Date(2000, 1, 20);
const end = new Date(2300, 10, 4);
const duration = durationInCenturies(start, end); //returns the duration in centuries, `3`

Date Part

To get only the date part of a Date instance, use the getDate function.

import { getDate } from '@progress/kendo-date-math';

const date = new Date(2000, 10, 10, 22, 30);
const datePart = getDate(date); //returns a Date instance with '00:00:00' time

Comparing Dates

To compare dates, the Date Math provides options for:

Date and Time Portions

To compare the date and time portions of the date instance of two dates, use isEqual function.

import { isEqual } from '@progress/kendo-date-math';

const date1 = new Date(2000, 10, 10);
const date2 = new Date(2000, 10, 10, 10);
const equal = isEqual(date1, date2); //returns false

Date-Only Portions

To compare only the date portions of the date instance of two dates, use the isEqualDate function.

import { isEqual } from '@progress/kendo-date-math';

const date1 = new Date(2000, 10, 10);
const date2 = new Date(2000, 10, 10, 10);
const equal = isEqualDate(date1, date2); //returns true

Creating Dates

To create a date with year value below 100, use the createDate function.

import { createDate } from '@progress/kendo-date-math';

createDate(16, 0, 15); // 0016-01-15 00:00:00
createDate(2016, 0, 15); // 2016-01-15 00:00:00
createDate(2016, 0, 15, 22, 22, 20); // 2016-01-15 22:22:20

Timezone Adjustments

Check the Timezone help topic for more details.

 /