Datetime Class

addDays(additionalDays)

Adds the specified number of days to a Datetime.

Signature

public Datetime addDays(Integer additionalDays)

Parameters

additionalDays: Type: Integer

Return Value

Type: Datetime

Example

1Datetime myDateTime = Datetime.newInstance(1960, 2, 17);
2Datetime newDateTime = myDateTime.addDays(2);
3Datetime expected = Datetime.newInstance(1960, 2, 19);
4System.assertEquals(expected, newDateTime);

addHours(additionalHours)

Adds the specified number of hours to a Datetime.

Signature

public Datetime addHours(Integer additionalHours)

Parameters

additionalHours: Type: Integer

Return Value

Type: Datetime

Example

1DateTime myDateTime = DateTime.newInstance(1997, 1, 31, 7, 8, 16);
2DateTime newDateTime = myDateTime.addHours(3);
3DateTime expected = DateTime.newInstance(1997, 1, 31, 10, 8, 16);
4System.assertEquals(expected, newDateTime);

addMinutes(additionalMinutes)

Adds the specified number of minutes to a Datetime.

Signature

public Datetime addMinutes(Integer additionalMinutes)

Parameters

additionalMinutes: Type: Integer

Return Value

Type: Datetime

Example

1DateTime myDateTime = DateTime.newInstance(1999, 2, 11, 8, 6, 16);
2DateTime newDateTime = myDateTime.addMinutes(7);
3DateTime expected = DateTime.newInstance(1999, 2, 11, 8, 13, 16);
4System.assertEquals(expected, newDateTime);

addMonths(additionalMonths)

Adds the specified number of months to a Datetime.

Signature

public Datetime addMonths(Integer additionalMonths)

Parameters

additionalMonths: Type: Integer

Return Value

Type: Datetime

Example

1DateTime myDateTime = DateTime.newInstance(2000, 7, 7, 7, 8, 12);
2DateTime newDateTime = myDateTime.addMonths(1);
3DateTime expected = DateTime.newInstance(2000, 8, 7, 7, 8, 12);
4System.assertEquals(expected, newDateTime);

addSeconds(additionalSeconds)

Adds the specified number of seconds to a Datetime.

Signature

public Datetime addSeconds(Integer additionalSeconds)

Parameters

additionalSeconds: Type: Integer

Return Value

Type: Datetime

Example

1DateTime myDateTime = DateTime.newInstance(2001, 7, 19, 10, 7, 12);
2DateTime newDateTime = myDateTime.addSeconds(4);
3DateTime expected = DateTime.newInstance(2001, 7, 19, 10, 7, 16);
4System.assertEquals(expected, newDateTime);

addYears(additionalYears)

Adds the specified number of years to a Datetime.

Signature

public Datetime addYears(Integer additionalYears)

Parameters

additionalYears: Type: Integer

Return Value

Type: Datetime

Example

1DateTime myDateTime = DateTime.newInstance(2009, 12, 17, 13, 6, 6);
2DateTime newDateTime = myDateTime.addYears(1);
3DateTime expected = DateTime.newInstance(2010, 12, 17, 13, 6, 6);
4System.assertEquals(expected, newDateTime);

date()

Returns the Date component of a Datetime in the local time zone of the context user.

Signature

public Date date()

Return Value

Type: Date

Example

1DateTime myDateTime = DateTime.newInstance(2006, 3, 16, 12, 6, 13);
2Date myDate = myDateTime.date();
3Date expected = Date.newInstance(2006, 3, 16);
4System.assertEquals(expected, myDate);

dateGMT()

Return the Date component of a Datetime in the GMT time zone.

Signature

public Date dateGMT()

Return Value

Type: Date

Example

1// California local time, PST
2DateTime myDateTime = DateTime.newInstance(2006, 3, 16, 23, 0, 0);
3Date myDate = myDateTime.dateGMT();
4Date expected = Date.newInstance(2006, 3, 17);
5System.assertEquals(expected, myDate);

day()

Returns the day-of-month component of a Datetime in the local time zone of the context user.

Signature

public Integer day()

Return Value

Type: Integer

Example

1DateTime myDateTime = DateTime.newInstance(1986, 2, 21, 23, 0, 0);
2System.assertEquals(21, myDateTime.day());

dayGmt()

Returns the day-of-month component of a Datetime in the GMT time zone.

Signature

public Integer dayGmt()

Return Value

Type: Integer

Example

1// California local time, PST
2DateTime myDateTime = DateTime.newInstance(1987, 1, 14, 23, 0, 3);
3System.assertEquals(15, myDateTime.dayGMT());

dayOfYear()

Returns the day-of-year component of a Datetime in the local time zone of the context user.

Signature

public Integer dayOfYear()

Return Value

Type: Integer

Example

For example, February 5, 2008 08:30:12 would be day 36.

1Datetime myDate = Datetime.newInstance(2008, 2, 5, 8, 30, 12);
2system.assertEquals(myDate.dayOfYear(), 36);

dayOfYearGmt()

Returns the day-of-year component of a Datetime in the GMT time zone.

Signature

public Integer dayOfYearGmt()

Return Value

Type: Integer

Example

1// This sample assumes we are in the PST timezone
2DateTime myDateTime = DateTime.newInstance(1999, 2, 5, 23, 0, 3);
3// January has 31 days + 5 days in February = 36 days
4// dayOfYearGmt() adjusts the time zone from the current time zone to GMT
5// by adding 8 hours to the PST time zone, so it's 37 days and not 36 days 
6System.assertEquals(37, myDateTime.dayOfYearGmt());

format()

Converts the date to the local time zone and returns the converted date as a formatted string using the locale of the context user. If the time zone cannot be determined, GMT is used.

Signature

public String format()

Return Value

Type: String

Example

The sample is executed in an org where the “Enable ICU Locale Formats” crucial update is enabled. See https://releasenotes.docs.salesforce.com/en-us/spring20/release-notes/rn_forcecom_globalization_enable_icu_cruc.htm.

Note

1DateTime.myDateTime = DateTime.newInstance(1993, 6, 6, 3, 3, 3);
2system.assertEquals('6/6/1993, 3:03 AM', mydatetime.format());

format(dateFormatString)

Converts the date to the local time zone and returns the converted date as a string using the supplied Java simple date format. If the time zone cannot be determined, GMT is used.

Signature

public String format(String dateFormatString)

Parameters

dateFormatString: Type: String

Return Value

Type: String

Usage

For more information on the Java simple date format, see Java SimpleDateFormat.

Example

1Datetime myDT = DateTime.newInstance(2022, 5, 4, 19, 37, 55);
2String myDate = myDT.format('yyyy-MM-dd h:mm a');
3String expected = '2022-05-04 7:37 PM';
4System.assertEquals(expected, myDate);

format(dateFormatString, timezone)

Converts the date to the specified time zone and returns the converted date as a string using the supplied Java simple date format. If the supplied time zone is not in the correct format, GMT is used.

Signature

public String format(String dateFormatString, String timezone)

Parameters

dateFormatString: Type: String
timezone: Type: String; Valid time zone values for the timezone argument are the time zones of the Java TimeZone class that correspond to the time zones returned by the TimeZone.getAvailableIDs method in Java. We recommend you use full time zone names, not the three-letter abbreviations.

Return Value

Type: String

Usage

For more information on the Java simple date format, see Java SimpleDateFormat.

Example

This example uses format to convert a GMT date to the America/New_York time zone and formats the date using the specified date format.

1Datetime GMTDate = 
2  Datetime.newInstanceGmt(2011,6,1,12,1,5);
3String strConvertedDate = 
4  GMTDate.format('MM/dd/yyyy HH:mm:ss', 
5                 'America/New_York');
6// Date is converted to 
7// the new time zone and is adjusted
8// for daylight saving time.
9System.assertEquals(
10  '06/01/2011 08:01:05', strConvertedDate);

formatGmt(dateFormatString)

Returns a Datetime as a string using the supplied Java simple date format and the GMT time zone.

Signature

public String formatGmt(String dateFormatString)

Parameters

dateFormatString: Type: String

Return Value

Type: String

Usage

For more information on the Java simple date format, see Java SimpleDateFormat.

Example

1DateTime myDateTime = DateTime.newInstance(1993, 6, 6, 3, 3, 3);
2String formatted = myDateTime.formatGMT('EEE, MMM d yyyy HH:mm:ss');
3String expected = 'Sun, Jun 6 1993 10:03:03';
4System.assertEquals(expected, formatted);

formatLong()

Converts the date to the local time zone and returns the converted date in long date format.

Signature

public String formatLong()

Return Value

Type: String

Example

1// Passing local date based on the PST time zone
2Datetime dt = DateTime.newInstance(2012,12,28,10,0,0);
3// Writes 12/28/2012 10:00:00 AM PST
4System.debug('dt.formatLong()=' + dt.formatLong());

getTime()

Returns the number of milliseconds since January 1, 1970, 00:00:00 GMT represented by this DateTime object.

Signature

public Long getTime()

Return Value

Type: Long

Example

1DateTime dt = DateTime.newInstance(2007, 6, 23, 3, 3, 3);
2Long gettime = dt.getTime();
3Long expected = 1182592983000L;
4System.assertEquals(expected, gettime);

hour()

Returns the hour component of a Datetime in the local time zone of the context user.

Signature

public Integer hour()

Return Value

Type: Integer

Example

1DateTime myDateTime = DateTime.newInstance(1998, 11, 21, 3, 3, 3);
2System.assertEquals(3 , myDateTime.hour());

hourGmt()

Returns the hour component of a Datetime in the GMT time zone.

Signature

public Integer hourGmt()

Return Value

Type: Integer

Example

1// California local time
2DateTime myDateTime = DateTime.newInstance(2000, 4, 27, 3, 3, 3);
3System.assertEquals(10 , myDateTime.hourGMT());

isSameDay(dateToCompare)

Returns true if the Datetime that called the method is the same as the specified Datetime in the local time zone of the context user.

Signature

public Boolean isSameDay(Datetime dateToCompare)

Parameters

dateToCompare: Type: Datetime

Return Value

Type: Boolean

Example

1datetime myDate = datetime.now();
2datetime dueDate = 
3     datetime.newInstance(2008, 1, 30);
4boolean dueNow = myDate.isSameDay(dueDate);

millisecond()

Return the millisecond component of a Datetime in the local time zone of the context user.

Signature

public Integer millisecond()

Return Value

Type: Integer

Example

1DateTime myDateTime = DateTime.now();
2system.debug(myDateTime.millisecond());

millisecondGmt()

Return the millisecond component of a Datetime in the GMT time zone.

Signature

public Integer millisecondGmt()

Return Value

Type: Integer

Example

1DateTime myDateTime = DateTime.now();
2system.debug(myDateTime.millisecondGMT());

minute()

Returns the minute component of a Datetime in the local time zone of the context user.

Signature

public Integer minute()

Return Value

Type: Integer

Example

1DateTime myDateTime = DateTime.newInstance(2001, 2, 27, 3, 3, 3);
2system.assertEquals(3, myDateTime.minute());

minuteGmt()

Returns the minute component of a Datetime in the GMT time zone.

Signature

public Integer minuteGmt()

Return Value

Type: Integer

Example

1DateTime myDateTime = DateTime.newInstance(2002, 12, 3, 3, 3, 3);
2system.assertEquals(3, myDateTime.minuteGMT());

month()

Returns the month component of a Datetime in the local time zone of the context user (1=Jan).

Signature

public Integer month()

Return Value

Type: Integer

Example

1DateTime myDateTime = DateTime.newInstance(2004, 11, 4, 3, 3, 3);
2system.assertEquals(11, myDateTime.month());

monthGmt()

Returns the month component of a Datetime in the GMT time zone (1=Jan).

Signature

public Integer monthGmt()

Return Value

Type: Integer

Example

1DateTime myDateTime = DateTime.newInstance(2006, 11, 19, 3, 3, 3);
2system.assertEquals(11, myDateTime.monthGMT());

newInstance(milliseconds)

Constructs a Datetime and initializes it to represent the specified number of milliseconds since January 1, 1970, 00:00:00 GMT.

Signature

public static Datetime newInstance(Long milliseconds)

Parameters

milliseconds: Type: Long

Return Value

Type: Datetime

The returned date is in the GMT time zone.

Example

1Long longtime = 1341828183000L;
2DateTime dt = DateTime.newInstance(longtime);
3DateTime expected = DateTime.newInstance(2012, 7, 09, 3, 3, 3);
4System.assertEquals(expected, dt);

newInstance(date, time)

Constructs a DateTime from the specified date and time in the local time zone.

Signature

public static Datetime newInstance(Date date, Time time)

Parameters

date: Type: Date
time: Type: Time

Return Value

Type: Datetime

The returned date is in the GMT time zone.

Example

1Date myDate = Date.newInstance(2011, 11, 18);
2Time myTime = Time.newInstance(3, 3, 3, 0);
3DateTime dt = DateTime.newInstance(myDate, myTime);
4DateTime expected = DateTime.newInstance(2011, 11, 18, 3, 3, 3);
5System.assertEquals(expected, dt);

newInstance(year, month, day)

Constructs a Datetime from Integer representations of the specified year, month (1=Jan), and day at midnight in the local time zone.

Signature

public static Datetime newInstance(Integer year, Integer month, Integer day)

Parameters

year: Type: Integer
month: Type: Integer
day: Type: Integer

Return Value

Type: Datetime

The returned date is in the GMT time zone.

Example

1datetime myDate = datetime.newInstance(2008, 12, 1);

newInstance(year, month, day, hour, minute, second)

Constructs a Datetime from Integer representations of the specified year, month (1=Jan), day, hour, minute, and second in the local time zone.

Signature

public static Datetime newInstance(Integer year, Integer month, Integer day, Integer hour, Integer minute, Integer second)

Parameters

year: Type: Integer
month: Type: Integer
day: Type: Integer
hour: Type: Integer
minute: Type: Integer
second: Type: Integer

Return Value

Type: Datetime

The returned date is in the GMT time zone.

Example

1Datetime myDate = Datetime.newInstance(2008, 12, 1, 12, 30, 2);

newInstanceGmt(date, time)

Constructs a DateTime from the specified date and time in the GMT time zone.

Signature

public static Datetime newInstanceGmt(Date date, Time time)

Parameters

date: Type: Date
time: Type: Time

Return Value

Type: Datetime

Example

1Date myDate = Date.newInstance(2013, 11, 12);
2Time myTime = Time.newInstance(3, 3, 3, 0);
3DateTime dt = DateTime.newInstanceGMT(myDate, myTime);
4DateTime expected = DateTime.newInstanceGMT(2013, 11, 12, 3, 3, 3);
5System.assertEquals(expected, dt);

newInstanceGmt(year, month, date)

Constructs a Datetime from Integer representations of the specified year, month (1=Jan), and day at midnight in the GMT time zone

Signature

public static Datetime newInstanceGmt(Integer year, Integer month, Integer date)

Parameters

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

Return Value

Type: Datetime

Example

1DateTime dt = DateTime.newInstanceGMT(1996, 3, 22);

newInstanceGmt(year, month, date, hour, minute, second)

Constructs a Datetime from Integer representations of the specified year, month (1=Jan), day, hour, minute, and second in the GMT time zone

Signature

public static Datetime newInstanceGmt(Integer year, Integer month, Integer date, Integer hour, Integer minute, Integer second)

Parameters

year: Type: Integer
month: Type: Integer
date: Type: Integer
hour: Type: Integer
minute: Type: Integer
second: Type: Integer

Return Value

Type: Datetime

Example

1//California local time
2DateTime dt = DateTime.newInstanceGMT(1998, 1, 29, 2, 2, 3);
3DateTime expected = DateTime.newInstance(1998, 1, 28, 18, 2, 3);
4System.assertEquals(expected, dt);

now()

Returns the current Datetime based on a GMT calendar.

Signature

public static Datetime now()

Return Value

Type: Datetime

The format of the returned datetime is: 'MM/DD/YYYY HH:MM PERIOD'

Example

1datetime myDateTime = datetime.now();

parse(datetimeString)

Constructs a Datetime from the given String in the local time zone and in the format of the user locale.

Signature

public static Datetime parse(String datetimeString)

Parameters

datetimeString: Type: String

Return Value

Type: Datetime

The returned date is in the GMT time zone.

Example

This example uses parse to create a Datetime from a date passed in as a string and that is formatted for the English (United States) locale. You may need to change the format of the date string if you have a different locale.

This sample is executed in an org where the “Enable ICU Locale Formats” crucial update is enabled. See https://releasenotes.docs.salesforce.com/en-us/spring20/release-notes/rn_forcecom_globalization_enable_icu_cruc.htm.

Note

1Datetime dt = DateTime.parse('10/14/2011, 11:46 AM');
2String myDtString = dt.format();
3system.assertEquals(myDtString, '10/14/2011, 11:46 AM');

second()

Returns the second component of a Datetime in the local time zone of the context user.

Signature

public Integer second()

Return Value

Type: Integer

Example

1DateTime dt = DateTime.newInstanceGMT(1999, 9, 22, 3, 1, 2);
2System.assertEquals(2, dt.second());

secondGmt()

Returns the second component of a Datetime in the GMT time zone.

Signature

public Integer secondGmt()

Return Value

Type: Integer

Example

1DateTime dt = DateTime.newInstance(2000, 2, 3, 3, 1, 5);
2System.assertEquals(5, dt.secondGMT());

time()

Returns the time component of a Datetime in the local time zone of the context user.

Signature

public Time time()

Return Value

Type: Time

Example

1DateTime dt = DateTime.newInstance(2002, 11, 21, 0, 2, 2);
2Time expected = Time.newInstance(0, 2, 2, 0);
3System.assertEquals(expected, dt.time());

timeGmt()

Returns the time component of a Datetime in the GMT time zone.

Signature

public Time timeGmt()

Return Value

Type: Time

Example

1// This sample is based on the PST time zone
2DateTime dt = DateTime.newInstance(2004, 1, 27, 4, 1, 2);
3Time expected = Time.newInstance(12, 1, 2, 0);
4// 8 hours are added to the time to convert it from
5// PST to GMT
6System.assertEquals(expected, dt.timeGMT());

valueOf(dateTimeString)

Returns a Datetime that contains the value of the specified string.

Signature

public static Datetime valueOf(String dateTimeString)

Parameters

dateTimeString: Type: String

Return Value

Type: Datetime

The returned date is in the GMT time zone.

Usage

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

Example

1string year = '2008';
2string month = '10';
3string day = '5';
4string hour = '12';
5string minute = '20';
6string second = '20';
7string stringDate = year + '-' + month + '-' + day + ' ' + hour + ':' 
8    + minute +  ':' + second;
9
10Datetime myDate = Datetime.valueOf(stringDate);

valueOf(fieldValue)

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

Signature

public static Datetime valueOf(Object fieldValue)

Parameters

fieldValue: Type: Object

Return Value

Type: Datetime

Usage

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

Example

1List<AccountHistory> ahlist = [SELECT Field,OldValue,NewValue FROM AccountHistory];
2for(AccountHistory ah : ahlist) {
3  System.debug('Field: ' + ah.Field);
4  if (ah.field == 'MyDatetime__c') {
5    Datetime oldValue = Datetime.valueOf(ah.OldValue);
6    Datetime newValue = Datetime.valueOf(ah.NewValue);
7  }
8}

valueOfGmt(dateTimeString)

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

Signature

public static Datetime valueOfGmt(String dateTimeString)

Parameters

dateTimeString: Type: String

Return Value

Type: Datetime

Usage

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

Example

1// California locale time
2string year = '2009';
3string month = '3';
4string day = '5';
5string hour = '5';
6string minute = '2';
7string second = '2';
8string stringDate = year + '-' + month + '-' + day + ' ' + hour + ':' 
9    + minute +  ':' + second;
10
11Datetime myDate = Datetime.valueOfGMT(stringDate);
12
13DateTime expected = DateTime.newInstance(2009, 3, 4, 21, 2, 2);
14System.assertEquals(expected, myDate);

year()

Returns the year component of a Datetime in the local time zone of the context user.

Signature

public Integer year()

Return Value

Type: Integer

Example

1DateTime dt = DateTime.newInstance(2012, 1, 26, 5, 2, 4);
2System.assertEquals(2012, dt.year());

yearGmt()

Returns the year component of a Datetime in the GMT time zone.

Signature

public Integer yearGmt()

Return Value

Type: Integer

Example

1DateTime dt = DateTime.newInstance(2012, 10, 4, 6, 4, 6);
2System.assertEquals(2012, dt.yearGMT());

Apex Reference Guide

Namespace

Usage

Datetime Methods

addDays(additionalDays)

Signature

Parameters

Return Value

Example

addHours(additionalHours)

Signature

Parameters

Return Value

Example

addMinutes(additionalMinutes)

Signature

Parameters

Return Value

Example

addMonths(additionalMonths)

Signature

Parameters

Return Value

Example

addSeconds(additionalSeconds)

Signature

Parameters

Return Value

Example

addYears(additionalYears)

Signature

Parameters

Return Value

Example

date()

Signature

Return Value

Example

dateGMT()

Signature

Return Value

Example

day()

Signature

Return Value

Example

dayGmt()

Signature

Return Value

Example

dayOfYear()

Signature

Return Value

Example

dayOfYearGmt()

Signature

Return Value

Example

format()

Signature

Return Value

Example

format(dateFormatString)

Signature

Parameters

Return Value

Usage

Example

format(dateFormatString, timezone)

Signature

Parameters

Return Value

Usage

Example

formatGmt(dateFormatString)

Signature

Parameters

Return Value

Usage