Add initial `BLI_math_time` with a 'seconds decompose' function.

Allows to decompose a given amount of seconds into a random set of
days/hours/minutes/seconds/milliseconds values.

Also add matching test.

Differential Revision: https://developer.blender.org/D11581

source/blender/blenlib/BLI_math.h

@@ -70,4 +70,5 @@
 #include "BLI_math_rotation.h"
 #include "BLI_math_solvers.h"
 #include "BLI_math_statistics.h"
+#include "BLI_math_time.h"
 #include "BLI_math_vector.h"

source/blender/blenlib/BLI_math_time.h

@@ -0,0 +1,51 @@
+/*
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License
+ * as published by the Free Software Foundation; either version 2
+ * of the License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+ *
+ * The Original Code is Copyright (C) 2021 by Blender Foundation.
+ * All rights reserved.
+ */
+
+#pragma once
+
+/** \file
+ * \ingroup bli
+ */
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/************************ Time constants definitions***************************/
+#define SECONDS_IN_MILLISECONDS 0.001
+#define SECONDS_IN_MINUTE 60.0
+#define MINUTES_IN_HOUR 60.0
+#define HOURS_IN_DAY 24.0
+
+#define MINUTES_IN_DAY (MINUTES_IN_HOUR * HOURS_IN_DAY)
+#define SECONDS_IN_DAY (MINUTES_IN_DAY * SECONDS_IN_MINUTE)
+#define SECONDS_IN_HOUR (MINUTES_IN_HOUR * SECONDS_IN_MINUTE)
+
+void BLI_math_time_seconds_decompose(double seconds,
+                                     double *r_days,
+                                     double *r_hours,
+                                     double *r_minutes,
+                                     double *r_seconds,
+                                     double *r_milliseconds);
+
+/**************************** Inline Definitions ******************************/
+
+#ifdef __cplusplus
+}
+#endif

source/blender/blenlib/CMakeLists.txt

@@ -103,6 +103,7 @@ set(SRC
   intern/math_rotation.c
   intern/math_solvers.c
   intern/math_statistics.c
+  intern/math_time.c
   intern/math_vec.cc
   intern/math_vector.c
   intern/math_vector_inline.c
@@ -241,6 +242,7 @@ set(SRC
   BLI_math_rotation.h
   BLI_math_solvers.h
   BLI_math_statistics.h
+  BLI_math_time.h
   BLI_math_vector.h
   BLI_memarena.h
   BLI_memblock.h
@@ -419,6 +421,7 @@ if(WITH_GTESTS)
     tests/BLI_math_matrix_test.cc
     tests/BLI_math_rotation_test.cc
     tests/BLI_math_solvers_test.cc
+    tests/BLI_math_time_test.cc
     tests/BLI_math_vector_test.cc
     tests/BLI_memiter_test.cc
     tests/BLI_memory_utils_test.cc

source/blender/blenlib/intern/math_time.c

@@ -0,0 +1,69 @@
+/*
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License
+ * as published by the Free Software Foundation; either version 2
+ * of the License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+ *
+ * The Original Code is Copyright (C) 2021 by Blender Foundation.
+ * All rights reserved.
+ */
+
+/** \file
+ * \ingroup bli
+ */
+
+#include "BLI_math.h"
+
+/** Explode given time value expressed in seconds, into a set of days, hours, minutes, seconds
+ * and/or milliseconds (depending on which return parameters are not NULL).
+ *
+ * \note: The smallest given return parameter will get the potential fractional remaining time
+ * value.
+ */
+void BLI_math_time_seconds_decompose(double seconds,
+                                     double *r_days,
+                                     double *r_hours,
+                                     double *r_minutes,
+                                     double *r_seconds,
+                                     double *r_milliseconds)
+{
+  BLI_assert(r_days != NULL || r_hours != NULL || r_minutes != NULL || r_seconds != NULL ||
+             r_milliseconds != NULL);
+
+  if (r_days != NULL) {
+    seconds = modf(seconds / SECONDS_IN_DAY, r_days) * SECONDS_IN_DAY;
+  }
+  if (r_hours != NULL) {
+    seconds = modf(seconds / SECONDS_IN_HOUR, r_hours) * SECONDS_IN_HOUR;
+  }
+  if (r_minutes != NULL) {
+    seconds = modf(seconds / SECONDS_IN_MINUTE, r_minutes) * SECONDS_IN_MINUTE;
+  }
+  if (r_seconds != NULL) {
+    seconds = modf(seconds, r_seconds);
+  }
+  if (r_milliseconds != NULL) {
+    *r_milliseconds = seconds / SECONDS_IN_MILLISECONDS;
+  }
+  else if (r_seconds != NULL) {
+    *r_seconds += seconds;
+  }
+  else if (r_minutes != NULL) {
+    *r_minutes += seconds / SECONDS_IN_MINUTE;
+  }
+  else if (r_hours != NULL) {
+    *r_hours += seconds / SECONDS_IN_HOUR;
+  }
+  else if (r_days != NULL) {
+    *r_days = seconds / SECONDS_IN_DAY;
+  }
+}

source/blender/blenlib/tests/BLI_math_time_test.cc

@@ -0,0 +1,35 @@
+/* Apache License, Version 2.0 */
+
+#include "testing/testing.h"
+
+#include "BLI_math.h"
+
+TEST(math_time, SecondsExplode)
+{
+  const double seconds = 2.0 * SECONDS_IN_DAY + 13.0 * SECONDS_IN_HOUR + 33.0 * SECONDS_IN_MINUTE +
+                         9.0 + 369.0 * SECONDS_IN_MILLISECONDS;
+  const double epsilon = 1e-8;
+
+  double r_days, r_hours, r_minutes, r_seconds, r_milliseconds;
+
+  BLI_math_time_seconds_decompose(
+      seconds, &r_days, &r_hours, &r_minutes, &r_seconds, &r_milliseconds);
+  EXPECT_NEAR(2.0, r_days, epsilon);
+  EXPECT_NEAR(13.0, r_hours, epsilon);
+  EXPECT_NEAR(33.0, r_minutes, epsilon);
+  EXPECT_NEAR(9.0, r_seconds, epsilon);
+  EXPECT_NEAR(369.0, r_milliseconds, epsilon);
+
+  BLI_math_time_seconds_decompose(seconds, NULL, &r_hours, &r_minutes, &r_seconds, NULL);
+  EXPECT_NEAR(61.0, r_hours, epsilon);
+  EXPECT_NEAR(33.0, r_minutes, epsilon);
+  EXPECT_NEAR(9.369, r_seconds, epsilon);
+
+  BLI_math_time_seconds_decompose(seconds, NULL, NULL, NULL, &r_seconds, NULL);
+  EXPECT_NEAR(seconds, r_seconds, epsilon);
+
+  BLI_math_time_seconds_decompose(seconds, &r_days, NULL, &r_minutes, NULL, &r_milliseconds);
+  EXPECT_NEAR(2.0, r_days, epsilon);
+  EXPECT_NEAR(813.0, r_minutes, epsilon);
+  EXPECT_NEAR(9369.0, r_milliseconds, epsilon);
+}