Replace HumanReadableByteCount getSize/getUnit with more obvious …

…`map(func)` (#286)

Replace HumanReadableByteCount `getSize`/`getUnit` with more obvious `map(func)`

changelog/@unreleased/pr-286.v2.yml

@@ -0,0 +1,6 @@
+type: improvement
+improvement:
+  description: Replace HumanReadableByteCount `getSize`/`getUnit` with more obvious
+    `map(func)`
+  links:
+  - https://github.com/palantir/human-readable-types/pull/286

human-readable-types/src/main/java/com/palantir/humanreadabletypes/HumanReadableByteCount.java

@@ -18,6 +18,7 @@
 
 import com.fasterxml.jackson.annotation.JsonCreator;
 import com.fasterxml.jackson.annotation.JsonValue;
+import com.google.errorprone.annotations.DoNotCall;
 import com.palantir.logsafe.Preconditions;
 import com.palantir.logsafe.SafeArg;
 import java.io.Serializable;
@@ -172,16 +173,55 @@ private HumanReadableByteCount(long size, ByteUnit unit) {
         this.unit = Preconditions.checkNotNull(unit, "unit must not be null");
     }
 
+    /**
+     * Reads the value of this {@link HumanReadableByteCount} as a tuple of quantity and unit.
+     * Unlike {@link #getSize()}, this API is meant to make it obvious that the data is only meaningful
+     * when both pieces are used together.
+     *
+     * @param <T> Result type.
+     */
+    @FunctionalInterface
+    public interface SizeFunction<T> {
+
+        /**
+         * A method allowing the raw quantity and unit values to be interpreted into a more specific type.
+         *
+         * @param quantity Raw number of the given {@code unit}
+         * @param unit Unit which the {@code quantity represents}
+         * @return A representation of the byte-count value
+         */
+        T apply(long quantity, ByteUnit unit);
+    }
+
+    /**
+     * Provides the value of this {@link HumanReadableByteCount} as a tuple of quantity and unit to the
+     * {@link SizeFunction}.
+     *
+     * @param <T> Result type.
+     */
+    public <T> T map(SizeFunction<T> function) {
+        Preconditions.checkNotNull(function, "function must not be null");
+        return Preconditions.checkNotNull(function.apply(size, unit), "result must not be null");
+    }
+
     /**
      * The size of this byte string in {@link HumanReadableByteCount.ByteUnit binary units}.
+     *
+     * @deprecated in favor of {@link #map(SizeFunction)} which is harder to misuse.
      */
+    @DoNotCall
+    @Deprecated
     public long getSize() {
         return size;
     }
 
     /**
      * The {@link ByteUnit binary unit} of this byte string.
+     *
+     * @deprecated in favor of {@link #map(SizeFunction)} which is harder to misuse.
      */
+    @DoNotCall
+    @Deprecated
     public ByteUnit getUnit() {
         return unit;
     }

human-readable-types/src/test/java/com/palantir/humanreadabletypes/HumanReadableByteCountTests.java

@@ -22,6 +22,8 @@
 import com.fasterxml.jackson.core.JsonProcessingException;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import com.fasterxml.jackson.databind.node.TextNode;
+import com.palantir.humanreadabletypes.HumanReadableByteCount.ByteUnit;
+import com.palantir.logsafe.exceptions.SafeNullPointerException;
 import java.util.Arrays;
 import java.util.function.Predicate;
 import java.util.stream.Collectors;
@@ -114,6 +116,20 @@ public void testToJsonString() throws Exception {
         assertThat(toJsonString(HumanReadableByteCount.valueOf("2 bytes"))).isEqualTo("\"2 bytes\"");
     }
 
+    @Test
+    public void testMapNulls() {
+        HumanReadableByteCount bytes = HumanReadableByteCount.valueOf("1 byte");
+        assertThatThrownBy(() -> bytes.map(null)).isInstanceOf(SafeNullPointerException.class);
+        assertThatThrownBy(() -> bytes.map((_val, _unit) -> null)).isInstanceOf(SafeNullPointerException.class);
+    }
+
+    @Test
+    public void testMap() {
+        HumanReadableByteCount bytes = HumanReadableByteCount.valueOf("5mb");
+        assertThat(bytes.<ByteUnit>map((_quantity, unit) -> unit)).isEqualTo(ByteUnit.MiB);
+        assertThat(bytes.<Long>map((quantity, _unit) -> quantity)).isEqualTo(5L);
+    }
+
     private static void assertStringsEqualToBytes(long expectedBytes, String... byteCounts) {
         assertThat(Arrays.stream(byteCounts)
                         .map(HumanReadableByteCountTests::parseFromString)