Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update README.md #543

Merged
merged 1 commit into from
Feb 10, 2023
Merged

Update README.md #543

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
115 changes: 68 additions & 47 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -175,9 +175,9 @@ Dates in JavaScript are tricky. `RRule` tries to support as much flexibility as

By default, `RRule` deals in ["floating" times or UTC timezones](https://tools.ietf.org/html/rfc5545#section-3.2.19). If you want results in a specific timezone, `RRule` also provides [timezone support](#timezone-support). Either way, JavaScript's built-in "timezone" offset tends to just get in the way, so this library simply doesn't use it at all. All times are returned with zero offset, as though it didn't exist in JavaScript.

**The bottom line is the returned "UTC" dates are always meant to be interpreted as dates in your local timezone. This may mean you have to do additional conversion to get the "correct" local time with offset applied.**
**THE BOTTOM LINE: Returned "UTC" dates are always meant to be interpreted as dates in your local timezone. This may mean you have to do additional conversion to get the "correct" local time with offset applied.**

For this reason, it is highly recommended to use timestamps in UTC eg. `new Date(Date.UTC(...))`. Returned dates will likewise be in UTC (except on Chrome, which always returns dates with a timezone offset). It's recommended to use the provided `datetime` helper, which
For this reason, it is highly recommended to use timestamps in UTC eg. `new Date(Date.UTC(...))`. Returned dates will likewise be in UTC (except on Chrome, which always returns dates with a timezone offset). It's recommended to use the provided `datetime()` helper, which
creates dates in the correct format using a 1-based month.

For example:
Expand All @@ -202,7 +202,7 @@ date.getUTCDate() // --> 1
date.getUTCHours() // --> 18
```

If you want to get the same times in true UTC, you may do so eg. using [Luxon](https://moment.github.io/luxon/#/):
If you want to get the same times in true UTC, you may do so (e.g., using [Luxon](https://moment.github.io/luxon/#/)):

```ts
rule.all().map(date =>
Expand Down Expand Up @@ -282,7 +282,7 @@ iCalendar RFC. Only `freq` is required.
<th>Option</th>
<th>Description</th>
</tr>
<thead>
</thead>
<tbody>
<tr>
<td><code>freq</code></td>
Expand Down Expand Up @@ -491,7 +491,7 @@ rule.all(function (date, i) {
##### `RRule.prototype.between(after, before, inc=false [, iterator])`

Returns all the occurrences of the rrule between `after` and `before`.
The inc keyword defines what happens if `after` and/or `before` are
The `inc` keyword defines what happens if `after` and/or `before` are
themselves occurrences. With `inc == true`, they will be included in the
list, if they are found in the recurrence set.

Expand Down Expand Up @@ -582,8 +582,8 @@ var rule = new RRule(options)

#### Natural Language Text Methods

These methods provide an incomplete support for text–`RRule` and
`RRule`–text conversion. You should test them with your input to see
These methods provide an incomplete support for text→`RRule` and
`RRule`→text conversion. You should test them with your input to see
whether the result is acceptable.

##### `RRule.prototype.toText([gettext, [language]])`
Expand Down Expand Up @@ -634,38 +634,38 @@ var rule = new RRule(options)
new RRuleSet([(noCache = false)])
```

The RRuleSet instance allows more complex recurrence setups, mixing multiple
The `RRuleSet` instance allows more complex recurrence setups, mixing multiple
rules, dates, exclusion rules, and exclusion dates.

Default `noCache` argument is `false`, caching of results will be enabled,
improving performance of multiple queries considerably.

##### `RRuleSet.prototype.rrule(rrule)`

Include the given rrule instance in the recurrence set generation.
Include the given `rrule` instance in the recurrence set generation.

##### `RRuleSet.prototype.rdate(dt)`

Include the given datetime instance in the recurrence set generation.
Include the given datetime instance `dt` in the recurrence set generation.

##### `RRuleSet.prototype.exrule(rrule)`

Include the given rrule instance in the recurrence set exclusion list. Dates
Include the given `rrule` instance in the recurrence set exclusion list. Dates
which are part of the given recurrence rules will not be generated, even if
some inclusive rrule or rdate matches them. NOTE: EXRULE has been (deprecated
some inclusive rrule or rdate matches them. **NOTE:** `EXRULE` has been (deprecated
in RFC 5545)[https://icalendar.org/iCalendar-RFC-5545/a-3-deprecated-features.html]
and does not support a DTSTART property.
and does not support a `DTSTART` property.

##### `RRuleSet.prototype.exdate(dt)`

Include the given datetime instance in the recurrence set exclusion list. Dates
included that way will not be generated, even if some inclusive rrule or
rdate matches them.
Include the given datetime instance `dt` in the recurrence set exclusion list. Dates
included that way will not be generated, even if some inclusive `rrule` or
`rdate` matches them.

##### `RRuleSet.prototype.tzid(tz?)`

Sets or overrides the timezone identifier. Useful if there are no rrules in this
RRuleSet and thus no DTSTART.
`RRuleSet` and thus no `DTSTART`.

##### `RRuleSet.prototype.all([iterator])`

Expand Down Expand Up @@ -709,36 +709,57 @@ rrulestr(rruleStr[, options])

The `rrulestr` function is a parser for RFC-like syntaxes. The string passed
as parameter may be a multiple line string, a single line string, or just the
RRULE property value.
`RRULE` property value.

Additionally, it accepts the following keyword arguments:

`cache`
If True, the rruleset or rrule created instance will cache its results.
Default is not to cache.

`dtstart`
If given, it must be a datetime instance that will be used when no DTSTART
property is found in the parsed string. If it is not given, and the property
is not found, datetime.now() will be used instead.

`unfold`
If set to True, lines will be unfolded following the RFC specification. It
defaults to False, meaning that spaces before every line will be stripped.

`forceset`
If set to True a rruleset instance will be returned, even if only a single rule
is found. The default is to return an rrule if possible, and an rruleset if necessary.
<dl>

`compatible`
If set to True, the parser will operate in RFC-compatible mode. Right now it
means that unfold will be turned on, and if a DTSTART is found, it will be
considered the first recurrence instance, as documented in the RFC.
<dt><code>cache</code></dt>
<dd>
If <code>true</code>, the <code>rruleset</code> or <code>rrule</code> created instance
will cache its results.
Default is not to cache.
</dd>

<dt><code>dtstart</code></dt>
<dd>
If given, it must be a datetime instance that will be used when no
<code>DTSTART</code> property is found in the parsed string.
If it is not given, and the property is not found,
<code>datetime.now()</code> will be used instead.
</dd>

<dt><code>unfold</code></dt>
<dd>
If set to <code>true</code>, lines will be unfolded following the RFC specification.
It defaults to <code>false</code>, meaning that spaces before every line will be stripped.
</dd>

<dt><code>forceset</code></dt>
<dd>
If set to <code>true</code>, an <code>rruleset</code> instance will be returned,
even if only a single rule is found.
The default is to return an <code>rrule</code> if possible, and
an <code>rruleset</code> if necessary.
</dd>

<dt><code>compatible</code></dt>
<dd>
If set to <code>true</code>, the parser will operate in RFC-compatible mode.
Right now it means that unfold will be turned on, and if a <code>DTSTART</code> is found,
it will be considered the first recurrence instance, as documented in the RFC.
</dd>

<dt><code>tzid</code></dt>
<dd>
If given, it must be a string that will be used when no <code>TZID</code>
property is found in the parsed string.
If it is not given, and the property is not found, <code>'UTC'</code> will
be used by default.
</dd>

`tzid`
If given, it must be a string that will be used when no `TZID` property is found
in the parsed string. If it is not given, and the property is not found, `'UTC'`
will be used by default.
</dl>

---

Expand Down Expand Up @@ -771,8 +792,8 @@ rruleSet.rrule(
rruleSet.rdate(start)
```

- Unlike documented in the RFC, every keyword is valid on every frequency (the
RFC documents that `byweekno` is only valid on yearly frequencies, for example).
- Unlike documented in the RFC, every keyword is valid on every frequency. (The
RFC documents that `byweekno` is only valid on yearly frequencies, for example.)

### Development

Expand All @@ -798,13 +819,13 @@ $ yarn build

#### Authors

- [Jakub Roztocil](http://roztocil.co/)
- [Jakub Roztocil](http://roztocil.co)
([@jakubroztocil](http://twitter.com/jakubroztocil))
- Lars Schöning ([@lyschoening](http://twitter.com/lyschoening))
- David Golightly ([@davigoli](http://twitter.com/davigoli))

Python `dateutil` is written by [Gustavo
Niemeyer](http://niemeyer.net/).
Niemeyer](http://niemeyer.net).

See [LICENCE](https://github.com/jakubroztocil/rrule/blob/master/LICENCE) for
more details.
Expand All @@ -822,4 +843,4 @@ more details.

#### Related projects

- https://rrules.com/ — RESTful API to get back occurrences of RRULEs that conform to RFC 5545.
- https://rrules.com — RESTful API to get back occurrences of RRULEs that conform to RFC 5545.