turbocommons-ts

/** * TurboCommons is a general purpose and cross-language library that implements frequently used and generic software development tasks. * * Website : -> https://turboframework.org/en/libs/turbocommons * License : -> Licensed under the Apache License, Version 2.0. You may not use this file except in compliance with the License. * License Url : -> http://www.apache.org/licenses/LICENSE-2.0 * CopyRight : -> Copyright 2015 Edertone Advanded Solutions (08211 Castellar del Vallès, Barcelona). http://www.edertone.com */ /** * 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 */ export declare class DateTimeObject { /** * String that defines the ISO 8601 format to be used internally when calling the format method on DateTime Php class. */ /** * The date and time values that are stored on this instance are saved as an ISO 8601 string */ private _dateTimeString; /** * An exploded version of this instance _dateTimeString ISO string, that is used to improve performance when reading * some of the date values */ private _dateTimeStringExploded; /** * 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. * * @param dateTimeString 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. * * @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 * * @return The created instance */ constructor(dateTimeString?: string); /** * 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. * * @param dateTime A string containing a valid ISO 8601 date/time value or a valid DateTimeObject instance. * * @see DateTimeObject.constructor() * * @return true if the specified value is ISO 8601 or a DateTimeObject instance, false if value contains invalid information. */ static isValidDateTime(dateTime: string | DateTimeObject): boolean; /** * Given two valid dateTime values, this method will check if they represent the same date and time value * * @param dateTime1 A valid ISO 8601 dateTime string or a DateTimeObject instance. * @param dateTime2 A valid ISO 8601 dateTime string or a DateTimeObject instance. * * @see DateTimeObject.__constructor() * * @return True if the date and time values on both elements are the same */ static isEqual(dateTime1: string | DateTimeObject, dateTime2: string | DateTimeObject): boolean; /** * Returns the month name from a numeric month value * * @param month A month number between 1 and 12 * * @return the month name in english and with capital letters, like: JANUARY, FEBRUARY, ... */ static getMonthName(month: 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 ... * * @param day A day number between 1 and 7 * * @return The day name in english and with capital letters, like for example: MONDAY, SATURDAY... */ static getDayName(day: number): string; /** * Get the year based on current system date and timezone * * @return A numeric value representing the current year */ static getCurrentYear(): number; /** * Get the month based on current system date and timezone as a numeric value from 1 to 12 * * @return A value between 1 and 12 */ static getCurrentMonth(): number; /** * Get the day based on current system date and timezone as a numeric value from 1 to 31 * * @return The day of month as a value between 1 and 31 */ static getCurrentDay(): number; /** * 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 ... * * @return A numeric value between 1 and 7 (where Sunday is 1, Monday is 2, ...) */ static getCurrentDayOfWeek(): void; /** * Get the hour based on current system date and timezone as a numeric value from 0 to 23 * * @return The hour as a value between 0 and 23 */ static getCurrentHour(): number; /** * Get the minute based on current system date and timezone as a numeric value from 0 to 59 * * @return The minute as a value between 0 and 59 */ static getCurrentMinute(): number; /** * Get the seconds based on current system date and timezone as a numeric value from 0 to 59 * * @return The seconds as a value between 0 and 59 */ static getCurrentSecond(): number; /** * Get the miliseconds based on current system date and timezone as a numeric value up to 3 digits * * @return The miliseconds as a value up to 3 digits */ static getCurrentMiliSecond(): number; /** * Get the microseconds based on current system date and timezone as a numeric value up to 6 digits * * @return The microseconds as a value up to 6 digits */ static getCurrentMicroSecond(): void; /** * Get the timezone offset based on current system date and timezone as a numeric value (in seconds) * * @return The timezone offset as a numeric value in seconds */ static getCurrentTimeZoneOffset(): number; /** * 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. * * @param dateTime1 A valid ISO 8601 dateTime value or a DateTimeObject instance. * @param dateTime2 A valid ISO 8601 dateTime value or a DateTimeObject instance. * * @throws UnexpectedValueException * * @return 0 If the two dateTime values represent the exact same time, 1 if dateTime1 > dateTime2 or 2 if dateTime2 > dateTime1 */ static compare(dateTime1: string | DateTimeObject, dateTime2: string | DateTimeObject): 1 | 0 | 2; /** * Get this instance's defined year as a numeric value * * @return A 4 digits numeric value */ getYear(): number; /** * Get this instance's defined month as a numeric value from 1 to 12 * * @return A value between 1 and 12 */ getMonth(): number; /** * Get this instance's defined day as a numeric value from 1 to 31 * * @return A value between 1 and 31 */ getDay(): number; /** * 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 ... * * @return A numeric value between 1 and 7 */ getDayOfWeek(): void; /** * Get this instance's defined hour as a numeric value from 0 to 23 * * @return A value between 0 and 23 */ getHour(): number; /** * Get this instance's defined minute as a numeric value from 0 to 59 * * @return A value between 0 and 59 */ getMinute(): number; /** * Get this instance's defined second as a numeric value from 0 to 59 * * @return A value between 0 and 59 */ getSecond(): number; /** * Get this instance's defined miliseconds as a numeric value up to 3 digit * * @return A value up to 3 digit */ getMiliSecond(): number; /** * Get this instance's defined microseconds as a numeric value up to 6 digit * * @return A value up to 6 digit */ getMicroSecond(): number; /** * Get this instance's defined timezone offset as a numeric value (in seconds) * * @return The UTC timezone offset in seconds */ getTimeZoneOffset(): number; /** * Get the first day of month for the current dateTime value. * * @return A dateTime object representing the first day of month based on the current instance */ getFirstDayOfMonth(): void; /** * Get the last day of month for the current dateTime value. * * @return A dateTime object representing the last day of month based on the current instance */ getLastDayOfMonth(): void; /** * Convert the current instance date and time values to the specified timezone offset. * * @param offset One of the supported timezone names or an offset value (+0200, +05:00, -0300, -03:00, etc...) * * @return This object instance */ /** * Convert the current instance date and time values to the local timezone offset. * * @return This object instance */ setLocalTimeZone(): void; /** * Check if the current instance timezone is the UTC +00:00 value * * @return True if the instance timezone is UTC, false if not */ isUTC(): boolean; /** * 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) * * @return This object instance */ setUTC(): this; /** * Output the current dateTime instance data as a custom formatted string (by default a full ISO 8601 string). * * @param formatString 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) * * @return The dateTime with the specified format. */ toString(formatString?: string): string; /** * 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. * * @param dateTime A valid ISO 8601 dateTime value or a DateTimeObject instance. * * @throws Error * * @see DateTimeObject.compare * * @return 0 If the two dateTime values represent the exact same time, 1 if this instance > dateTime or 2 if dateTime > this instance */ compareTo(dateTime: string | DateTimeObject): 1 | 0 | 2; /** * Check if the provided ISO 8601 dateTime value is identical to the date and time from this instance * * @param dateTime A valid ISO 8601 dateTime string or a DateTimeObject instance. * * @return True if both dateTime values are equivalent to the exact same date and time */ isEqualTo(dateTime: string | DateTimeObject): boolean; /** * Adds the specified amount of time to the given dateTime value * TODO - This method currently only works with years, and PHPDoc is incomplete! * * @param value The numeric amount that will be added to this DateTimeObject instance * @param type TODO - this paramenter description * * @return void */ /** * TODO - this method depends on this.add for being finished */ /** * Auxiliary method that is used to generate an array with all the values that are defined on an ISO 8601 string * * @param string A valid ISO 8601 string * * @return An array with all the date time values extracted */ private _explodeISO8601String; }