This is an automated email from the ASF dual-hosted git repository.
garydgregory pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-lang.git
The following commit(s) were added to refs/heads/master by this push:
new 531e2a2cf Add Instants.toEpochMillis(Instant) (#1680)
531e2a2cf is described below
commit 531e2a2cf1c1e56708859ad2579a5e5760140714
Author: Gary Gregory <[email protected]>
AuthorDate: Fri May 29 06:12:50 2026 -0400
Add Instants.toEpochMillis(Instant) (#1680)
---
.../org/apache/commons/lang3/time/Instants.java | 56 +++++++++++++++
.../apache/commons/lang3/time/InstantsTest.java | 83 ++++++++++++++++++++++
2 files changed, 139 insertions(+)
diff --git a/src/main/java/org/apache/commons/lang3/time/Instants.java
b/src/main/java/org/apache/commons/lang3/time/Instants.java
new file mode 100644
index 000000000..3c092f96e
--- /dev/null
+++ b/src/main/java/org/apache/commons/lang3/time/Instants.java
@@ -0,0 +1,56 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.commons.lang3.time;
+
+import java.time.Instant;
+
+/**
+ * Works with {@link Instant}s.
+ *
+ * @since 3.21.0
+ */
+public class Instants {
+
+ /**
+ * Converts an Instant to milliseconds bound to a {@code long} without
throwing {@link ArithmeticException}.
+ * <ul>
+ * <li>If the duration milliseconds are greater than {@link
Long#MAX_VALUE}, then return {@link Long#MAX_VALUE}.</li>
+ * <li>If the duration milliseconds are lesser than {@link
Long#MIN_VALUE}, then return {@link Long#MIN_VALUE}.</li>
+ * </ul>
+ *
+ * @param instant The instant to convert, not null.
+ * @return long milliseconds.
+ * @see Instant#toEpochMilli()
+ * @see Long#MIN_VALUE
+ * @see Long#MAX_VALUE
+ */
+ public static long toEpochMillis(final Instant instant) {
+ try {
+ return instant.toEpochMilli();
+ } catch (final ArithmeticException e) {
+ return instant.getEpochSecond() < 0 ? Long.MIN_VALUE :
Long.MAX_VALUE;
+ }
+ }
+
+ /**
+ * No instances needed.
+ */
+ private Instants() {
+ // empty.
+ }
+}
diff --git a/src/test/java/org/apache/commons/lang3/time/InstantsTest.java
b/src/test/java/org/apache/commons/lang3/time/InstantsTest.java
new file mode 100644
index 000000000..a64644b06
--- /dev/null
+++ b/src/test/java/org/apache/commons/lang3/time/InstantsTest.java
@@ -0,0 +1,83 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.commons.lang3.time;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+import java.time.Instant;
+
+import org.apache.commons.lang3.AbstractLangTest;
+import org.junit.jupiter.api.Test;
+
+/**
+ * Tests {@link Instants}.
+ */
+class InstantsTest extends AbstractLangTest {
+
+ /**
+ * An Instant far in the future whose epoch-millis overflow {@code long}:
seconds chosen so that {@code seconds * 1_000} exceeds {@link Long#MAX_VALUE}.
+ */
+ private static final Instant INSTANT_FAR_FUTURE =
Instant.ofEpochSecond(Long.MAX_VALUE / 1_000 + 1_000);
+ /**
+ * An Instant far in the past whose epoch-millis underflow {@code long}:
seconds chosen so that {@code seconds * 1_000} is less than {@link
Long#MIN_VALUE}.
+ */
+ private static final Instant INSTANT_FAR_PAST =
Instant.ofEpochSecond(Long.MIN_VALUE / 1_000 - 1_000);
+
+ @Test
+ void testToEpochMillisEpoch() {
+ assertEquals(0L, Instants.toEpochMillis(Instant.EPOCH));
+ }
+
+ @Test
+ void testToEpochMillisMaxValue() {
+ assertEquals(Long.MAX_VALUE,
Instants.toEpochMillis(Instant.ofEpochMilli(Long.MAX_VALUE)));
+ }
+
+ @Test
+ void testToEpochMillisMinValue() {
+ assertEquals(Long.MIN_VALUE,
Instants.toEpochMillis(Instant.ofEpochMilli(Long.MIN_VALUE)));
+ }
+
+ @Test
+ void testToEpochMillisNegativeMillis() {
+ final Instant instant = Instant.ofEpochMilli(-1_000_000L);
+ assertEquals(-1_000_000L, Instants.toEpochMillis(instant));
+ }
+
+ @Test
+ void testToEpochMillisNormalInstant() {
+ final Instant instant = Instant.ofEpochMilli(1_000_000L);
+ assertEquals(1_000_000L, Instants.toEpochMillis(instant));
+ }
+
+ @Test
+ void testToEpochMillisNow() {
+ final Instant now = Instant.now();
+ assertEquals(now.toEpochMilli(), Instants.toEpochMillis(now));
+ }
+
+ @Test
+ void testToEpochMillisOverflowReturnsMaxValue() {
+ assertEquals(Long.MAX_VALUE,
Instants.toEpochMillis(INSTANT_FAR_FUTURE));
+ }
+
+ @Test
+ void testToEpochMillisUnderflowReturnsMinValue() {
+ assertEquals(Long.MIN_VALUE, Instants.toEpochMillis(INSTANT_FAR_PAST));
+ }
+}
