diff --git a/src/changes/changes.xml b/src/changes/changes.xml index 6e523cf37..b0b6ac5e4 100644 --- a/src/changes/changes.xml +++ b/src/changes/changes.xml @@ -88,6 +88,8 @@ The type attribute can be add,update,fix,remove. Add JavaVersion.JAVA_17. Add missing boolean[] join method #686. Add StringUtils.substringBefore(String, int). + Add Range.INTEGER. + Add DurationUtils. Introduce the use of @Nonnull, and @Nullable, and the Objects class as a helper tool. Enable Dependabot #587. diff --git a/src/main/java/org/apache/commons/lang3/math/NumberUtils.java b/src/main/java/org/apache/commons/lang3/math/NumberUtils.java index ade72b0d1..45c5dbf1b 100644 --- a/src/main/java/org/apache/commons/lang3/math/NumberUtils.java +++ b/src/main/java/org/apache/commons/lang3/math/NumberUtils.java @@ -70,6 +70,20 @@ public class NumberUtils { /** Reusable Float constant for minus one. */ public static final Float FLOAT_MINUS_ONE = Float.valueOf(-1.0f); + /** + * {@link Integer#MAX_VALUE} as a {@link Long}. + * + * @since 3.12.0 + */ + public static final Long LONG_INT_MAX_VALUE = Long.valueOf(Integer.MAX_VALUE); + + /** + * {@link Integer#MIN_VALUE} as a {@link Long}. + * + * @since 3.12.0 + */ + public static final Long LONG_INT_MIN_VALUE = Long.valueOf(Integer.MIN_VALUE); + /** *

{@code NumberUtils} instances should NOT be constructed in standard programming. diff --git a/src/main/java/org/apache/commons/lang3/time/DurationUtils.java b/src/main/java/org/apache/commons/lang3/time/DurationUtils.java new file mode 100644 index 000000000..1d87e12d0 --- /dev/null +++ b/src/main/java/org/apache/commons/lang3/time/DurationUtils.java @@ -0,0 +1,60 @@ +/* + * 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 + * + * http://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.Duration; +import java.util.Objects; + +import org.apache.commons.lang3.Range; +import org.apache.commons.lang3.math.NumberUtils; + +/** + * Utilities for {@link Duration}. + * + * @since 3.12.0 + */ +public class DurationUtils { + + /** + * An Integer Range that accepts Longs. + */ + static final Range LONG_TO_INT_RANGE = Range.between( + NumberUtils.LONG_INT_MIN_VALUE, + NumberUtils.LONG_INT_MAX_VALUE); + + /** + * Converts a Duration to milliseconds bound to an int (instead of a long). + *

+ * Handy for low-level APIs that take millisecond timeouts in ints rather than longs. + *

+ * + * + * @param duration The duration to convert, not null. + * @return int milliseconds. + */ + public static int toMillisInt(final Duration duration) { + Objects.requireNonNull(duration, "duration"); + // intValue() does not do a narrowing conversion here + return DurationUtils.LONG_TO_INT_RANGE.fit(Long.valueOf(duration.toMillis())).intValue(); + } +} diff --git a/src/test/java/org/apache/commons/lang3/time/DurationUtilsTest.java b/src/test/java/org/apache/commons/lang3/time/DurationUtilsTest.java new file mode 100644 index 000000000..2ef2d627b --- /dev/null +++ b/src/test/java/org/apache/commons/lang3/time/DurationUtilsTest.java @@ -0,0 +1,65 @@ +/* + * 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 + * + * http://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.Duration; + +import org.apache.commons.lang3.math.NumberUtils; +import org.junit.jupiter.api.Test; + +/** + * Tests {@link DurationUtils}. + */ +public class DurationUtilsTest { + + @Test + public void testLongToIntRangeFit() { + assertEquals(0, DurationUtils.LONG_TO_INT_RANGE.fit(0L)); + // + assertEquals(Integer.MIN_VALUE, DurationUtils.LONG_TO_INT_RANGE.fit(NumberUtils.LONG_INT_MIN_VALUE)); + assertEquals(Integer.MIN_VALUE, DurationUtils.LONG_TO_INT_RANGE.fit(NumberUtils.LONG_INT_MIN_VALUE - 1)); + assertEquals(Integer.MIN_VALUE, DurationUtils.LONG_TO_INT_RANGE.fit(NumberUtils.LONG_INT_MIN_VALUE - 2)); + assertEquals(Integer.MAX_VALUE, DurationUtils.LONG_TO_INT_RANGE.fit(NumberUtils.LONG_INT_MAX_VALUE)); + assertEquals(Integer.MAX_VALUE, DurationUtils.LONG_TO_INT_RANGE.fit(NumberUtils.LONG_INT_MAX_VALUE + 1)); + assertEquals(Integer.MAX_VALUE, DurationUtils.LONG_TO_INT_RANGE.fit(NumberUtils.LONG_INT_MAX_VALUE + 2)); + // + assertEquals(Integer.MIN_VALUE, DurationUtils.LONG_TO_INT_RANGE.fit(Long.MIN_VALUE)); + assertEquals(Integer.MAX_VALUE, DurationUtils.LONG_TO_INT_RANGE.fit(Long.MAX_VALUE)); + // + assertEquals(Short.MIN_VALUE, DurationUtils.LONG_TO_INT_RANGE.fit((long) Short.MIN_VALUE)); + assertEquals(Short.MAX_VALUE, DurationUtils.LONG_TO_INT_RANGE.fit((long) Short.MAX_VALUE)); + } + + @Test + public void testToMillisInt() { + assertEquals(0, DurationUtils.toMillisInt(Duration.ZERO)); + assertEquals(1, DurationUtils.toMillisInt(Duration.ofMillis(1))); + // + assertEquals(Integer.MIN_VALUE, DurationUtils.toMillisInt(Duration.ofMillis(Integer.MIN_VALUE))); + assertEquals(Integer.MAX_VALUE, DurationUtils.toMillisInt(Duration.ofMillis(Integer.MAX_VALUE))); + assertEquals(Integer.MAX_VALUE, DurationUtils.toMillisInt(Duration.ofMillis(NumberUtils.LONG_INT_MAX_VALUE + 1))); + assertEquals(Integer.MAX_VALUE, DurationUtils.toMillisInt(Duration.ofMillis(NumberUtils.LONG_INT_MAX_VALUE + 2))); + assertEquals(Integer.MIN_VALUE, DurationUtils.toMillisInt(Duration.ofMillis(NumberUtils.LONG_INT_MIN_VALUE - 1))); + assertEquals(Integer.MIN_VALUE, DurationUtils.toMillisInt(Duration.ofMillis(NumberUtils.LONG_INT_MIN_VALUE - 2))); + // + assertEquals(Integer.MIN_VALUE, DurationUtils.toMillisInt(Duration.ofNanos(Long.MIN_VALUE))); + assertEquals(Integer.MAX_VALUE, DurationUtils.toMillisInt(Duration.ofNanos(Long.MAX_VALUE))); + } +}