Skip to content

Commit

Permalink
Fixed documentation by adding a few references to wikipedia articles.
Browse files Browse the repository at this point in the history
  • Loading branch information
David Aguilera committed Mar 27, 2020
1 parent 4ce862d commit c3d5fe4
Show file tree
Hide file tree
Showing 2 changed files with 65 additions and 41 deletions.
14 changes: 12 additions & 2 deletions packages/date/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,11 +20,16 @@ _This package assumes that your code will run in an **ES2015+** environment. If

Formats a date (like `date()` in PHP).

_Related_

- {@link <https://en.wikipedia.org/wiki/List_of_tz_database_time_zones|Timezones}>
- {@link <https://en.wikipedia.org/wiki/ISO_8601#Time_offsets_from_UTC|UTC> Offsets}

_Parameters_

- _dateFormat_ `string`: PHP-style formatting string. See php.net/date.
- _dateValue_ `(Date|string|Moment|null)`: Date object or string, parsable by moment.js.
- _timezone_ `(string|number|null)`: Timezone to output result in or a UTC offset. Defaults to timezone from site. See momentjs.com.
- _timezone_ `(string|number|null)`: Timezone to output result in or a UTC offset. Defaults to timezone from site.

_Returns_

Expand All @@ -37,11 +42,16 @@ Formats a date (like `wp_date()` in PHP), translating it into site's locale.
Backward Compatibility Notice: if `timezone` is set to `true`, the function
behaves like `gmdateI18n`.

_Related_

- {@link <https://en.wikipedia.org/wiki/List_of_tz_database_time_zones|Timezones}>
- {@link <https://en.wikipedia.org/wiki/ISO_8601#Time_offsets_from_UTC|UTC> Offsets}

_Parameters_

- _dateFormat_ `string`: PHP-style formatting string. See php.net/date.
- _dateValue_ `(Date|string|Moment|null)`: Date object or string, parsable by moment.js.
- _timezone_ `(string|number|null)`: Timezone to output result in or a UTC offset. Defaults to timezone from site. See momentjs.com.
- _timezone_ `(string|number|boolean|null)`: Timezone to output result in or a UTC offset. Defaults to timezone from site. Notice: `boolean` is effectively deprecated, but still supported for backward compatibility reasons.

_Returns_

Expand Down
92 changes: 53 additions & 39 deletions packages/date/src/index.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,10 @@ import 'moment-timezone/moment-timezone-utils';

const WP_ZONE = 'WP';

// This regular expression tests positive for UTC offsets as described in ISO 8601.
// See: https://en.wikipedia.org/wiki/ISO_8601#Time_offsets_from_UTC
const VALID_UTC_OFFSET = /^[+-][0-1][0-9](:?[0-9][0-9])?$/;

// Changes made here will likely need to be made in `lib/client-assets.php` as
// well because it uses the `setSettings()` function to change these settings.
let settings = {
Expand Down Expand Up @@ -318,10 +322,10 @@ const formatMap = {
/**
* Formats a date. Does not alter the date's timezone.
*
* @param {string} dateFormat PHP-style formatting string.
* See php.net/date.
* @param {(Date|string|Moment|null)} dateValue Date object or string,
* parsable by moment.js.
* @param {string} dateFormat PHP-style formatting string.
* See php.net/date.
* @param {Date|string|Moment|null} dateValue Date object or string,
* parsable by moment.js.
*
* @return {string} Formatted date.
*/
Expand Down Expand Up @@ -359,14 +363,16 @@ export function format( dateFormat, dateValue = new Date() ) {
/**
* Formats a date (like `date()` in PHP).
*
* @param {string} dateFormat PHP-style formatting string.
* See php.net/date.
* @param {(Date|string|Moment|null)} dateValue Date object or string, parsable
* by moment.js.
* @param {(string|number|null)} timezone Timezone to output result in or
* a UTC offset.
* Defaults to timezone from site.
* See momentjs.com.
* @param {string} dateFormat PHP-style formatting string.
* See php.net/date.
* @param {Date|string|Moment|null} dateValue Date object or string, parsable
* by moment.js.
* @param {string|number|null} timezone Timezone to output result in or a
* UTC offset. Defaults to timezone from
* site.
*
* @see {@link https://en.wikipedia.org/wiki/List_of_tz_database_time_zones|Timezones}
* @see {@link https://en.wikipedia.org/wiki/ISO_8601#Time_offsets_from_UTC|UTC Offsets}
*
* @return {string} Formatted date in English.
*/
Expand All @@ -378,10 +384,10 @@ export function date( dateFormat, dateValue = new Date(), timezone ) {
/**
* Formats a date (like `date()` in PHP), in the UTC timezone.
*
* @param {string} dateFormat PHP-style formatting string.
* See php.net/date.
* @param {(Date|string|Moment|null)} dateValue Date object or string,
* parsable by moment.js.
* @param {string} dateFormat PHP-style formatting string.
* See php.net/date.
* @param {Date|string|Moment|null} dateValue Date object or string,
* parsable by moment.js.
*
* @return {string} Formatted date in English.
*/
Expand All @@ -396,14 +402,18 @@ export function gmdate( dateFormat, dateValue = new Date() ) {
* Backward Compatibility Notice: if `timezone` is set to `true`, the function
* behaves like `gmdateI18n`.
*
* @param {string} dateFormat PHP-style formatting string.
* See php.net/date.
* @param {(Date|string|Moment|null)} dateValue Date object or string,
* parsable by moment.js.
* @param {(string|number|null)} timezone Timezone to output result in or
* a UTC offset.
* Defaults to timezone from site.
* See momentjs.com.
* @param {string} dateFormat PHP-style formatting string.
* See php.net/date.
* @param {Date|string|Moment|null} dateValue Date object or string, parsable by
* moment.js.
* @param {string|number|boolean|null} timezone Timezone to output result in or a
* UTC offset. Defaults to timezone from
* site. Notice: `boolean` is effectively
* deprecated, but still supported for
* backward compatibility reasons.
*
* @see {@link https://en.wikipedia.org/wiki/List_of_tz_database_time_zones|Timezones}
* @see {@link https://en.wikipedia.org/wiki/ISO_8601#Time_offsets_from_UTC|UTC Offsets}
*
* @return {string} Formatted date.
*/
Expand All @@ -412,6 +422,10 @@ export function dateI18n( dateFormat, dateValue = new Date(), timezone ) {
return gmdateI18n( dateFormat, dateValue );
}

if ( false === timezone ) {
timezone = undefined;
}

const dateMoment = buildMoment( dateValue, timezone );
dateMoment.locale( settings.l10n.locale );
return format( dateFormat, dateMoment );
Expand All @@ -421,10 +435,10 @@ export function dateI18n( dateFormat, dateValue = new Date(), timezone ) {
* Formats a date (like `wp_date()` in PHP), translating it into site's locale
* and using the UTC timezone.
*
* @param {string} dateFormat PHP-style formatting string.
* See php.net/date.
* @param {(Date|string|Moment|null)} dateValue Date object or string,
* parsable by moment.js.
* @param {string} dateFormat PHP-style formatting string.
* See php.net/date.
* @param {Date|string|Moment|null} dateValue Date object or string,
* parsable by moment.js.
*
* @return {string} Formatted date.
*/
Expand Down Expand Up @@ -466,15 +480,18 @@ export function getDate( dateString ) {
/**
* Creates a moment instance using the given timezone or, if none is provided, using global settings.
*
* @param {(Date|string|Moment|null)} dateValue Date object or string, parsable
* by moment.js.
* @param {(string|number|null)} timezone Timezone to output result in or
* a UTC offset.
* Defaults to timezone from site.
* See momentjs.com.
* @return {Moment} a moment instance.
* @param {Date|string|Moment|null} dateValue Date object or string, parsable
* by moment.js.
* @param {string|number|null} timezone Timezone to output result in or a
* UTC offset. Defaults to timezone from
* site.
*
* @see {@link https://en.wikipedia.org/wiki/List_of_tz_database_time_zones|Timezones}
* @see {@link https://en.wikipedia.org/wiki/ISO_8601#Time_offsets_from_UTC|UTC Offsets}
*
* @return {Moment} a moment instance.
*/
function buildMoment( dateValue, timezone ) {
function buildMoment( dateValue, timezone = '' ) {
const dateMoment = momentLib( dateValue );

if ( timezone && ! isUTCOffset( timezone ) ) {
Expand All @@ -492,8 +509,6 @@ function buildMoment( dateValue, timezone ) {
return dateMoment.utcOffset( settings.timezone.offset );
}

const VALID_UTC_OFFSET = /^[+-][0-1][0-9](:[0-9][0-9])?$/;

/**
* Returns whether a certain UTC offset is valid or not.
*
Expand All @@ -506,7 +521,6 @@ function isUTCOffset( offset ) {
return true;
}

offset = `${ offset }`;
return VALID_UTC_OFFSET.test( offset );
}

Expand Down

0 comments on commit c3d5fe4

Please sign in to comment.