Add helper method to convert from US week numbering

[admackin]

It would be great to have a method to convert from the US week numbering system (First weekday is Sunday, week 1 always starts on the first sunday, preceding days are in week 0) to a JodaTime object

I have written some code to do this but it would be great (for me, and I think others) to have it included in JodaTime. I've posted it under ASL at:
https://gist.github.com/admackin/8e9847c0f4f078ea8cd0

Could this be worked into something suitable for inclusion? I wanted to check if a) it was worth adapting it for inclusion and b) what I would need to do, before opening a pull request. (Obviously I would convert the asserts into proper standalone unit tests, but I'm not sure what else would make sense)

[jodastephen]

Any change to Joda-Time would involve a full global solution based on a Locale, as this doesn't just affect the US. There is no particularly good place to integrate the change, so it would probably have to be a static utility.

[admackin]

Right, and the utility I implemented is literally a couple of static methods on a util class which take a calendar year, US week number and US weekday number, and return a Joda DateTime object. It does the job (although doesn't seem like a particularly Joda-ish API, I must admit). I haven't addressed the job of converting in the other direction yet, although.

[It has now occurred to me that it might be more sensibly implemented as date-time format fields (by analogy with strftime/strptime, which in modern C implementations support for ISO and US week numbering), but I think that change would be further-reaching (and I have no idea of the implementation difficulty, but it's presumably going to be more than the few dozen LOC I've written in the linked implementation). It would also pollute the rest of the codebase with workarounds for these aberrant non-ISO date formats]

[admackin]

For posterity, here's the API from over at my Gist

public class DateConversion {
/**
 * Convert a date from US customary Year-WeekNumber-Day format to a Joda DateTime object
 * <p/>
 * US week numbers correspond to the <b>%U</b> format specifier in the C standard library's <code>strftime</code>
 * function.
 * They assume that weeks start on Sunday (with zero-based day numbering)
 * These can range from 0 to 53, although not in all years, as it depends on the weekday on which New Year's Day
 * falls. If it falls on Sunday, there is no week 0, but otherwise all days preceding the first Sunday are in week 0.
 * The final week of each year is either 52 or 53.
 *
 * @param permissive
 *      If true, allow malformed variants in the date, when that can be sensibly interpreted. For example, when
 *      this is set to <code>true</code> if the week day in weeks 0, 52 or 53 causes crossing a year boundary
 *      (so the returned date's year is different to passed-in year), no exception will be thrown where it would
 *      be otherwise. This also allows week numbers outside the range <code>[0, 53]</code>.
 * @param year
 *      The calendar year
 * @param usWeek
 *      The US week number, which can range from 0-53
 * @param usWeekDay
 *      The zero-based US day number, where Sunday is 0 and Saturday is 6
 * @return
 * @throws org.joda.time.IllegalFieldValueException
 *      If one of the values is invalid, and <code>permissive</code>
 *      is false
 */
public static DateTime fromUSWeekAndYear(int year, int usWeek, int usWeekDay, boolean permissive);
}