Skip to content

Commit

Permalink
Merge branch 'develop'
Browse files Browse the repository at this point in the history
  • Loading branch information
knowledgecode committed Aug 4, 2020
2 parents a5f31dc + a46f69a commit 6f726d9
Show file tree
Hide file tree
Showing 89 changed files with 969 additions and 582 deletions.
60 changes: 46 additions & 14 deletions LOCALE.md
Original file line number Diff line number Diff line change
@@ -1,52 +1,84 @@
# Locale

Month, day of week, and meridiem (am / pm) the `format()` outputs are usually in English, and the `parse()` also assumes that a passed date string is English.
The `format()` outputs month, day of week, and meridiem (am / pm) in English, and the `parse()` assumes the passed date string is in English. Here it describes how to use other languages in these functions.

## Usage

If you would like to use any other language in these functions, switch as follows:
To support `ES Modules` in the next version, the locale switching method has changed and then the old method has been deprecated.

- Node.js:
- CommonJS:

```javascript
const date = require('date-and-time');
require('date-and-time/locale/fr');
const fr = require('date-and-time/locale/fr');

date.locale('fr'); // French
date.locale(fr); // French
date.format(new Date(), 'dddd D MMMM'); // => 'lundi 11 janvier'
```

- With a transpiler:
- ES Modules (with transpile):

```javascript
import date from 'date-and-time';
import 'date-and-time/locale/it';
import it from 'date-and-time/locale/it';

date.locale('it'); // Italian
date.locale(it); // Italian
date.format(new Date(), 'dddd D MMMM'); // => 'Lunedì 11 gennaio'
```

- With an older browser:
- Older browser:

When in older browser, pass the locale string as before. (no changes)

```html
<script src="/path/to/date-and-time.min.js"></script>
<script src="/path/to/locale/zh-cn.js"></script>

<script>
date.locale('zh-cn'); // Chinese
date.locale('zh-cn'); // Chinese
date.format(new Date(), 'MMMD日dddd'); // => '1月11日星期一'
</script>
```

### NOTE

- You have to import (or require) in advance the all locale modules that you are going to switch to.
- The locale will be actually switched after executing `locale('xx')`.
- You could return the locale to English by executing `locale ('en')`.
- The locale will be actually switched after executing the `locale()`.
- You can also change the locale back to English by loading the `en` module:

```javascript
import en from 'date-and-time/locale/en';

date.locale(en);
```

### FYI

The following (old) methods are deprecated. In the next version it won't be able to use them.

- CommonJS:

```javascript
const date = require('date-and-time');
require('date-and-time/locale/fr');

date.locale('fr'); // French
date.format(new Date(), 'dddd D MMMM'); // => 'lundi 11 janvier'
```

- ES Modules (with transpile):

```javascript
import date from 'date-and-time';
import 'date-and-time/locale/it';

date.locale('it'); // Italian
date.format(new Date(), 'dddd D MMMM'); // => 'Lunedì 11 gennaio'
```

## Supported List
## Supported locale List

For now, it supports the following languages:
At this time, it supports the following locales:

```text
Arabic (ar)
Expand Down
74 changes: 52 additions & 22 deletions PLUGINS.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,33 +4,37 @@ As this library is oriented toward minimalism, it may seem like a lack of functi

## Usage

- Node.js:
To support `ES Modules` in the next version, the importing method has changed and then the old method has been deprecated.

- CommonJS:

```javascript
const date = require('date-and-time');
// Import a plugin "foobar".
require('date-and-time/plugin/foobar');
// Import the plugin "foobar".
const foobar = require('date-and-time/plugin/foobar');

// Apply the plugin to "date-and-time".
date.plugin('foobar');
date.plugin(foobar);
```

- With a transpiler:
- ES Modules (with transpile):

```javascript
import date from 'date-and-time';
// Import a plugin "foobar".
import 'date-and-time/plugin/foobar';
// Import the plugin "foobar".
import foobar from 'date-and-time/plugin/foobar';

// Apply the plugin to "date-and-time".
date.plugin('foobar');
date.plugin(foobar);
```

- The browser:
- Older browser:

When in older browser, pass the plugin name as before. (no changes)

```html
<script src="/path/to/date-and-time.min.js"></script>
<!-- Import a plugin "foobar". -->
<!-- Import the plugin "foobar". -->
<script src="/path/to/plugin/foobar.js"></script>

<script>
Expand All @@ -39,6 +43,32 @@ date.plugin('foobar');
</script>
```

### FYI

The following (old) methods are deprecated. In the next version it won't be able to use them.

- CommonJS:

```javascript
const date = require('date-and-time');
// Import the plugin "foobar".
require('date-and-time/plugin/foobar');

// Apply the plugin to "date-and-time".
date.plugin('foobar');
```

- ES Modules (with transpile):

```javascript
import date from 'date-and-time';
// Import the plugin "foobar".
import 'date-and-time/plugin/foobar';

// Apply the plugin to "date-and-time".
date.plugin('foobar');
```

## Plugin List

- day-of-week
Expand Down Expand Up @@ -74,10 +104,10 @@ It adds `dddd`, `ddd` and `dd` tokens to the parser. While these meanings are as
```javascript
const date = require('date-and-time');
// Import "day-of-week" plugin.
require('date-and-time/plugin/day-of-week');
const day_of_week = require('date-and-time/plugin/day-of-week');

// Apply "day-of-week" plugin to `date-and-time`.
date.plugin('day-of-week');
date.plugin(day_of_week);

// You can write like this.
date.parse('Thursday, March 05, 2020', 'dddd, MMMM, D YYYY');
Expand Down Expand Up @@ -106,10 +136,10 @@ It also extends `A` token of the parser as follows:
```javascript
const date = require('date-and-time');
// Import "meridiem" plugin.
require('date-and-time/plugin/meridiem');
const meridiem = require('date-and-time/plugin/meridiem');

// Apply "medidiem" plugin to `date-and-time`.
date.plugin('meridiem');
date.plugin(meridiem);

// This is default behavior of the formatter.
date.format(new Date(), 'hh:mm A'); // => '12:34 PM'
Expand Down Expand Up @@ -142,10 +172,10 @@ It adds `SSSSSS`, `SSSSS` and `SSSS` tokens to the parser. Thease meanings are a
```javascript
const date = require('date-and-time');
// Import "microsecond" plugin.
require('date-and-time/plugin/microsecond');
const microsecond = require('date-and-time/plugin/microsecond');

// Apply "microsecond" plugin to `date-and-time`.
date.plugin('microsecond');
date.plugin(microsecond);

// A date object in JavaScript supports `millisecond` (ms):
date.parse('12:34:56.123', 'HH:mm:ss.SSS');
Expand All @@ -169,10 +199,10 @@ It adds `DDD` token to the formatter. This meaning is as follows:
```javascript
const date = require('date-and-time');
// Import "ordinal" plugin.
require('date-and-time/plugin/ordinal');
const ordinal = require('date-and-time/plugin/ordinal');

// Apply "ordinal" plugin to `date-and-time`.
date.plugin('ordinal');
date.plugin(ordinal);

// These are default behavior of the formatter.
date.format(new Date(), 'MMM D YYYY'); // => Jan 1 2019
Expand All @@ -189,10 +219,10 @@ It adds `timeSpan()` function to the library. This function is similar to the `s
```javascript
const date = require('date-and-time');
// Import "timespan" plugin.
require('date-and-time/plugin/timespan');
const timespan = require('date-and-time/plugin/timespan');

// Apply "timespan" plugin to `date-and-time`.
date.plugin('timespan');
date.plugin(timespan);

const now = new Date(2020, 2, 5, 1, 2, 3, 4);
const new_years_day = new Date(2020, 0, 1);
Expand Down Expand Up @@ -245,14 +275,14 @@ It adds `YY` token to the parser and also changes behavior of `Y` token. These m
```javascript
const date = require('date-and-time');
// Import "two-digit-year" plugin.
require('date-and-time/plugin/two-digit-year');
const two_digit_year = require('date-and-time/plugin/two-digit-year');

// These are default behavior of the parser.
date.parse('Dec 25 69', 'MMM D YY'); // => Invalid Date
date.parse('Dec 25 70', 'MMM D Y'); // => 70 AD (ancient times)

// Apply "two-digit-year" plugin to `date-and-time`.
date.plugin('two-digit-year');
date.plugin(two_digit_year);

// These convert the year 69 or earlier to 2000s, the year 70 or later to 1900s.
date.parse('Dec 25 69', 'MMM D YY'); // => Dec 25 2069
Expand Down
62 changes: 37 additions & 25 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,24 @@ npm install date-and-time --save

## Recent Changes

- 0.14.0
- **Feature Freeze**

We decided to freeze the feature with this version (except the following). The next will be 1.0.0.

- To support `ES Modules` (without transpile) in the next version, the importing method has changed in the `locale()` and the `plugin()`. As this version you will see the warning message if using the old method. See [LOCALE.md](./LOCALE.md) and [PLUGINS.md](./PLUGINS.md) for details.

- Added `transform()` function to transform the format of a date string. When changing the format, in the past you would convert the date string to a date object with the `parse()`, and then format it with the `format()` again, but you can now do this with a single function.

```javascript
// 3/8/2020 => 8/3/2020
date.transform('3/8/2020', 'D/M/YYYY', 'M/D/YYYY');

// in the past
const today = date.parse('3/8/2020', 'D/M/YYYY');
date.format(today, 'M/D/YYYY'); // => '8/3/2020'
```

- 0.13.0
- The `format()` now supports a compiled formatString.

Expand Down Expand Up @@ -99,31 +117,6 @@ npm install date-and-time --save
| a | meridiem (lowercase) | am, pm | |
| aa | meridiem (lowercase with ellipsis) | a.m., p.m. | |

- 0.11.0
- Added `compile()` function that precompiling a date-time string for the parser. If you need to process many date-time string with one format, you can get results faster than before by precompiling the format string with this function.

```javascript
// We have passed a string format at the 2nd parameter each time when calling the parse() function.
date.parse('Mar 22 2019 2:54:21 PM', 'MMM D YYYY h:m:s A');
date.parse('Jul 27 2019 4:15:24 AM', 'MMM D YYYY h:m:s A');
date.parse('Dec 25 2019 3:51:11 AM', 'MMM D YYYY h:m:s A');

// You can precompile the string format.
const pattern = date.compile('MMM D YYYY h:m:s A');

// The parse() will be able to finish faster than passing the format string each time.
date.parse('Mar 22 2019 2:54:21 PM', pattern);
date.parse('Jul 27 2019 4:15:24 AM', pattern);
date.parse('Dec 25 2019 3:51:11 AM', pattern);
```

```javascript
const pattern = date.compile('MMM D YYYY h:m:s A');

// The isValid() will also too.
date.isValid('Mar 22 2019 2:54:21 PM', pattern);
```

## Usage

- Node.js:
Expand Down Expand Up @@ -431,6 +424,25 @@ const result = date.preparse('2015/01/02 23:14:05', 'YYYY/MM/DD HH:mm:ss');
date.isValid(result); // => true
```

### transform(dateString, arg1, arg2[, utc])

- Transformation of date string.
- @param {**string**} dateString - a date string
- @param {**string|Array.\<string\>**} arg1 - the format string of the date string or the compiled object
- @param {**string|Array.\<string\>**} arg2 - the transformed format string or the compiled object
- @param {**boolean**} [utc] - output as UTC
- @returns {**string**} a formatted string

This function transforms the format of a date string. The 2nd parameter, `arg1`, is the format string of it. Available token list is equal to the `parse()`'s. The 3rd parameter, `arg2`, is the transformed format string. Available token list is equal to the `format()`'s.

```javascript
// 3/8/2020 => 8/3/2020
date.transform('3/8/2020', 'D/M/YYYY', 'M/D/YYYY');

// 13:05 => 01:05 PM
date.transform('13:05', 'HH:mm', 'hh:mm A');
```

### addYears(dateObj, years)

- Adding years.
Expand Down
2 changes: 1 addition & 1 deletion bower.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "date-and-time",
"description": "A Minimalist DateTime utility for Node.js and the browser",
"version": "0.13.1",
"version": "0.14.0",
"main": "date-and-time.js",
"moduleType": [
"amd",
Expand Down
Loading

0 comments on commit 6f726d9

Please sign in to comment.