Force.com Apex Code Developer's Guide

Clouds with binary code floating aboveCloud with binary code floating above

No Results

Search Tips:

  • Please consider misspellings
  • Try different search keywords
PDF

Newer Version Available

This content describes an older version of this product. View Latest

Datetime Methods

Contains methods for the Datetime primitive data type.

Namespace

System

Usage

For more information about the Datetime, see Primitive Data Types.

Datetime Methods

The following are methods for Datetime.

addDays(Integer)

Adds the specified number of days to a Datetime.

Signature

public Datetime addDays(Integer addlDays)

Parameters

addlDays
Type: Integer

Return Value

Type: Datetime

Example

1datetime myDate = 
2   datetime.newInstance
3      (1960, 2, 17);
4datetime newDate = mydate.addDays(2);

addHours(Integer)

Adds the specified number of hours to a Datetime.

Signature

public Datetime addHours(Integer addlHours)

Parameters

addlHours
Type: Integer

Return Value

Type: Datetime

addMinutes(Integer)

Adds the specified number of minutes to a Datetime.

Signature

public Datetime addMinutes(Integer addlMinutes)

Parameters

addlMinutes
Type: Integer

Return Value

Type: Datetime

addMonths(Integer)

Adds the specified number of months to a Datetime.

Signature

public Datetime addMonths(Integer addlMonths)

Parameters

addlMonths
Type: Integer

Return Value

Type: Datetime

addSeconds(Integer)

Adds the specified number of seconds to a Datetime.

Signature

public Datetime addSeconds(Integer addlSeconds)

Parameters

addlSeconds
Type: Integer

Return Value

Type: Datetime

addYears(Integer)

Adds the specified number of years to a Datetime.

Signature

public Datetime addYears(Integer addlYears)

Parameters

addlYears
Type: Integer

Return Value

Type: Datetime

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

dateGMT()

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

Signature

public Date dateGMT()

Return Value

Type: Date

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

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

dayGmt()

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

Signature

public Integer dayGmt()

Return Value

Type: Integer

Example

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

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 = 
2   datetime.newInstance
3    (2008, 2, 5, 8, 30, 12);
4system.assertEquals
5    (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

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

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

format(String)

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 dateFormat)

Parameters

dateFormat
Type: String

Return Value

Type: String

Usage

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

Example

1Datetime myDT = Datetime.now();
2String myDate = myDT.format('h:mm a');

format(String, String)

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 dateFormat, String timezone)

Parameters

dateFormat
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(String)

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

Signature

public String formatGmt(String dateFormat)

Parameters

dateFormat
Type: String

Return Value

Type: String

Usage

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

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 
2//   time zone
3Datetime dt = DateTime.newInstance(
4    2012,12,28,10,0,0);
5// Writes 12/28/2012 10:00:00 AM PST
6System.debug('dt.formatLong()=' 
7    + 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

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

hourGmt()

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

Signature

public Integer hourGmt()

Return Value

Type: Integer

isSameDay(Datetime)

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 compDt)

Parameters

compDt
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

millisecondGmt()

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

Signature

public Integer millisecondGmt()

Return Value

Type: Integer

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

minuteGmt()

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

Signature

public Integer minuteGmt()

Return Value

Type: Integer

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

monthGmt()

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

Signature

public Integer monthGmt()

Return Value

Type: Integer

newInstance(Long)

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.

newInstance(Date, Time)

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

Signature

public static Datetime newInstance(Date dt, Time tm)

Parameters

dt
Type: Date
tm
Type: Time

Return Value

Type: Datetime

The returned date is in the GMT time zone.

newInstance(Integer, Integer, Integer)

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 = 
2   datetime.newInstance(2008, 12, 1);

newInstance(Integer, Integer, Integer, Integer, Integer, Integer)

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 = 
2datetime.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 dt, Time tm)

Parameters

dt
Type: Date
tm
Type: Time

Return Value

Type: Datetime

newInstanceGmt(Integer, Integer, Integer)

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

newInstanceGmt(Integer, Integer, Integer, Integer, Integer, Integer)

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

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(String)

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

Signature

public static Datetime parse(String datetime)

Parameters

datetime
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.
1Datetime dt = DateTime.parse(
2              '10/14/2011 11:46 AM');
3String myDtString = dt.format();
4system.assertEquals(
5    myDtString,
6    '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

secondGmt()

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

Signature

public Integer secondGmt()

Return Value

Type: Integer

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

timeGmt()

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

Signature

public Time timeGmt()

Return Value

Type: Time

valueOf(String)

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

Signature

public static Datetime valueOf(String toDateTime)

Parameters

toDateTime
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
8 + '-' + day + ' ' + hour + ':' + 
9minute +  ':' + second;
10
11Datetime myDate = 
12   datetime.valueOf(stringDate);

valueOf(Object)

Converts the specified history tracking field value to a Datetime.

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

valueOfGmt(String)

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

Signature

public static Datetime valueOfGmt(String toDateTime)

Parameters

toDateTime
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.

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

yearGmt()

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

Signature

public Integer yearGmt()

Return Value

Type: Integer