Options
All
  • Public
  • Public/Protected
  • All
Menu

Class DateTimeObject

date and time format object abstraction based on ISO 8601 standard TODO - This is a first implementation of this class which must be strictly tested and completed by taking the php version as a reference

Hierarchy

  • DateTimeObject

Index

Constructors

Properties

Methods

Constructors

constructor

  • Object that represents a date and time value with timezone and its related operations.

    All the class methods are based and expect values that follow the ISO 8601 format, which is the international standard for the representation of dates and times. Any other date/time format will be considered as invalid.

    Following is an example of a valid ISO 8601 dateTime value:

    yyyy-mm-ddTHH:MM:SS.UUU+TT:TT

    where:

    • yyyy is a four digits year value
    • mm is a two digits month value
    • dd is a two digits day value
    • HH is a two digits hour value
    • MM is a two digits minutes value
    • SS is a two digits seconds value
    • UUU is an arbitrary number of digits decimal seconds fraction value
    • +TT:TT is the timezone offset value, like +03:00

    IMPORTANT: It is highly recommended to always physically store your datetime values as UTC (aka 00 timezone offset). The local timezone offset should be applied only when showing the datetime values to the user. All the other date and time usages of your application should be performed with UTC values.

    example

    '1996' Will create a DateTimeObject with the value '1996-01-01T00:00:00.000000+00:00' based on the UTC 00 timezone

    example

    '1996-12' Will create a DateTimeObject with the value '1996-12-01T00:00:00.000000+00:00' based on the UTC 00 timezone

    example

    This is a fully valid ISO 8601 string value: '2017-10-14T17:55:25.163583+02:00'

    see

    https://es.wikipedia.org/wiki/ISO_8601

    Parameters

    • Default value dateTimeString: string = ""

      A string containing a valid ISO 8601 date/time value that will be used to initialize this instance. If string is empty, the current system date/time WITH UTC TIMEZONE will be used. If string is incomplete, all missing parts will be filled with the lowest possible value. If timezone offset is missing, UTC will be used.

    Returns DateTimeObject

    The created instance

Properties

Private _dateTimeString

_dateTimeString: string = ""

The date and time values that are stored on this instance are saved as an ISO 8601 string

Private _dateTimeStringExploded

_dateTimeStringExploded: string[] = []

An exploded version of this instance _dateTimeString ISO string, that is used to improve performance when reading some of the date values

Methods

Private _explodeISO8601String

  • _explodeISO8601String(string: string): string[]

  • Auxiliary method that is used to generate an array with all the values that are defined on an ISO 8601 string

    Parameters

    • string: string

      A valid ISO 8601 string

    Returns string[]

    An array with all the date time values extracted

compareTo

  • Compares the current datetime instance value to the given one and tells if they are exactly the same or which one represents a later time value than the other. Timezones from the both dateTime values are taken into consideration for the comparison.

    throws

    Error

    see

    DateTimeObject.compare

    Parameters

    • dateTime: string | DateTimeObject

      A valid ISO 8601 dateTime value or a DateTimeObject instance.

    Returns 0 | 1 | 2

    0 If the two dateTime values represent the exact same time, 1 if this instance > dateTime or 2 if dateTime > this instance

getDay

  • getDay(): number

  • Get this instance's defined day as a numeric value from 1 to 31

    Returns number

    A value between 1 and 31

getDayOfWeek

  • getDayOfWeek(): void

  • Get this instance's defined day of week as a numeric value from 1 to 7, where Sunday is considered to be the first one:
    1 = Sunday, 2 = Monday, 3 = Tuesday, etc ...

    Returns void

    A numeric value between 1 and 7

getFirstDayOfMonth

  • getFirstDayOfMonth(): void

  • Get the first day of month for the current dateTime value.

    Returns void

    A dateTime object representing the first day of month based on the current instance

getHour

  • getHour(): number

  • Get this instance's defined hour as a numeric value from 0 to 23

    Returns number

    A value between 0 and 23

getLastDayOfMonth

  • getLastDayOfMonth(): void

  • Get the last day of month for the current dateTime value.

    Returns void

    A dateTime object representing the last day of month based on the current instance

getMicroSecond

  • getMicroSecond(): number

  • Get this instance's defined microseconds as a numeric value up to 6 digit

    Returns number

    A value up to 6 digit

getMiliSecond

  • getMiliSecond(): number

  • Get this instance's defined miliseconds as a numeric value up to 3 digit

    Returns number

    A value up to 3 digit

getMinute

  • getMinute(): number

  • Get this instance's defined minute as a numeric value from 0 to 59

    Returns number

    A value between 0 and 59

getMonth

  • getMonth(): number

  • Get this instance's defined month as a numeric value from 1 to 12

    Returns number

    A value between 1 and 12

getSecond

  • getSecond(): number

  • Get this instance's defined second as a numeric value from 0 to 59

    Returns number

    A value between 0 and 59

getTimeZoneOffset

  • getTimeZoneOffset(): number

  • Get this instance's defined timezone offset as a numeric value (in seconds)

    Returns number

    The UTC timezone offset in seconds

getYear

  • getYear(): number

  • Get this instance's defined year as a numeric value

    Returns number

    A 4 digits numeric value

isEqualTo

  • Check if the provided ISO 8601 dateTime value is identical to the date and time from this instance

    Parameters

    • dateTime: string | DateTimeObject

      A valid ISO 8601 dateTime string or a DateTimeObject instance.

    Returns boolean

    True if both dateTime values are equivalent to the exact same date and time

isUTC

  • isUTC(): boolean

  • Check if the current instance timezone is the UTC +00:00 value

    Returns boolean

    True if the instance timezone is UTC, false if not

setLocalTimeZone

  • setLocalTimeZone(): void

  • Convert the current instance date and time values to the local timezone offset.

    Returns void

    This object instance

setUTC

  • setUTC(): this

  • Convert the current instance date and time values to the UTC zero timezone offset.

    example

    If this instance contains a +02:00 timezone offset, after calling this method the offset will be +00:00 (date and time will be updated accordingly)

    Returns this

    This object instance

toString

  • toString(formatString?: string): string

  • Output the current dateTime instance data as a custom formatted string (by default a full ISO 8601 string).

    Parameters

    • Default value formatString: string = "Y-M-DTH:N:S.UOffset"

      A string containing the output format like 'd/m/Y' or 'm-d-y' where the following characters will be automatically replaced:

      • Y with a four digit year value
      • y with a one or two digit year value
      • M with a two digit month value
      • m with a one or two digit month value
      • D with a two digit day value
      • d with a one or two digit day value
      • H with a two digit hour value
      • h with a one or two digit hour value
      • N with a two digit minutes value
      • n with a one or two digit minutes value
      • S with a two digit seconds value
      • s with a one or two digit seconds value
      • U with a 6 digit microseconds value
      • u with a 3 digit miliseconds value
      • Offset with the timezone offset value (including the + or - symbol)

    Returns string

    The dateTime with the specified format.

Static compare

  • This method compares two dateTime values and tells if they are exactly the same or which one represents a later time value than the other. Timezones from the specified dateTime values are taken into consideration for the comparison.

    throws

    UnexpectedValueException

    Parameters

    • dateTime1: string | DateTimeObject

      A valid ISO 8601 dateTime value or a DateTimeObject instance.

    • dateTime2: string | DateTimeObject

      A valid ISO 8601 dateTime value or a DateTimeObject instance.

    Returns 0 | 1 | 2

    0 If the two dateTime values represent the exact same time, 1 if dateTime1 > dateTime2 or 2 if dateTime2 > dateTime1

Static getCurrentDay

  • getCurrentDay(): number

  • Get the day based on current system date and timezone as a numeric value from 1 to 31

    Returns number

    The day of month as a value between 1 and 31

Static getCurrentDayOfWeek

  • getCurrentDayOfWeek(): void

  • Get the numeric day of week (between 1 and 7) based on current system time, where Sunday is considered to be the first one:
    1 = Sunday, 2 = Monday, 3 = Tuesday, etc ...

    Returns void

    A numeric value between 1 and 7 (where Sunday is 1, Monday is 2, ...)

Static getCurrentHour

  • getCurrentHour(): number

  • Get the hour based on current system date and timezone as a numeric value from 0 to 23

    Returns number

    The hour as a value between 0 and 23

Static getCurrentMicroSecond

  • getCurrentMicroSecond(): void

  • Get the microseconds based on current system date and timezone as a numeric value up to 6 digits

    Returns void

    The microseconds as a value up to 6 digits

Static getCurrentMiliSecond

  • getCurrentMiliSecond(): number

  • Get the miliseconds based on current system date and timezone as a numeric value up to 3 digits

    Returns number

    The miliseconds as a value up to 3 digits

Static getCurrentMinute

  • getCurrentMinute(): number

  • Get the minute based on current system date and timezone as a numeric value from 0 to 59

    Returns number

    The minute as a value between 0 and 59

Static getCurrentMonth

  • getCurrentMonth(): number

  • Get the month based on current system date and timezone as a numeric value from 1 to 12

    Returns number

    A value between 1 and 12

Static getCurrentSecond

  • getCurrentSecond(): number

  • Get the seconds based on current system date and timezone as a numeric value from 0 to 59

    Returns number

    The seconds as a value between 0 and 59

Static getCurrentTimeZoneOffset

  • getCurrentTimeZoneOffset(): number

  • Get the timezone offset based on current system date and timezone as a numeric value (in seconds)

    Returns number

    The timezone offset as a numeric value in seconds

Static getCurrentYear

  • getCurrentYear(): number

  • Get the year based on current system date and timezone

    Returns number

    A numeric value representing the current year

Static getDayName

  • getDayName(day: number): string

  • Get the english name representing the given numeric value of a week day (between 1 and 7), where Sunday is considered to be the first one: 1 = Sunday, 2 = Monday, 3 = Tuesday, etc ...

    Parameters

    • day: number

      A day number between 1 and 7

    Returns string

    The day name in english and with capital letters, like for example: MONDAY, SATURDAY...

Static getMonthName

  • getMonthName(month: number): string

  • Returns the month name from a numeric month value

    Parameters

    • month: number

      A month number between 1 and 12

    Returns string

    the month name in english and with capital letters, like: JANUARY, FEBRUARY, ...

Static isEqual

  • Given two valid dateTime values, this method will check if they represent the same date and time value

    see

    DateTimeObject.__constructor()

    Parameters

    • dateTime1: string | DateTimeObject

      A valid ISO 8601 dateTime string or a DateTimeObject instance.

    • dateTime2: string | DateTimeObject

      A valid ISO 8601 dateTime string or a DateTimeObject instance.

    Returns boolean

    True if the date and time values on both elements are the same

Static isValidDateTime

  • DateTimeObject class operates only with ISO 8601 strings, which is the international standard for the representation of dates and times. Therefore, this method considers a dateTime string value to be valid only if it is a string that follows that standard or a DateTimeObject instance.

    see

    DateTimeObject.constructor()

    Parameters

    • dateTime: string | DateTimeObject

      A string containing a valid ISO 8601 date/time value or a valid DateTimeObject instance.

    Returns boolean

    true if the specified value is ISO 8601 or a DateTimeObject instance, false if value contains invalid information.

Generated using TypeDoc