[feature][expressions] Add format_interval function #55172

Malvineous · 2023-11-05T05:31:25Z

Description

This adds a new format_interval function to address feature request #54257. It takes an interval value and a format specifier, and returns a string describing the interval in terms of the format specifier (e.g. 5 years, 2 months or 3:01).

I have included some tests and they pass with make test.

Here is a screenshot of the help text with some examples:

Malvineous · 2023-11-16T12:32:31Z

Updated to fix code formatting issue and rebase on master

Implements qgis#54257.

DelazJ

Hi @Malvineous
Trying to provide a feedback, not on code side but on the expression help content.
I personally find it quite verbose and wondered if some details (somehow technical and describing internal logic) should not be showcased in examples instead of text. Tried below.

Also how do you decide whether the letters should be uppercase (Y,M,W,D) or lowercase (h,m,s,z)? Time vs date, I guess. How about distinguish only month vs minute? (I think this is the usage but I may be wrong, i don't have much experience)

DelazJ · 2023-11-16T16:24:06Z

resources/function_help/json/format_interval

+    "expression": "format_interval(make_interval(minutes:=1560),'%Dd %mm')",
+    "returns": "'1d 120m'"
+  }],
+  "tags": ["custom", "type", "uses", "format", "strings", "time", "date", "formats", "see", "interval", "tostring"]


Suggested change

"tags": ["custom", "type", "uses", "format", "strings", "time", "date", "formats", "see", "interval", "tostring"]

"tags": ["custom", "type", "format", "strings", "time", "date", "formats", "conversion", "interval", "tostring"]

I do not find them relevant here. Not also convinced by the tostring...

I wanted to provide plenty of information and examples to make things clear, but if you think could be better explained I'm happy to make changes. I was hoping by providing a few examples users could skip reading the text and just look at the examples to figure it out if they preferred.

For the tags I just copied them off the format_date function as this function does something very similar, so do you think your proposed changes here should also apply to format_date?

DelazJ · 2023-11-16T16:31:24Z

resources/function_help/json/format_interval

+    "description": "interval value, such as that returned by make_interval()."
+  }, {
+    "arg": "format",
+    "description": "String template used to format the string. <table><thead><tr><th>Expression</th><th>Output</th></tr></thead><tr valign=\"top\"><td><code>%Y</code></td><td>the number of years</td></tr><tr valign=\"top\"><td><code>%M</code></td><td>the number of months</td></tr><tr valign=\"top\"><td><code>%W</code></td><td>the number of weeks</td></tr><tr valign=\"top\"><td>%D</td><td>the number of days</td></tr><tr valign=\"top\"><td>%h</td><td>the number of hours</td></tr><tr valign=\"top\"><td>%m</td><td>the number of minutes</td></tr><tr valign=\"top\"><td>%s</td><td>the number of seconds</td></tr><tr valign=\"top\"><td>%z</td><td>the number of milliseconds</td></tr></table>A single zero can be inserted before the specifier (e.g. <code>%0m</code>) to add a leading zero if the value would be less than two digits.  Milliseconds can be padded to three digits (<code>%00z</code>) and years up to four digits (<code>%000Y</code>).  This is useful for formats like <code>%h:%0m:%0s.%00z</code> to display as <code>2:04:06.008</code> rather than <code>2:4:6.8</code>.<br/>The interval is only broken down to the largest specifier.  So for an interval of 65 seconds, only using the <code>%s</code> specifier will show 65 as the value for the seconds field, however if the <code>%m</code> specifier is also used, the value will be broken down into minutes instead, so the same interval will show as 1 minute 5 seconds.  This means you do not have to specify all placeholders - if you omit <code>%h</code> for hours, the result is that <code>%m</code> for minutes will increase above 59 if needed.<br/>The least significant placeholder specified (with the year being the most significant and milliseconds the least) will be rounded up or down as appropriate.  This way an interval of 90 seconds will show as 2 minutes if only <code>%m</code> is used, or 1 minute 30 seconds if both <code>%m</code> and <code>%s</code> are used together."


I wonder if examples should not showcase what you are describing here

Suggested change

"description": "String template used to format the string. <table><thead><tr><th>Expression</th><th>Output</th></tr></thead><tr valign=\"top\"><td><code>%Y</code></td><td>the number of years</td></tr><tr valign=\"top\"><td><code>%M</code></td><td>the number of months</td></tr><tr valign=\"top\"><td><code>%W</code></td><td>the number of weeks</td></tr><tr valign=\"top\"><td>%D</td><td>the number of days</td></tr><tr valign=\"top\"><td>%h</td><td>the number of hours</td></tr><tr valign=\"top\"><td>%m</td><td>the number of minutes</td></tr><tr valign=\"top\"><td>%s</td><td>the number of seconds</td></tr><tr valign=\"top\"><td>%z</td><td>the number of milliseconds</td></tr></table>A single zero can be inserted before the specifier (e.g. <code>%0m</code>) to add a leading zero if the value would be less than two digits. Milliseconds can be padded to three digits (<code>%00z</code>) and years up to four digits (<code>%000Y</code>). This is useful for formats like <code>%h:%0m:%0s.%00z</code> to display as <code>2:04:06.008</code> rather than <code>2:4:6.8</code>.<br/>The interval is only broken down to the largest specifier. So for an interval of 65 seconds, only using the <code>%s</code> specifier will show 65 as the value for the seconds field, however if the <code>%m</code> specifier is also used, the value will be broken down into minutes instead, so the same interval will show as 1 minute 5 seconds. This means you do not have to specify all placeholders - if you omit <code>%h</code> for hours, the result is that <code>%m</code> for minutes will increase above 59 if needed.<br/>The least significant placeholder specified (with the year being the most significant and milliseconds the least) will be rounded up or down as appropriate. This way an interval of 90 seconds will show as 2 minutes if only <code>%m</code> is used, or 1 minute 30 seconds if both <code>%m</code> and <code>%s</code> are used together."

"description": "String template used to format the string. <table><thead><tr><th>Expression</th><th>Output</th></tr></thead><tr valign=\"top\"><td><code>%Y</code></td><td>the number of years</td></tr><tr valign=\"top\"><td><code>%M</code></td><td>the number of months</td></tr><tr valign=\"top\"><td><code>%W</code></td><td>the number of weeks</td></tr><tr valign=\"top\"><td>%D</td><td>the number of days</td></tr><tr valign=\"top\"><td>%h</td><td>the number of hours</td></tr><tr valign=\"top\"><td>%m</td><td>the number of minutes</td></tr><tr valign=\"top\"><td>%s</td><td>the number of seconds</td></tr><tr valign=\"top\"><td>%z</td><td>the number of milliseconds</td></tr></table>Not all placeholders need to be specified; the interval is broken down to only the specified ones and will be rounded up or down as appropriate.<br/>Zeros can be inserted before the specifier (e.g. <code>%0m</code>) to add a leading zero if the returned value would be less than a desired number of digits. This is useful for formats like <code>%h:%0m:%0s.%00z</code> to display as <code>2:04:06.008</code> rather than <code>2:4:6.8</code>."

Happy to remove some of the explanation. Having worked in IT support for many years I am used to spending a lot of time explaining things to people so I tend to include a lot of detail, to avoid people coming back and asking more questions later :)

DelazJ · 2023-12-01T09:59:47Z

resources/function_help/json/format_interval

+  }, {
+    "expression": "format_interval(make_interval(minutes:=91),'%h hr')",
+    "returns": "'2 hr'"
+  }, {


Assuming I understand the description.

Suggested change

}, {

}, {

"expression": "format_interval(make_interval(minutes:=62), '%h hr')",

"returns": "'1 hr'"

}, {

"expression": "format_interval(make_interval(minutes:=62), '%h hr %s')",

"returns": "'1 hr 120s'"

}, {

Yes that's correct, only the second format specifier must be %ss to show 120s (as written it will show 1 hr 120). Happy to add these examples although for uniformity I think it looks better using either hr and sec or h and s but not mixing both variants.

DelazJ · 2023-12-17T06:49:16Z

Forgot to say: thanks for providing a new feature and for your patience.

Malvineous · 2023-12-19T04:11:24Z

@DelazJ No problems at all, many thanks for reviewing!

agiudiceandrea · 2024-02-17T07:53:52Z

@Malvineous, thanks for submitting this PR.
IMHO this PR is not receiving the attention it deserves. Unfortunately I cannot review/approve it. Hopefully some developer will do that in time for the upcoming 3.36 release.

Malvineous · 2024-03-03T13:24:08Z

Thanks @agiudiceandrea let's hope so!

nyalldawson · 2024-03-20T00:56:20Z