feat: conditional, relative/absolute date/time formatter

Signed-off-by: Andy Scherzinger <[email protected]>

Author: AndyScherzinger

core/src/main/java/com/nextcloud/android/common/core/utils/DateFormatter.kt

@@ -0,0 +1,90 @@
+/**
+ * Nextcloud Android Common Library
+ *
+ * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: MIT
+ */
+package com.nextcloud.android.common.core.utils
+
+import android.content.Context
+import android.text.format.DateFormat
+import com.nextcloud.android.common.core.R
+import java.text.SimpleDateFormat
+import java.util.Calendar
+
+/**
+ * Helper implementation for date formatting.
+ */
+class DateFormatter(
+    private val context: Context
+) {
+    private val sdfDays: SimpleDateFormat
+    private val sdfMonths: SimpleDateFormat
+    private val sdfYears: SimpleDateFormat
+
+    /**
+     * constructor.
+     *
+     * @param context Context needed to load locale-specific date/time-patterns and translation strings.
+     */
+    init {
+        val locale = this.context.resources.configuration.locale
+        this.sdfDays = SimpleDateFormat(DateFormat.getBestDateTimePattern(locale, "EEE"), locale)
+        this.sdfMonths =
+            SimpleDateFormat(DateFormat.getBestDateTimePattern(locale, "MMM d"), locale)
+        this.sdfYears =
+            SimpleDateFormat(DateFormat.getBestDateTimePattern(locale, "MMM d, yyyy"), locale)
+    }
+
+    /**
+     * Returns a conditionally relative date formated string.
+     * For anything less than 1h hours a relative time in minutes will be returned,
+     * for anything less than 24h hours a relative time in hours will be returned,
+     * for anything less than 6 days the day of the week in short form,
+     * for anything up to 364 days a day and moth string will be returned,
+     * for anything more than 364 days from now a complete date will be returned.
+     *
+     * @param calendar to be formatted calendar
+     * @return formatted date strings
+     */
+    fun getConditionallyRelativeFormattedTimeSpan(calendar: Calendar): String {
+        var timeSpan = ""
+        val span = System.currentTimeMillis() - calendar.getTimeInMillis()
+        if (span < ONE_MINUTE_IN_MILLIS) {
+            // less than 1m
+            timeSpan = context.getString(R.string.date_formatting_now)
+        } else if (span < ONE_HOUR_IN_MILLIS) {
+            // less than 1h
+            timeSpan =
+                context.getString(
+                    R.string.date_formatting_relative_minutes,
+                    span / ONE_MINUTE_IN_MILLIS
+                )
+        } else if (span < ONE_DAY_IN_MILLIS) {
+            // less than 24h
+            val hours: Int = span.toInt() / ONE_HOUR_IN_MILLIS
+            timeSpan =
+                context
+                    .resources
+                    .getQuantityString(R.plurals.date_formatting_relative_hours, hours, hours)
+        } else if (span <= SIX_DAYS_IN_MILLIS) {
+            // less than 6 days
+            timeSpan = sdfDays.format(calendar.getTime())
+        } else if (span <= YEAR_IN_MILLIS) {
+            // up to 364 days
+            timeSpan = sdfMonths.format(calendar.getTime())
+        } else {
+            // more than 364 days
+            timeSpan = sdfYears.format(calendar.getTime())
+        }
+        return timeSpan
+    }
+
+    companion object {
+        private const val ONE_MINUTE_IN_MILLIS = 60000
+        private const val ONE_HOUR_IN_MILLIS: Int = ONE_MINUTE_IN_MILLIS * 60
+        private const val ONE_DAY_IN_MILLIS: Int = ONE_HOUR_IN_MILLIS * 24
+        private const val SIX_DAYS_IN_MILLIS: Int = ONE_DAY_IN_MILLIS * 6
+        private const val YEAR_IN_MILLIS: Long = ONE_DAY_IN_MILLIS * 364L
+    }
+}

core/src/main/res/values/strings.xml

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+  ~  Nextcloud Android Common Library
+  ~ 
+  ~ SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+  ~ SPDX-License-Identifier: MIT
+-->
+<resources>
+    <!-- relative time less than 1 minute using the term: Now -->
+    <string name="date_formatting_now">Now</string>
+    <!-- relative time in minutes, less than 1 hour, i.e. 1m, 5m, 59m -->
+    <string name="date_formatting_relative_minutes">%dm</string>
+    <!-- relative time in hours, less than 1 day, i.e. 1h, 5h, 23h -->
+    <plurals name="date_formatting_relative_hours">
+        <item quantity="one">%dh</item>
+        <item quantity="other">%dh</item>
+    </plurals>
+</resources>