Date Class

Contains methods for the Date primitive data type.

Namespace

System

Usage

For more information on Dates, see Primitive Data Types.

Date Methods

The following are methods for Date.

addDays(additionalDays)

Adds the specified number of additional days to a Date.

Signature

public Date addDays(Integer additionalDays)

Parameters

additionalDays
Type: Integer

Return Value

Type: Date

Example

Date myDate = Date.newInstance(1960, 2, 17);
Date newDate = mydate.addDays(2);

addMonths(additionalMonths)

Adds the specified number of additional months to a Date

Signature

public Date addMonths(Integer additionalMonths)

Parameters

additionalMonths
Type: Integer

Return Value

Type: Date

Example

date myDate = date.newInstance(1990, 11, 21);
date newDate = myDate.addMonths(3);
date expectedDate = date.newInstance(1991, 2, 21);
system.assertEquals(expectedDate, newDate);

addYears(additionalYears)

Adds the specified number of additional years to a Date

Signature

public Date addYears(Integer additionalYears)

Parameters

additionalYears
Type: Integer

Return Value

Type: Date

Example

date myDate = date.newInstance(1983, 7, 15);
date newDate = myDate.addYears(2);
date expectedDate = date.newInstance(1985, 7, 15);
system.assertEquals(expectedDate, newDate);

day()

Returns the day-of-month component of a Date.

Signature

public Integer day()

Return Value

Type: Integer

Example

date myDate = date.newInstance(1989, 4, 21);
Integer day = myDate.day();
system.assertEquals(21, day);

dayOfYear()

Returns the day-of-year component of a Date.

Signature

public Integer dayOfYear()

Return Value

Type: Integer

Example

date myDate = date.newInstance(1998, 10, 21);
Integer day = myDate.dayOfYear();
system.assertEquals(294, day);

daysBetween(secondDate)

Returns the number of days between the Date that called the method and the specified date.

Signature

public Integer daysBetween(Date secondDate)

Parameters

secondDate
Type: Date

Return Value

Type: Integer

Usage

If the Date that calls the method occurs after the compDate, the return value is negative.

Example

Date startDate = Date.newInstance(2008, 1, 1);
Date dueDate = Date.newInstance(2008, 1, 30);
Integer numberDaysDue = startDate.daysBetween(dueDate);

daysInMonth(year, month)

Returns the number of days in the month for the specified year and month (1=Jan).

Signature

public static Integer daysInMonth(Integer year, Integer month)

Parameters

year
Type: Integer
month
Type: Integer

Return Value

Type: Integer

Example

The following example finds the number of days in the month of February in the year 1960.

Integer numberDays = date.daysInMonth(1960, 2);

format()

Returns the Date as a string using the locale of the context user

Signature

public String format()

Return Value

Type: String

Example

// In American-English locale
date myDate = date.newInstance(2001, 3, 21);
String dayString = myDate.format();
system.assertEquals('3/21/2001', dayString);

isLeapYear(year)

Returns true if the specified year is a leap year.

Signature

public static Boolean isLeapYear(Integer year)

Parameters

year
Type: Integer

Return Value

Type: Boolean

Example

system.assert(Date.isLeapYear(2004));

isSameDay(dateToCompare)

Returns true if the Date that called the method is the same as the specified date.

Signature

public Boolean isSameDay(Date dateToCompare)

Parameters

dateToCompare
Type: Date

Return Value

Type: Boolean

Example

date myDate = date.today();
date dueDate = date.newInstance(2008, 1, 30);
boolean dueNow = myDate.isSameDay(dueDate);

month()

Returns the month component of a Date (1=Jan).

Signature

public Integer month()

Return Value

Type: Integer

Example

date myDate = date.newInstance(2004, 11, 21);
Integer month = myDate.month();
system.assertEquals(11, month);

monthsBetween(secondDate)

Returns the number of months between the Date that called the method and the specified date, ignoring the difference in days.

Signature

public Integer monthsBetween(Date secondDate)

Parameters

secondDate
Type: Date

Return Value

Type: Integer

Example

Date firstDate = Date.newInstance(2006, 12, 2);
Date secondDate = Date.newInstance(2012, 12, 8);
Integer monthsBetween = firstDate.monthsBetween(secondDate);
System.assertEquals(72, monthsBetween);

newInstance(year, month, date)

Constructs a Date from Integer representations of the year, month (1=Jan), and day.

Signature

public static Date newInstance(Integer year, Integer month, Integer date)

Parameters

year
Type: Integer
month
Type: Integer
date
Type: Integer

Return Value

Type: Date

Example

The following example creates the date February 17th, 1960:

Date myDate = date.newinstance(1960, 2, 17);

parse(stringDate)

Constructs a Date from a String. The format of the String depends on the local date format.

Signature

public static Date parse(String stringDate)

Parameters

stringDate
Type: String

Return Value

Type: Date

Example

The following example works in some locales.

date mydate = date.parse('12/27/2009');

today()

Returns the current date in the current user's time zone.

Signature

public static Date today()

Return Value

Type: Date

toStartOfMonth()

Returns the first of the month for the Date that called the method.

Signature

public Date toStartOfMonth()

Return Value

Type: Date

Example

date myDate = date.newInstance(1987, 12, 17);
date firstDate = myDate.toStartOfMonth();
date expectedDate = date.newInstance(1987, 12, 1);
system.assertEquals(expectedDate, firstDate);

toStartOfWeek()

Returns the start of the week for the Date that called the method, depending on the context user's locale.

Signature

public Date toStartOfWeek()

Return Value

Type: Date

Example

For example, the start of a week is Sunday in the United States locale, and Monday in European locales. For example:

Date myDate = Date.today();
Date weekStart = myDate.toStartofWeek();

valueOf(stringDate)

Returns a Date that contains the value of the specified String.

Signature

public static Date valueOf(String stringDate)

Parameters

stringDate
Type: String

Return Value

Type: Date

Usage

The specified string should use the standard date format “yyyy-MM-dd HH:mm:ss” in the local time zone.

Example

string year = '2008';
string month = '10';
string day = '5';
string hour = '12';
string minute = '20';
string second = '20';
string stringDate = year + '-' + month
 + '-' + day + ' ' + hour + ':' + 
minute + ':' + second;

Date myDate = date.valueOf(stringDate);

valueOf(fieldValue)

Converts the specified object to a Date. Use this method to convert a history tracking field value or an object that represents a Date value.

Signature

public static Date valueOf(Object fieldValue)

Parameters

fieldValue
Type: Object

Return Value

Type: Date

Usage

Use this method with the OldValue or NewValue fields of history sObjects, such as AccountHistory, when the field is a Date field.

Note
In API version 33.0 or earlier, if you call Date.valueOf with an object that represents a Datetime, the method returns a Date value that contains the hours, minutes, and seconds. In version 34.0 and later, Date.valueOf converts the object to a valid Date without the time information. To convert a variable of type Datetime to a Date, use the Datetime.date method.

Example

This example converts history tracking fields to Date values.

List<AccountHistory> ahlist = [SELECT Field,OldValue,NewValue FROM AccountHistory];
for(AccountHistory ah : ahlist) {
  System.debug('Field: ' + ah.Field);
  if (ah.field == 'MyDate__c') {
    Date oldValue = Date.valueOf(ah.OldValue);
    Date newValue = Date.valueOf(ah.NewValue);
  }
}

year()

Returns the year component of a Date

Signature

public Integer year()

Return Value

Type: Integer

Example

date myDate = date.newInstance(1988, 12, 17);
system.assertEquals(1988, myDate.year());
© Copyright 2000–2015 salesforce.com, inc. All rights reserved.
Various trademarks held by their respective owners.