OpenRefine: Documentation missing for toDate(locale,format)

When the enhancement to toDate() requested in #729 was added in fa072df85c27ce601f867a7f39c5a5d1bf288dec 9 years ago (!), no documentation was included. The online help and the documentation should be updated to reflect the current code.

The test cases show how the list of format strings can be prepended with a string identifying the locale which should be used for the parsing attempts:

https://github.com/OpenRefine/OpenRefine/blob/fa072df85c27ce601f867a7f39c5a5d1bf288dec/main/tests/server/src/com/google/refine/tests/expr/functions/strings/ToFromConversionTests.java#L134-L139

Docs to be updated:

https://github.com/OpenRefine/OpenRefine/blob/d9c235b5b4f763826ab6e4ff1b1d946389286530/main/resources/com/google/refine/grel/FunctionDescription.properties#L123

https://github.com/OpenRefine/OpenRefine/blob/be2d14e72158dfc1c93dce098f97ed59a7eb7dc8/docs/docs/manual/grelfunctions.md#date-functions-date-functions

About this issue

Original URL
State: open
Created 2 years ago
Reactions: 2
Comments: 16 (6 by maintainers)

Most upvoted comments

@amyra98 That’s very close. I would slightly tweak your statement to say “the ~~formatting~~ parsing function will use the formatting rules for that locale.”

Also, as @ostephens pointed out, the current help is completely wrong (looks like it was cut & paste from toString() and not updated), so I would suggest starting from scratch and rewriting it.

tfmorris on Mar 14, 2023

Slightly separate to the need to add the locale aspect to the documentation, but that description in fun_to_date does not seem correct to me:

Returns the inputted object converted to a date object. Without arguments, it returns the ISO 8601 extended format. With arguments, you can control the output format. With monthFirst: set false if the date is formatted with the day before the month. With formatN: attempt to parse the date using an ordered list of possible formats. Supply formats based on the SimpleDateFormat syntax: SimpleDateFormat

The arguments available to the toDate function control how the inputted object is interpreted as a date, not what the output format is (the output of a successful toDate function will always be a date object)

It is also not the case that “Without arguments, it returns the ISO 8601 extended format” - again with or without arguments toDate returns a date object. I’m not sure what this statement was really trying to say that the display of the dates in the OpenRefine UI uses ISO8601 extended, or something else. If it was indicating how the date would be displayed in the UI once again the arguments given to toDate don’t affect this at all

ostephens on Mar 14, 2023