<commit_before>Date and Time Arithmetic in Noda Time

There are two types of arithmetic in Noda Time: arithmetic on the
time line (in some sense "absolute" arithmetic), and calendrical arithmetic.
Noda Time deliberately separates the two, with the aim of avoiding
subtle bugs where developers may be tempted to mix concepts inappropriately.

Time Line Arithmetic
====================

The [`Instant`](noda-type://NodaTime.Instant) and
[`ZonedDateTime`](noda-type://NodaTime.ZonedDateTime) types both unambiguously
refer to a point in time (with the latter additionally holding time
zone and calendar information). We can add a length of time to that point to get
another point in time - but only if it's a truly fixed length of time, such as
"3 minutes". While a minute is a fixed length of time, a month isn't - so
the concept of adding "3 months" to an instant makes no sense. (Note
that Noda Time doesn't support leap seconds, otherwise even "3
minutes" wouldn't be a fixed length of time.)

These "fixed lengths of time" are represented in Noda Time with the
[`Duration`](noda-type://NodaTime.Duration) type, and they can be
added to either an `Instant` or `ZonedDateTime` using either the `+` operator
or `Plus` methods:

    Duration duration = Duration.FromMinutes(3);
    Instant now = SystemClock.Instance.Now;    
    Instant future = now + duration; // Or now.Plus(duration)
    
    ZonedDateTime nowInIsoUtc = now.InIsoUtc();
    ZonedDateTime thenInIsoUtc = nowInIsoUtc + duration;

(There are also static `Add` and `Subtract` methods, the `-` operator and
the instance `Minus` method on both `Instant` and `ZonedDateTime`.)

Time line arithmetic is pretty simple, except you might not *always* get
what you expect when using `ZonedDateTime`, due to daylight saving transitions:

    DateTimeZone london = DateTimeZoneProviders.Tzdb["Europe/London"];
    // 12:45am on March 27th 2012
    LocalDateTime local = new LocalDateTime(2012, 3, 27, 0, 45, 00);
    ZonedDateTime before = london.AtStrictly(local);
    ZonedDateTime after = before + Duration.FromMinutes(20);
    
We start off with a *local* time of 12.45am. The time that we add is effectively
"experienced" time - as if we'd simply waited twenty minutes. However, at 1am on that day,
the clocks in the Europe/London time zone go forward by an hour - so we end up with a local
time of 2:05am, not the 1:05am you might have expected.
<commit_msg>Fix a reference to InIsoUtc() missed from revision 98c87f937bf6. (But leave the variable name, since it helps contrast the Instant and ZonedDateTime concepts.)<commit_after>Date and Time Arithmetic in Noda Time

There are two types of arithmetic in Noda Time: arithmetic on the
time line (in some sense "absolute" arithmetic), and calendrical arithmetic.
Noda Time deliberately separates the two, with the aim of avoiding
subtle bugs where developers may be tempted to mix concepts inappropriately.

Time Line Arithmetic
====================

The [`Instant`](noda-type://NodaTime.Instant) and
[`ZonedDateTime`](noda-type://NodaTime.ZonedDateTime) types both unambiguously
refer to a point in time (with the latter additionally holding time
zone and calendar information). We can add a length of time to that point to get
another point in time - but only if it's a truly fixed length of time, such as
"3 minutes". While a minute is a fixed length of time, a month isn't - so
the concept of adding "3 months" to an instant makes no sense. (Note
that Noda Time doesn't support leap seconds, otherwise even "3
minutes" wouldn't be a fixed length of time.)

These "fixed lengths of time" are represented in Noda Time with the
[`Duration`](noda-type://NodaTime.Duration) type, and they can be
added to either an `Instant` or `ZonedDateTime` using either the `+` operator
or `Plus` methods:

    Duration duration = Duration.FromMinutes(3);
    Instant now = SystemClock.Instance.Now;    
    Instant future = now + duration; // Or now.Plus(duration)
    
    ZonedDateTime nowInIsoUtc = now.InUtc();
    ZonedDateTime thenInIsoUtc = nowInIsoUtc + duration;

(There are also static `Add` and `Subtract` methods, the `-` operator and
the instance `Minus` method on both `Instant` and `ZonedDateTime`.)

Time line arithmetic is pretty simple, except you might not *always* get
what you expect when using `ZonedDateTime`, due to daylight saving transitions:

    DateTimeZone london = DateTimeZoneProviders.Tzdb["Europe/London"];
    // 12:45am on March 27th 2012
    LocalDateTime local = new LocalDateTime(2012, 3, 27, 0, 45, 00);
    ZonedDateTime before = london.AtStrictly(local);
    ZonedDateTime after = before + Duration.FromMinutes(20);
    
We start off with a *local* time of 12.45am. The time that we add is effectively
"experienced" time - as if we'd simply waited twenty minutes. However, at 1am on that day,
the clocks in the Europe/London time zone go forward by an hour - so we end up with a local
time of 2:05am, not the 1:05am you might have expected.

{'fraction_non_alphanumeric': 0.08090744830355351, 'fraction_numerical': 0.017265609315398514, 'mean_word_length': 4.339764201500536, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3943964', 'n_tokens_mistral': 1502, 'n_tokens_neox': 1375, 'n_words': 680}