Friday, 19 August 2011

First NuGet package of Noda Time available - feedback please!

Having been stuck in a bit of an API dilemma recently and having also found time to release Unconstrained Melody as a NuGet package, I figured it would be worth doing the same for Noda Time, in the hope of getting more potential "customers" to have a look. Even though fetching the source and building it is pretty painless, it's more than I'd expect for a casual onlooker, where NuGet makes the whole process pretty simple.

So, while you're reading the rest of this post, why not download the Noda Time 0.1 packages? There are three to pick up, although you only really need the first:

  • NodaTime: the core library
  • NodaTime.Experimental: our sort of sandbox; when there are multiple ways of attacking a problem, I'll probably try to have them all in here at the same time. This only works for new classes and things which can be implemented as extension methods of course - but that should cover a lot of ground. This is more for comment than production use, basically.
  • NodaTime.Testing: Extra library which is designed for testing code which uses Noda Time - for example, a fake clock to be used where you're passing in IClock for dependency injection.

What do I need to know?

It's worth being aware of the core concepts in Noda Time:

  • Instant: defines a universal point in time (we don't handle relativity) without reference to a time zone or calendar system. (Internally it's the number of ticks since the Unix epoch, but don't let that concern you too much.)
  • CalendarSystem: A way of breaking down time into years, months, days, hours, minutes etc. You'll almost certainly only want to use the ISO calendar system, which is the universal default in Noda Time.
  • DateTimeZone: Essentially, a mapping between UTC and local time. But full of subtleties like local times that don't exist or are ambiguous...
  • LocalDateTime: A date and time in a particular calendar but not in a particular time zone. Something like "15th January 2010, 10:30am (ISO)". This is the type you're actually most likely to perform arithmetic - it makes sense to do things like adding a week or a month. Closely related are LocalDate and LocalTime, for situations where you only need a date or only need a time of day respectively.
  • ZonedDateTime: A date and time in a particular calendar and time zone. Think of it as a local date and time + DateTimeZone + offset from UTC. A ZonedDateTime can be mapped unambiguously to an instant.

All of the above are immutable in Noda Time. All except CalendarSystem and DateTimeZone are structs.

Those are the important concepts. There are some more details on the wiki page, but hopefully that's enough to get you going.

What's in the package?

Currently, I'm reasonably confident in the API and implementation of:

  • CalendarSystem (ISO, Gregorian, Julian and Coptic are implemented; a few more to come)
  • DateTimeZone (Olson identifiers; we have a mapping for the Windows identifiers, but I don't think we expose them yet.)
  • ZonedDateTime: Conversion to and from a LocalDateTime (with various options for handling awkward situations)
  • LocalDateTime / LocalDate / LocalTime: Various conversions between them (and construction of course). Arithmetic adding periods (e.g. "this date/time plus two weeks") is implemented but may not be the final API or semantics; manipulation is still up in the air. There are some extension methods in the experimental package to say localDateTime.WithMonthOfYear(10) etc - other options include a builder API, more direct ways of adding periods localDateTime.AddDays(10) and more. Feedback very welcome on this.
  • Instant/Duration/Interval: These are fairly primitive types which don't have much need for extra work

LocalDateTime and ZonedDateTime have conversions to/from .NET types (DateTime and DateTimeOffset) - that may be your best bet for getting "into" the API, unless you want to construct values explicitly.

What's not there yet?

The big feature missing from all of this is formatting and parsing. We have an implementation for Instant and Offset, but those are fairly limited types - obviously ZonedDateTime and LocalDateTime are the big ones here. It's worth understanding the basic plan though...

For each appropriate type, we're going to support the framework convention of ToString on the type itself, as well as static Parse and TryParse methods. However, I personally regard those as legacy approaches. There'll also be INodaFormatter<T> and INodaParser<T> which define interfaces for formatting and parsing - with concrete implementations like LocalDateTimeParser etc. These will be thread-safe and reusable, so you'll be able to set up the parser or formatter once for each pattern you want to use. I see this as giving better maintainability and performance, as well feeling like better OO. Thoughts on this general principle would be welcome - the actual interfaces are there now, but somewhat in flux.

We have yet to decide how to expose what I'm calling pseudo-mutators - methods which get you from one value to another, e.g. the WithYearOfMonth method mentioned earlier. What we're really missing is use cases, so if you can dump a list of feature requests based on what you actually want to do that would be wonderful.

There are no doubt some other features we'll want for v1.0 - and some that might make it, but may not. If there's something you regard as a must-have, holler about it.

Where's the documentation?

The API documentation is actually pretty reasonable - at least, some exists for pretty much everything (no warnings about missing summaries) but it may very well be skimpy in places, and there's just a chance some of it is out of date. Before the full release we'll do a proper pass through, of course. This documentation is built nightly (or on demand) so by the time you read it, it may not reflect the package you've downloaded, if I've applied some fixes etc. I wouldn't expect any really big changes in the very near future though. Before release I'll set up versioned documentation.

The project wiki is in a worse state - the key concepts page is reasonably accurate, but obviously there's a lot of work to be done overall.

How do I give feedback?

The main point of releasing 0.1 as a NuGet package is to get feedback. Lots of feedback. This should be done on the project issues page. If it's a non-trivial matter which you'd like to discuss further, then it'd be great if you'd join the Google group / mailing list, but don't feel you have to get involved to leave feedback.

While high quality feedback is obviously desirable, at this point I'd really just like lots of it. So in particular:

  • If the NuGet packaging is wrong, please let me know - I'm a complete newbie on this.
  • I'm not going to care much whether you report something as a bug or a feature request.
  • If you don't have time to see if your feedback is already covered elsewhere, don't bother.
  • Even if it's only a vague idea, I still want to hear it.
  • Positive feedback is useful too - say what you like as well as what you don't.

Obviously I'll go through and prune the feedback, mark duplicates etc, but that's work that I can do afterwards. If you find any "barriers to entry" when it comes to giving feedback, let me know by email (skeet@pobox.com) and I'll do what I can do fix it.

32 comments:

  1. Maybe it's just me, but given how long I've used the .NET DateTime API, the word "Local" is kind of ingrained in my brain as meaning something very different than the Noda uses it.

    Would it be reasonable to suggest a completely different term for LocalDateTime/LocalDate/LocalTime? Perhaps Calendar instead of Local, given that these concepts represent an instant of time mapped to a particular calendar?

    That would sure make the API more understandable to a mere mortal like me...

    ReplyDelete

  2. The Wallabies must successfully target dynamic All Blacks second rowers Brodie Retallick and
    Sam Whitelock when they attempt to turn their Bledisloe Cup fortunes around, says Australian backrower
    Rory Arnold.The formidable duo of Retallick and Whitelock has been one of the great strengths of the world
    champion All Blacks’ forward ­machine in recent years and both are used to winning against the Wallabies.
    All Blacks vs Wallabies
    All Blacks vs Wallabies Live
    All Blacks vs Wallabies Stream

    Whitelock has tasted defeat just three times in 20 games Tests against Australia and Retallick once in 15.
    Rising Wallabies lock Rory ­Arnold said getting an edge over the duo was key for his team.“They’ve been world-class
    locks now for a number of years, so if we want to dominate up front we know we’ve got to go at those blokes,” said Arnold.
    “We’re going to have to be at our best, the second-rowers, to take those blokes on.”
    Watch All Blacks vs Wallabies
    Watch All Blacks vs Wallabies Live
    Wallabies vs All Blacks

    While Whitelock and Retallick have been a constant force for New Zealand,
    Australia have chopped and changed their second-row combinations since the 2015 World Cup final against the All Blacks.
    Wallabies vs All Blacks Live
    Wallabies vs All Blacks Live Stream
    Watch Wallabies vs All Blacks Live
    Watch Wallabies vs All Blacks Live Stream

    Coach Michael Cheika used five starting second-row combinations in the first five Tests of 2016 and seven in total across the season as
    six different locks got an opportunity in the run-on side.
    In the June Tests, Cheika started with Adam Coleman and Sam Carter and then brought in Arnold for the last match.
    “He sort of swapped and changed a fair bit last year, so I’m not sure how he’s going to go this year with those second-row spots,” Arnold said.

    ReplyDelete
  3. The Wallabies must successfully target dynamic All Blacks second rowers Brodie Retallick and
    Sam Whitelock when they attempt to turn their Bledisloe Cup fortunes around, says Australian backrower
    Rory Arnold.The formidable duo of Retallick and Whitelock has been one of the great strengths of the world
    champion All Blacks’ forward ­machine in recent years and both are used to winning against the Wallabies.
    All Blacks vs Wallabies
    All Blacks vs Wallabies Live
    All Blacks vs Wallabies Stream

    Whitelock has tasted defeat just three times in 20 games Tests against Australia and Retallick once in 15.
    Rising Wallabies lock Rory ­Arnold said getting an edge over the duo was key for his team.“They’ve been world-class
    locks now for a number of years, so if we want to dominate up front we know we’ve got to go at those blokes,” said Arnold.
    “We’re going to have to be at our best, the second-rowers, to take those blokes on.”
    Watch All Blacks vs Wallabies
    Watch All Blacks vs Wallabies Live
    Wallabies vs All Blacks

    While Whitelock and Retallick have been a constant force for New Zealand,
    Australia have chopped and changed their second-row combinations since the 2015 World Cup final against the All Blacks.
    Wallabies vs All Blacks Live
    Wallabies vs All Blacks Live Stream
    Watch Wallabies vs All Blacks Live
    Watch Wallabies vs All Blacks Live Stream

    Coach Michael Cheika used five starting second-row combinations in the first five Tests of 2016 and seven in total across the season as
    six different locks got an opportunity in the run-on side.
    In the June Tests, Cheika started with Adam Coleman and Sam Carter and then brought in Arnold for the last match.
    “He sort of swapped and changed a fair bit last year, so I’m not sure how he’s going to go this year with those second-row spots,” Arnold said.

    ReplyDelete
  4. The winners of this year's US Open Tennis 2017 will have even more to celebrate than in past years.The tennis tournament, scheduled for August 28 through September 10, will award a total purse of $50.4 million, a $4 million (nine percent) increase over the total prize money in the 2016 US Open.Stan Wawrinka will not defend his US Open title and will miss the rest of the season after deciding to undergo surgery on his left knee.The 32-year-old was troubled by the US Open Tennis 2017 Live problem during his first-round loss to Daniil Medvedev at Wimbledon and revealed earlier this week he would miss the Masters events in Montreal and Cincinnati.

    Wawrinka, however, has since made the US Open Tennis 2017 Live Stream decision to take direct action in a bid to resolve the problem.He said in a statement: “I am sad to announce that, after talking with my team and doctor, I had to make a difficult decision to undergo a medical intervention on my knee. This was the only solution to make sure I will be able to compete at the top level for many more years.”Wawrinka won his third grand slam title in New York last year with victory over Novak Djokovic. Neither will be at Flushing Meadows this year, with Djokovic also calling an early end to his season to rest an elbow problem that forced him to retire US Open 2017 Finals during his Wimbledon quarter-final against Tomas Berdych.It remains to be seen whether Andy Murray will be fit enough to compete as he continues his recovery from a hip problem. The world No1 has withdrawn from next week’s Rogers Cup in Montreal but has not yet announced whether he will play the following week in Cincinnati or at the US Open.

    Continuing his statement, Wawrinka said: “This is obviously US Open 2017 Finals Live extremely disappointing but I’m already looking ahead and planning my recovery. I love this sport and I will work hard to get back to my top level and play many more years.”Wawrinka has been replaced in the US Open draw by Germany’s Florian Mayer.

    ReplyDelete
  5. The long ushered super fight that fans dared Golden Boy promoter,
    Oscar De Le Hoya, to make, finally got the go ahead when it was officially announced in May of this year.
    Canelo Alvarez versus Gennady Golovkin is set for the 26th of September at the T-Mobile Arena, Las Vegas.
    May vs Conor
    May vs Conor Live
    May vs Conor Live Stream
    Watch May vs Conor
    Watch May vs Conor Live
    Watch May vs Conor Live Stream
    May vs Conor Boxing
    May vs Conor Online
    May vs Conor Boxing Fight
    Conor vs May
    Conor vs May Live
    Conor vs May Live Stream
    Conor vs May Obxing
    Conor vs May Boxing Fight
    Conor vs May Live Online
    Watch Conor vs May
    Watch Conor vs May Live
    WatchConor vs May Live Stream
    Yee haw shouted ghosts of super fights gone by, one super fight in the mail, signed and sealed. Boxing fans
    rejoiced, only to have their hymn interrupted by heresy. Shortly after, another long spoken of affair,
    one largely rejected in the boxing community, Floyd Mayweather versus Conor McGregor, was also announced,
    and has since echoed louder through TMZ manufactured speakers. Both fights offer something to the public,

    ReplyDelete
  6. <a href="https://conorvsmayfight.net”>MayweathervsMcgregor</a>

    ReplyDelete
  7. The tournament begins with the US Open Tennis 2017 Qualifying Tournament, from Tuesday, August 22, through to Friday, August 25.
    The real thing kicks off the following Monday, August 28, which for Australian audiences will be the early hours of Tuesday, August 29 (AEST).
    In terms of the pointy end of proceedings, the women’s final is set to start at 4pm, US Open Tennis 2017 Live Saturday September 9 (EST), which for Aussies means 6am, Sunday September 7 (AEST).
    As for the men’s final, it will begin at 4pm (EST) the following day, so means another 6am start in Australia, this time on Monday, September 8 (AEST).

    US Open Tennis 2017 Live Stream
    US Open Tennis 2017 Live Online
    US Open Tennis 2017 Live Free

    ReplyDelete
  8. The All Blacks vs Wallabies must successfully target dynamic All Blacks second rowers Brodie Retallick and
    Sam Whitelock when they attempt to turn their Bledisloe Cup fortunes around, says Australian backrower
    Rory Arnold.The formidable duo of Retallick and Whitelock has been one of the great strengths of the world
    champion All Blacks’ forward ­machine in recent All Blacks vs Wallabies Live years and both are used to winning against the Wallabies.

    All Blacks vs Wallabies Stream
    Watch All Blacks vs Wallabies
    Wallabies vs All Blacks

    ReplyDelete
  9. The Bledisloe Cup 2017 gets in progress with the Wallabies out to do the apparently unfathomable to crush the all-vanquishing All Blacks.
    This is The Roar's definitive manual for live spilling and watching the match on TV. The match is booked to commence at 8pm (AEST) on Saturday, August 19.
    It's being held at ANZ Stadium in Sydney.The Bledisloe Cup has been held by New Zealand since 2003, with Australia just winning three of their previous 20 matches against the New Zealand side.
    Besides, the initial two matches of the Bledisloe Cup 2017 Live frame some portion of the Rugby Championship, which likewise includes South Africa and Argentina.
    The third match of the Bledisloe is played outside of the Championship.

    Bledisloe Cup 2017 Live Stream
    Bledisloe Cup Live
    Bledisloe Cup Live Stream

    ReplyDelete
  10. Mayweather deserves any and all criticism levied against him in regards to his personal conduct, but one thing that can never be put in doubt is his near-divine boxing talents.
    Watch Mcgregor Mayweather Live Stream online
    Mcgregor Mayweather Live Stream
    Mcgregor Mayweather Live
    Mcgregor Mayweather
    Mayweather Mcgregor Live
    Mayweather Mcgregor
    Mcgregor Mayweather Boxing Fight
    It’s almost unfair how gifted Mayweather is as a boxer. Like a video game character, the 40-year-old possesses god-like hand speed, quick feet, an almost-psychic ability to predict what his opponent wants to do, otherworldly spatial awareness and impossible reactions.

    ReplyDelete
  11. Mayweather deserves any and all criticism levied against him in regards to his personal conduct, but one thing that can never be put in doubt is his near-divine boxing talents.
    Mayweather Mcgregor Boxing
    Mayweather Mcgregor Fight
    Mcgregor vs Mayweather PPV Fight
    Mayweather Mcgregor Boxing Fight
    Mayweather Mcgregor Live Boxing
    Mayweather Mcgregor Live Stream
    Watch Mayweather Mcgregor Live Stream online
    It’s almost unfair how gifted Mayweather is as a boxer. Like a video game character, the 40-year-old possesses god-like hand speed, quick feet, an almost-psychic ability to predict what his opponent wants to do, otherworldly spatial awareness and impossible reactions.

    ReplyDelete
  12. but one thing that can never be put in doubt is his near-divine boxing talents.


    gclub

    ReplyDelete
  13. Rugby League World Cup 2017the Championship for Bradford in troublesome conditions this year and has grown essentially. In like manner, Shane (Toal) has been an ascent in League One and topped everything by scoring the undertaking that got Barrow pushed last week."Scotland achieved the quarter-last of the last Rugby League World Cup, when it was held in England, Wales, France and Ireland. They were pounded 40-4 by New Zealand, who continued to lose to Australia in the last and are in Pool B for the finals in the near future, near to Tonga and Samoa. Prize breakers: A ticket for a 8 to 12 year old kid and guard to the Rugby League World Cup 2017 Liveopening match of the RLWC2017 on Friday October 27. Every tyke gets a uniform to wear on the pitch – shirt, shorts, socks. Moreover the young people will get onto the pitch with the world's Best Rugby League players and remain on the pitch for the national tunes of approval.
    Rugby League World Cup 2017 Live Stream
    Rugby League World Cup
    Rugby League World Cup Live

    ReplyDelete
  14. Thank you so much for this wonderful article really!
    If someone want to read more about that NFR Rodeo 2017 Live I think this is the right place for you!

    Thank you so much for this wonderful article really!
    If someone want to read more about that NFR Rodeo 2017 I think this is the right place for you!

    Thank you so much for this wonderful article really!
    If someone want to read more about that NFR Rodeo 2017 Live Stream I think this is the right place for you!

    Thank you so much for this wonderful article really!
    If someone want to read more about that NFR Rodeo I think this is the right place for you!

    ReplyDelete