com.chilkatsoft.chilkat2.DateTime

All Implemented Interfaces:: AutoCloseable

public class DateTime extends ChilkatObject

CkDateTime represents a date/time value and provides conversion methods for common date/time formats, including .NET DateTime, DateTime ticks, RFC 822, RFC 3339 / ISO 8601-style timestamps, Unix time, DOS date/time, OLE DATE, NTP time, ULID timestamps, and Chilkat DtObj. It also supports date arithmetic, age/expiration checks, serialization, and local/UTC conversion.

For an extended overview, see CkDateTime Class Overview

Instances hold a native Chilkat object: close them with ChilkatObject.close() (try-with-resources) when done; an unclosed instance is freed when it becomes unreachable.

See Also:: Online reference

Constructor Summary

Constructors

Constructor

Description

DateTime()

Creates a new DateTime object.
Method Summary

Modifier and Type

Method

Description

void

addDays(int numDays)

Adds an integer number of days to the date/time.

void

addSeconds(int numSeconds)

Adds an integer number of seconds to the date/time.

void

deSerialize(String serializedDateTime)

Loads the date/time with a string having the format as produced by the Serialize method, which is a string of SPACE separated integers containing (in this order) year, month, day, hour, minutes, seconds, and a UTC flag having the value of 1/0.

int

diffSeconds(DateTime dateTimeArg)

Returns the difference in seconds between the dateTimeArg and this date/time.

boolean

expiresWithin(int n, String units)

Returns true if the date/time is within n seconds/minutes/hours/days of the current system date/time.

long

getAsDateTimeTicks(boolean bLocal)

Returns the date/time as a 64-bit integer .NET DateTime value.

long

getAsDosDate(boolean bLocal)

Returns the date/time as a 32-bit DOS date/time bitmask.

String

getAsIso8601(String formatStr, boolean bLocal)

Returns the date/time in a compatible ISO 8601 format according to the format specified in formatStr..

double

getAsOleDate(boolean bLocal)

Returns the date/time in a Windows OLE DATE format.

String

getAsRfc822(boolean bLocal)

Returns the date/time as an RFC822 formatted string.

String

getAsTimestamp(boolean bLocal)

Returns the date/time as an RFC 3339 formatted string, such as 1990-12-31T23:59:60Z.

long

getAsUnixTime(boolean bLocal)

Returns the date/time as a Unix time value, which is the number of seconds elapsed since 00:00:00 UTC on January 1, 1970.

long

getAsUnixTime64(boolean bLocal)

The same as GetUnixTime, except returns the date/time as a 64-bit integer.

double

getAsUnixTimeDbl(boolean bLocal)

The same as GetUnixTime, except returns the date/time as a double.

String

getAsUnixTimeStr(boolean bLocal)

Returns the time in Unix format (in seconds since the epoch: 00:00:00 UTC on 1 January 1970).

int

getIsDst()

This is the Daylight Saving Time flag.

int

getUtcOffset()

For the current system's timezone, returns the number of seconds offset from UTC for this date/time.

boolean

olderThan(int n, String units)

Returns true if the date/time is older than the current system date/time by n seconds/minutes/hours/days.

String

serialize()

Serializes the date/time to a us-ascii string that can be imported at a later time via the DeSerialize method.

void

setFromCurrentSystemTime()

Sets the date/time from the current system time.

void

setFromDateTimeTicks(boolean bLocal, long ticks)

Sets the date/time from a .NET DateTime value represented in ticks.

void

setFromDosDate(boolean bLocal, long t)

Sets the date/time from a 32-bit DOS date/time bitmask.

void

setFromDtObj(DtObj dt)

Sets the date/time from a Chilkat Dt object.

void

setFromNtpServer(String jsonStr)

Sets the date/time by sending a query to an NTP server.

void

setFromNtpTime(int ntpSeconds)

Sets the date/time from a 32-bit NTP time value.

void

setFromOleDate(boolean bLocal, double dt)

Sets the date/time from a Windows OLE DATE value.

void

setFromRfc822(String rfc822Str)

Sets the date/time from an RFC822 date/time formatted string.

void

setFromTimestamp(String timestamp)

Sets the date/time from an RFC 3339 timestamp format.

void

setFromUlid(boolean bLocal, String ulid)

Sets this object's date/time using the timestamp embedded in the ulid.

void

setFromUnixTime(boolean bLocal, long t)

Sets the date/time from a UNIX time value.

void

setFromUnixTime64(boolean bLocal, long t)

The same as SetFromUnixTime, except that it uses a 64-bit integer to solve the Y2038 problem.

void

setFromUnixTimeDbl(boolean bLocal, double d)

The same as SetFromUnixTime, except that it uses a double to solve the Y2038 problem.

void

toDtObj(boolean bLocal, DtObj dtObj)

Copies the date/time to the dtObj.

String

ulidGenerate(boolean bLocal)

Generates and returns a new ULID using this object's date/time value.

void

ulidIncrement(StringBuilder ulid)

Increments the ULID that is passed in ulid.

void

ulidValidate(String ulid)

Validates the ulid.

Methods inherited from class com.chilkatsoft.chilkat2.ChilkatObject
close, getDebugLogFilePath, getLastErrorHtml, getLastErrorText, getLastErrorXml, getLastMethodSuccess, getVerboseLogging, getVersion, isClosed, setDebugLogFilePath, setLastMethodSuccess, setVerboseLogging, toString

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Details
- DateTime
  
  public DateTime()
  
  Creates a new DateTime object.
Method Details
- getIsDst
  
  public int getIsDst()
  
  This is the Daylight Saving Time flag. It can have one of three possible values: 1, 0, or -1. It has the value 1 if Daylight Saving Time is in effect, 0 if Daylight Saving Time is not in effect, and -1 if the information is not available.
  Note: This is NOT the DST for the current system time. It is the DST that was in effect at the date value contained in this object.
  
  Returns:
  
  the value of the IsDst property (read-only)
- getUtcOffset
  
  public int getUtcOffset()
  
  For the current system's timezone, returns the number of seconds offset from UTC for this date/time. The offset includes daylight savings adjustment. Local timezones west of UTC return a negative offset.
  
  Returns:
  
  the value of the UtcOffset property (read-only)
- addDays
  
  public void addDays(int numDays)
  
  Adds an integer number of days to the date/time. To subtract days, pass a negative integer.
  
  Parameters:
  
  numDays - the numDays argument
  
  Throws:
  
  ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why
- addSeconds
  
  public void addSeconds(int numSeconds)
  
  Adds an integer number of seconds to the date/time. To subtract seconds, pass a negative integer.
  
  Parameters:
  
  numSeconds - the numSeconds argument
  
  Throws:
  
  ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why
- deSerialize
  
  public void deSerialize(String serializedDateTime)
  
  Loads the date/time with a string having the format as produced by the Serialize method, which is a string of SPACE separated integers containing (in this order) year, month, day, hour, minutes, seconds, and a UTC flag having the value of 1/0.
  
  Parameters:
  
  serializedDateTime - the serializedDateTime argument (not null)
- diffSeconds
  
  public int diffSeconds(DateTime dateTimeArg)
  
  Returns the difference in seconds between the dateTimeArg and this date/time. The value returned is this object's date/time - dateTimeArg's date/time. For example, if the returned value is positive, then this object's date/time is more recent than dateTimeArg's date/time. If the return value is negative, then this object's date/time is older than dateTimeArg's date/time.
  
  Parameters:
  
  dateTimeArg - the dateTimeArg argument (not null)
  
  Returns:
  
  the result (see ChilkatObject.getLastMethodSuccess() where the description mentions failure)
- expiresWithin
  
  public boolean expiresWithin(int n, String units)
  
  Returns true if the date/time is within n seconds/minutes/hours/days of the current system date/time. Otherwise returns false. The units can be seconds, minutes, hours, or days (plural or singular).
  
  Parameters:
  
  n - the n argument
  
  units - the units argument (not null)
  
  Returns:
  
  the result; this method never throws ChilkatException
- getAsDateTimeTicks
  
  public long getAsDateTimeTicks(boolean bLocal)
  
  Returns the date/time as a 64-bit integer .NET DateTime value.
  bLocal indicates whether a local or UTC time is returned.
  This is a date and time expressed in the number of 100-nanosecond intervals that have elapsed since January 1, 0001 at 00:00:00.000 in the Gregorian calendar.
  The DateTime value type represents dates and times with values ranging from 12:00:00 midnight, January 1, 0001 Anno Domini (Common Era) through 11:59:59 P.M., December 31, 9999 A.D. (C.E.).
  Time values are measured in 100-nanosecond units called ticks, and a particular date is the number of ticks since 12:00 midnight, January 1, 0001 A.D. (C.E.) in the GregorianCalendar calendar (excluding ticks that would be added by leap seconds). For example, a ticks value of 31241376000000000L represents the date, Friday, January 01, 0100 12:00:00 midnight. A DateTime value is always expressed in the context of an explicit or default calendar.
  
  Parameters:
  
  bLocal - the bLocal argument
  
  Returns:
  
  the result (see ChilkatObject.getLastMethodSuccess() where the description mentions failure)
- getAsDosDate
  
  public long getAsDosDate(boolean bLocal)
  Returns the date/time as a 32-bit DOS date/time bitmask.
  bLocal indicates whether a local or UTC time is returned.
  The DOS date/time format is a bitmask:
  24 16 8 0 +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+ |Y|Y|Y|Y|Y|Y|Y|M| |M|M|M|D|D|D|D|D| |h|h|h|h|h|m|m|m| |m|m|m|s|s|s|s|s| +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+ \___________/\________/\_________/ \________/\____________/\_________/ year month day hour minute second
  
  The year is stored as an offset from 1980. Seconds are stored in two-second increments. (So if the second value is 15, it actually represents 30 seconds.)
  Parameters:
  
  bLocal - the bLocal argument
  
  Returns:
  
  the result (see ChilkatObject.getLastMethodSuccess() where the description mentions failure)
- getAsIso8601
  
  public String getAsIso8601(String formatStr, boolean bLocal)
  Returns the date/time in a compatible ISO 8601 format according to the format specified in formatStr.. Examples of ISO 8601 formats include the following:
  YYYY-MM-DD YYYY-MM-DDThh:mmTZD YYYY-MM-DDThh:mm:ssTZD YYYY-MM-DDThh:mm:ss:sssTZD
  
  For the date portion of these formats, YYYY is a four-digit year representation, MM is a two-digit month, and DD is a two-digit day. For the time portion, hh is the hour in 24-hour notation, mm is the two-digit minutes, ss is the two-digit seconds, and sss is the 3-digit milliseconds. A time designator T separates the date and time portions of the string, while a time zone designator TZD specifies a time zone (UTC).
  bLocal indicates whether a local or UTC time is returned.
  Parameters:
  
  formatStr - the formatStr argument (not null)
  
  bLocal - the bLocal argument
  
  Returns:
  
  the result (never null)
  
  Throws:
  
  ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why
- getAsOleDate
  
  public double getAsOleDate(boolean bLocal)
  
  Returns the date/time in a Windows OLE DATE format.
  bLocal indicates whether a local or UTC time is returned.
  The OLE automation date format is a floating point value, counting days since midnight 30 December 1899. Hours and minutes are represented as fractional days.
  
  Parameters:
  
  bLocal - the bLocal argument
  
  Returns:
  
  the result (see ChilkatObject.getLastMethodSuccess() where the description mentions failure)
- getAsRfc822
  
  public String getAsRfc822(boolean bLocal)
  
  Returns the date/time as an RFC822 formatted string. (An RFC822 format string is what is found in the Date header field of an email, such as Wed, 18 Oct 2017 09:08:21 GMT.)
  bLocal indicates whether a local or UTC time is returned.
  
  Parameters:
  
  bLocal - the bLocal argument
  
  Returns:
  
  the result (never null)
  
  Throws:
  
  ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why
- getAsTimestamp
  
  public String getAsTimestamp(boolean bLocal)
  
  Returns the date/time as an RFC 3339 formatted string, such as 1990-12-31T23:59:60Z. (This is an ISO 8061 format like the following: YYYY-MM-DDThh:mm:ssTZD)
  bLocal indicates whether a local or UTC time is returned.
  
  Parameters:
  
  bLocal - the bLocal argument
  
  Returns:
  
  the result (never null)
  
  Throws:
  
  ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why
- getAsUnixTime
  
  public long getAsUnixTime(boolean bLocal)
  
  Returns the date/time as a Unix time value, which is the number of seconds elapsed since 00:00:00 UTC on January 1, 1970.
  bLocal indicates whether the date/time returned is local or UTC.
  
  Parameters:
  
  bLocal - the bLocal argument
  
  Returns:
  
  the result (see ChilkatObject.getLastMethodSuccess() where the description mentions failure)
- getAsUnixTime64
  
  public long getAsUnixTime64(boolean bLocal)
  
  The same as GetUnixTime, except returns the date/time as a 64-bit integer.
  bLocal indicates whether a local or UTC time is returned.
  Note: 64-bit integers are needed after Jan 19, 2038. The Y2038 problem happens because some systems store Unix time as a signed 32-bit number of seconds since Jan 1, 1970. This number runs out on Jan 19, 2038, causing the time to wrap around to a date in 1901.
  
  Parameters:
  
  bLocal - the bLocal argument
  
  Returns:
  
  the result (see ChilkatObject.getLastMethodSuccess() where the description mentions failure)
- getAsUnixTimeDbl
  
  public double getAsUnixTimeDbl(boolean bLocal)
  
  The same as GetUnixTime, except returns the date/time as a double.
  bLocal indicates whether a local or UTC time is returned.
  
  Parameters:
  
  bLocal - the bLocal argument
  
  Returns:
  
  the result (see ChilkatObject.getLastMethodSuccess() where the description mentions failure)
- getAsUnixTimeStr
  
  public String getAsUnixTimeStr(boolean bLocal)
  
  Returns the time in Unix format (in seconds since the epoch: 00:00:00 UTC on 1 January 1970).
  bLocal indicates whether the date/time returned is local or UTC.
  
  Parameters:
  
  bLocal - the bLocal argument
  
  Returns:
  
  the result (never null)
  
  Throws:
  
  ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why
- olderThan
  
  public boolean olderThan(int n, String units)
  
  Returns true if the date/time is older than the current system date/time by n seconds/minutes/hours/days. Otherwise returns false. The units can be seconds, minutes, hours, or days (plural or singular).
  
  Parameters:
  
  n - the n argument
  
  units - the units argument (not null)
  
  Returns:
  
  the result; this method never throws ChilkatException
- serialize
  
  public String serialize()
  
  Serializes the date/time to a us-ascii string that can be imported at a later time via the DeSerialize method. The format of the string returned by this method is not intended to match any published standard. It is formatted to a string with SPACE separated integers containing (in this order) year, month, day, hour, minutes, seconds, and a UTC flag having the value of 1 or 0.
  
  Returns:
  
  the result (never null)
  
  Throws:
  
  ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why
- setFromCurrentSystemTime
  
  public void setFromCurrentSystemTime()
  
  Sets the date/time from the current system time.
  
  Throws:
  
  ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why
- setFromDateTimeTicks
  
  public void setFromDateTimeTicks(boolean bLocal, long ticks)
  
  Sets the date/time from a .NET DateTime value represented in ticks. See GetAsDateTimeTicks for more information.
  bLocal indicates whether the passed in date/time is local or UTC.
  
  Parameters:
  
  bLocal - the bLocal argument
  
  ticks - the ticks argument
  
  Throws:
  
  ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why
- setFromDosDate
  
  public void setFromDosDate(boolean bLocal, long t)
  
  Sets the date/time from a 32-bit DOS date/time bitmask. See GetAsDosDate for more information.
  
  Parameters:
  
  bLocal - the bLocal argument
  
  t - the t argument (0 .. 4294967295)
  
  Throws:
  
  ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why
- setFromDtObj
  
  public void setFromDtObj(DtObj dt)
  
  Sets the date/time from a Chilkat Dt object.
  
  Parameters:
  
  dt - the dt argument (not null)
  
  Throws:
  
  ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why
- setFromNtpServer
  
  public void setFromNtpServer(String jsonStr)
  
  Sets the date/time by sending a query to an NTP server.
  
  Parameters:
  
  jsonStr - the jsonStr argument (not null)
  
  Throws:
  
  ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why
- setFromNtpTime
  
  public void setFromNtpTime(int ntpSeconds)
  
  Sets the date/time from a 32-bit NTP time value. ntpSeconds is the number of seconds since 00:00 (midnight) 1 January 1900 GMT.
  
  Parameters:
  
  ntpSeconds - the ntpSeconds argument
  
  Throws:
  
  ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why
- setFromOleDate
  
  public void setFromOleDate(boolean bLocal, double dt)
  
  Sets the date/time from a Windows OLE DATE value.
  bLocal indicates whether the passed in date/time is local or UTC.
  Note: This method was not working correctly. The problem was discovered just after releasing v9.5.0.65. It will be fixed in the next version update.
  
  Parameters:
  
  bLocal - the bLocal argument
  
  dt - the dt argument
  
  Throws:
  
  ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why
- setFromRfc822
  
  public void setFromRfc822(String rfc822Str)
  Sets the date/time from an RFC822 date/time formatted string. Here are some examples of RFC822 formatted date/times:
  Tue, 15 Nov 2022 22:00:58 +0000 Tue, 15 Nov 2022 20:21:50 +0100 Tue, 01 Nov 2022 18:09:41 -0600
  Parameters:
  
  rfc822Str - the rfc822Str argument (not null)
  
  Throws:
  
  ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why
- setFromTimestamp
  
  public void setFromTimestamp(String timestamp)
  
  Sets the date/time from an RFC 3339 timestamp format. (such as 1990-12-31T23:59:60Z:)
  (This is an ISO 8061 format like the following: YYYY-MM-DDThh:mm:ssTZD)
  Note: Starting in v9.5.0.77, strings formatted as YYMMDDhhmmssZ, such as 181221132225Z, can also be passed to this method.
  
  Parameters:
  
  timestamp - the timestamp argument (not null)
  
  Throws:
  
  ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why
- setFromUlid
  
  public void setFromUlid(boolean bLocal, String ulid)
  
  Sets this object's date/time using the timestamp embedded in the ulid. If the ulid was not a valid ULID, returns false and the date/time is not set. bLocal indicates whether the ulid uses a local time or UTC time.
  
  Parameters:
  
  bLocal - the bLocal argument
  
  ulid - the ulid argument (not null)
  
  Throws:
  
  ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why
- setFromUnixTime
  
  public void setFromUnixTime(boolean bLocal, long t)
  
  Sets the date/time from a UNIX time value.
  bLocal indicates whether the passed in date/time is local or UTC.
  
  Parameters:
  
  bLocal - the bLocal argument
  
  t - the t argument (0 .. 4294967295)
  
  Throws:
  
  ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why
- setFromUnixTime64
  
  public void setFromUnixTime64(boolean bLocal, long t)
  
  The same as SetFromUnixTime, except that it uses a 64-bit integer to solve the Y2038 problem.
  bLocal indicates whether the passed in date/time is local or UTC.
  Note: 64-bit integers are needed after Jan 19, 2038. The Y2038 problem happens because some systems store Unix time as a signed 32-bit number of seconds since Jan 1, 1970. This number runs out on Jan 19, 2038, causing the time to wrap around to a date in 1901.
  
  Parameters:
  
  bLocal - the bLocal argument
  
  t - the t argument
  
  Throws:
  
  ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why
- setFromUnixTimeDbl
  
  public void setFromUnixTimeDbl(boolean bLocal, double d)
  
  The same as SetFromUnixTime, except that it uses a double to solve the Y2038 problem. (See GetAsUnixTime for more information about Y2038).
  bLocal indicates whether the passed in date/time is local or UTC.
  
  Parameters:
  
  bLocal - the bLocal argument
  
  d - the d argument
  
  Throws:
  
  ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why
- toDtObj
  
  public void toDtObj(boolean bLocal, DtObj dtObj)
  
  Copies the date/time to the dtObj. Gets the date/time in the local time if bLocal is true, or GMT if bLocal is false.
  
  Parameters:
  
  bLocal - the bLocal argument
  
  dtObj - the dtObj argument (not null)
- ulidGenerate
  
  public String ulidGenerate(boolean bLocal)
  
  Generates and returns a new ULID using this object's date/time value. bLocal indicates whether to use local time or UTC time.
  
  Parameters:
  
  bLocal - the bLocal argument
  
  Returns:
  
  the result (never null)
  
  Throws:
  
  ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why
- ulidIncrement
  
  public void ulidIncrement(StringBuilder ulid)
  
  Increments the ULID that is passed in ulid.
  
  Parameters:
  
  ulid - the ulid argument (not null)
  
  Throws:
  
  ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why
- ulidValidate
  
  public void ulidValidate(String ulid)
  
  Validates the ulid. Returns true if the ulid is valid, otherwise returns false.
  
  Parameters:
  
  ulid - the ulid argument (not null)
  
  Throws:
  
  ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

Class DateTime

Constructor Summary

Method Summary

Methods inherited from class com.chilkatsoft.chilkat2.ChilkatObject

Methods inherited from class java.lang.Object

Constructor Details

DateTime

Method Details

getIsDst

getUtcOffset

addDays

addSeconds

deSerialize

diffSeconds

expiresWithin

getAsDateTimeTicks

getAsDosDate

getAsIso8601

getAsOleDate

getAsRfc822

getAsTimestamp

getAsUnixTime

getAsUnixTime64

getAsUnixTimeDbl

getAsUnixTimeStr

olderThan

serialize

setFromCurrentSystemTime

setFromDateTimeTicks

setFromDosDate

setFromDtObj

setFromNtpServer

setFromNtpTime

setFromOleDate

setFromRfc822

setFromTimestamp

setFromUlid

setFromUnixTime

setFromUnixTime64

setFromUnixTimeDbl

toDtObj

ulidGenerate

ulidIncrement

ulidValidate