Introduce a ByteString.substringNoCopy() method.

PiperOrigin-RevId: 866483595

Author: protobuf-github-bot

java/core/src/main/java/com/google/protobuf/ByteString.java

@@ -127,7 +127,7 @@ public byte[] copyFrom(byte[] bytes, int offset, int size) {
   /**
    * Gets the byte at the given index. This method should be used only for random access to
    * individual bytes. To access bytes sequentially, use the {@link ByteIterator} returned by {@link
-   * #iterator()}, and call {@link #substring(int, int)} first if necessary.
+   * #iterator()}, and call {@link #substringNoCopy(int, int)} first if necessary.
    *
    * @param index index of byte
    * @return the value
@@ -317,7 +317,7 @@ public static Comparator<ByteString> unsignedLexicographicalComparator() {
    * Return the substring from {@code beginIndex}, inclusive, to the end of the string.
    *
    * @param beginIndex start at this index
-   * @return substring sharing underlying data
+   * @return substring
    * @throws IndexOutOfBoundsException if {@code beginIndex < 0} or {@code beginIndex > size()}.
    */
   public final ByteString substring(int beginIndex) {
@@ -329,12 +329,38 @@ public final ByteString substring(int beginIndex) {
    *
    * @param beginIndex start at this index
    * @param endIndex the last character is the one before this index
-   * @return substring sharing underlying data
+   * @return substring
    * @throws IndexOutOfBoundsException if {@code beginIndex < 0}, {@code endIndex > size()}, or
    *     {@code beginIndex > endIndex}.
    */
   public abstract ByteString substring(int beginIndex, int endIndex);
 
+  /**
+   * Return the substring from {@code beginIndex}, inclusive, to the end of the string. Unlike
+   * {@link #substring(int)} this method tries to avoid copies of the underlying data where
+   * possible, but may still copy in some situations.
+   *
+   * @param beginIndex start at this index
+   * @return substring sharing underlying data
+   * @throws IndexOutOfBoundsException if {@code beginIndex < 0} or {@code beginIndex > size()}.
+   */
+  public final ByteString substringNoCopy(int beginIndex) {
+    return substringNoCopy(beginIndex, size());
+  }
+
+  /**
+   * Return the substring from {@code beginIndex}, inclusive, to {@code endIndex}, exclusive. Unlike
+   * {@link #substring(int, int)} this method tries to avoid copies of the underlying data where
+   * possible, but may still copy in some situations.
+   *
+   * @param beginIndex start at this index
+   * @param endIndex the last character is the one before this index
+   * @return substring sharing underlying data
+   * @throws IndexOutOfBoundsException if {@code beginIndex < 0}, {@code endIndex > size()}, or
+   *     {@code beginIndex > endIndex}.
+   */
+  public abstract ByteString substringNoCopy(int beginIndex, int endIndex);
+
   /**
    * Tests if this bytestring starts with the specified prefix. Similar to {@link
    * String#startsWith(String)}
@@ -344,7 +370,7 @@ public final ByteString substring(int beginIndex) {
    *     byte sequence represented by this string; <code>false</code> otherwise.
    */
   public final boolean startsWith(ByteString prefix) {
-    return size() >= prefix.size() && substring(0, prefix.size()).equals(prefix);
+    return size() >= prefix.size() && substringNoCopy(0, prefix.size()).equals(prefix);
   }
 
   /**
@@ -356,7 +382,7 @@ public final boolean startsWith(ByteString prefix) {
    *     byte sequence represented by this string; <code>false</code> otherwise.
    */
   public final boolean endsWith(ByteString suffix) {
-    return size() >= suffix.size() && substring(size() - suffix.size()).equals(suffix);
+    return size() >= suffix.size() && substringNoCopy(size() - suffix.size()).equals(suffix);
   }
 
   // =================================================================
@@ -774,7 +800,7 @@ public void copyTo(byte[] target, int offset) {
    * @param targetOffset offset within the target buffer
    * @param numberToCopy number of bytes to copy
    * @throws IndexOutOfBoundsException if an offset or size is negative or too large
-   * @deprecated Use {@code byteString.substring(sourceOffset, sourceOffset +
+   * @deprecated Use {@code byteString.substringNoCopy(sourceOffset, sourceOffset +
    *     numberToCopy).copyTo(target, targetOffset)} instead.
    */
   @Deprecated
@@ -797,7 +823,7 @@ protected abstract void copyToInternal(
    * Copies bytes into a ByteBuffer.
    *
    * <p>To copy a subset of bytes, you call this method on the return value of {@link
-   * #substring(int, int)}. Example: {@code byteString.substring(start, end).copyTo(target)}
+   * #substring(int, int)}. Example: {@code byteString.substringNoCopy(start, end).copyTo(target)}
    *
    * @param target ByteBuffer to copy into.
    * @throws java.nio.ReadOnlyBufferException if the {@code target} is read-only
@@ -1434,7 +1460,7 @@ public final String toString() {
   private String truncateAndEscapeForDisplay() {
     final int limit = 50;
 
-    return size() <= limit ? escapeBytes(this) : escapeBytes(substring(0, limit - 3)) + "...";
+    return size() <= limit ? escapeBytes(this) : escapeBytes(substringNoCopy(0, limit - 3)) + "...";
   }
 
   /**
@@ -1511,6 +1537,17 @@ public ByteString substring(int beginIndex, int endIndex) {
       return new BoundedByteString(bytes, beginIndex, length);
     }
 
+    @Override
+    public ByteString substringNoCopy(int beginIndex, int endIndex) {
+      final int length = checkRange(beginIndex, endIndex, size());
+
+      if (length == 0) {
+        return ByteString.EMPTY;
+      }
+
+      return new BoundedByteString(bytes, beginIndex, length);
+    }
+
     // =================================================================
     // ByteString -> byte[]
 
@@ -1607,7 +1644,7 @@ boolean equalsRange(ByteString other, int offset, int length) {
         return subArrayEquals(bytes, 0, bbsOther.bytes, bbsOther.offset + offset, length);
       }
 
-      return other.substring(offset, offset + length).equals(substring(0, length));
+      return other.substringNoCopy(offset, offset + length).equals(substringNoCopy(0, length));
     }
 
     @Override
@@ -1702,6 +1739,15 @@ public ByteString substring(int beginIndex, int endIndex) {
       return new BoundedByteString(bytes, offset + beginIndex, substringLength);
     }
 
+    @Override
+    public ByteString substringNoCopy(int beginIndex, int endIndex) {
+      int substringLength = checkRange(beginIndex, endIndex, length);
+      if (substringLength == 0) {
+        return ByteString.EMPTY;
+      }
+      return new BoundedByteString(bytes, offset + beginIndex, substringLength);
+    }
+
     // =================================================================
     // ByteString -> byte[]
     @Override
@@ -1782,8 +1828,8 @@ boolean equalsRange(ByteString other, int offset, int length) {
       }
 
       return other
-          .substring(offset, offset + length)
-          .equals(substring(this.offset, this.offset + length));
+          .substringNoCopy(offset, offset + length)
+          .equals(substringNoCopy(this.offset, this.offset + length));
     }
 
     @Override

java/core/src/main/java/com/google/protobuf/RopeByteString.java

@@ -339,6 +339,24 @@ protected boolean isBalanced() {
    */
   @Override
   public ByteString substring(int beginIndex, int endIndex) {
+    return substringNoCopy(beginIndex, endIndex);
+  }
+
+  /**
+   * Takes a substring of this one. This involves recursive descent along the left and right edges
+   * of the substring, and referencing any wholly contained segments in between. Any leaf nodes
+   * entirely uninvolved in the substring will not be referenced by the substring.
+   *
+   * <p>Substrings of {@code length < 2} should result in at most a single recursive call chain,
+   * terminating at a leaf node. Thus the result will be a {@link
+   * com.google.protobuf.ByteString.LeafByteString}.
+   *
+   * @param beginIndex start at this index
+   * @param endIndex the last character is the one before this index
+   * @return substring leaf node or tree
+   */
+  @Override
+  public ByteString substringNoCopy(int beginIndex, int endIndex) {
     final int length = checkRange(beginIndex, endIndex, totalLength);
 
     if (length == 0) {

java/core/src/test/java/com/google/protobuf/ByteStringTest.java

@@ -119,6 +119,15 @@ public void testSubstring_beginIndex() {
         .isTrue();
   }
 
+  @Test
+  public void testSubstringNoCopy_beginIndex() {
+    byte[] bytes = getTestBytes();
+    ByteString substring = ByteString.copyFrom(bytes).substringNoCopy(500);
+    assertWithMessage("substring must contain the tail of the string")
+        .that(isArrayRange(substring.toByteArray(), bytes, 500, bytes.length - 500))
+        .isTrue();
+  }
+
   @Test
   public void testEmpty_isEmpty() {
     ByteString byteString = ByteString.empty();
@@ -732,6 +741,27 @@ public void testSubstringParity() {
         .isEqualTo(concreteSubstring.hashCode());
   }
 
+  @Test
+  public void testSubstringNoCopyParity() {
+    byte[] bigBytes = getTestBytes(2048 * 1024, 113344L);
+    int start = 512 * 1024 - 3333;
+    int end = 512 * 1024 + 7777;
+    ByteString concreteSubstring = ByteString.copyFrom(bigBytes).substringNoCopy(start, end);
+    boolean ok = true;
+    for (int i = start; ok && i < end; ++i) {
+      ok = (bigBytes[i] == concreteSubstring.byteAt(i - start));
+    }
+    assertWithMessage("Concrete substring didn't capture the right bytes").that(ok).isTrue();
+
+    ByteString literalString = ByteString.copyFrom(bigBytes, start, end - start);
+    assertWithMessage("Substring must be equal to literal string")
+        .that(literalString)
+        .isEqualTo(concreteSubstring);
+    assertWithMessage("Substring must have same hashcode as literal string")
+        .that(literalString.hashCode())
+        .isEqualTo(concreteSubstring.hashCode());
+  }
+
   @Test
   public void testCompositeSubstring() {
     byte[] referenceBytes = getTestBytes(77748, 113344L);
@@ -772,6 +802,46 @@ public void testCompositeSubstring() {
         .isFalse();
   }
 
+  @Test
+  public void testCompositeSubstringNoCopy() {
+    byte[] referenceBytes = getTestBytes(77748, 113344L);
+
+    List<ByteString> pieces = makeConcretePieces(referenceBytes);
+    ByteString listString = ByteString.copyFrom(pieces);
+
+    int from = 1000;
+    int to = 40000;
+    ByteString compositeSubstring = listString.substringNoCopy(from, to);
+    byte[] substringBytes = compositeSubstring.toByteArray();
+    boolean stillEqual = true;
+    for (int i = 0; stillEqual && i < to - from; ++i) {
+      stillEqual = referenceBytes[from + i] == substringBytes[i];
+    }
+    assertWithMessage("Substring must return correct bytes").that(stillEqual).isTrue();
+
+    stillEqual = true;
+    for (int i = 0; stillEqual && i < to - from; ++i) {
+      stillEqual = referenceBytes[from + i] == compositeSubstring.byteAt(i);
+    }
+    assertWithMessage("Substring must support byteAt() correctly").that(stillEqual).isTrue();
+
+    ByteString literalSubstring = ByteString.copyFrom(referenceBytes, from, to - from);
+    assertWithMessage("Composite substring must equal a literal substring over the same bytes")
+        .that(literalSubstring)
+        .isEqualTo(compositeSubstring);
+    assertWithMessage("Literal substring must equal a composite substring over the same bytes")
+        .that(compositeSubstring)
+        .isEqualTo(literalSubstring);
+
+    assertWithMessage("We must get the same hashcodes for composite and literal substrings")
+        .that(literalSubstring.hashCode())
+        .isEqualTo(compositeSubstring.hashCode());
+
+    assertWithMessage("We can't be equal to a proper substring")
+        .that(compositeSubstring.equals(literalSubstring.substring(0, literalSubstring.size() - 1)))
+        .isFalse();
+  }
+
   @Test
   public void testCopyFromList() {
     byte[] referenceBytes = getTestBytes(77748, 113344L);