From ed9c8dea6742e1a903a2256201c58426e99bc532 Mon Sep 17 00:00:00 2001 From: Denver Coneybeare Date: Tue, 8 Jul 2025 01:07:03 +0000 Subject: [PATCH 1/2] docs: add an example to the detailed comment in compareUtf8Strings() --- .../java/com/google/cloud/firestore/Order.java | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/google-cloud-firestore/src/main/java/com/google/cloud/firestore/Order.java b/google-cloud-firestore/src/main/java/com/google/cloud/firestore/Order.java index 8cfd107d6..cfb6c5a24 100644 --- a/google-cloud-firestore/src/main/java/com/google/cloud/firestore/Order.java +++ b/google-cloud-firestore/src/main/java/com/google/cloud/firestore/Order.java @@ -162,6 +162,22 @@ public static int compareUtf8Strings(String left, String right) { // used to represent code points greater than 0xFFFF which have 4-byte UTF-8 representations // and are lexicographically greater than the 1, 2, or 3-byte representations of code points // less than or equal to 0xFFFF. + // + // An example of why Case 2 is required is comparing the following two Unicode code points: + // + // |-----------------------|------------|---------------------|-----------------| + // | Name | Code Point | UTF-8 Encoding | UTF-16 Encoding | + // |-----------------------|------------|---------------------|-----------------| + // | Replacement Character | U+FFFD | 0xEF 0xBF 0xBD | 0xFFFD | + // | Grinning Face | U+1F600 | 0xF0 0x9F 0x98 0x80 | 0xD83D 0xDE00 | + // |-----------------------|------------|---------------------|-----------------| + // + // A lexicographical comparison of the UTF-8 encodings of these code points would order + // "Replacement Character" _before_ "Grinning Face" because 0xEF is less than 0xF0. However, a + // direct comparison of the UTF-16 code units, as would be done in case 1, would erroneously + // produce the _opposite_ ordering, because 0xFFFD is _greater than_ 0xD83D. As it turns out, + // this relative ordering holds for all comparisons of UTF-16 code points requiring a surrogate + // pair with those that do not. final int length = Math.min(left.length(), right.length()); for (int i = 0; i < length; i++) { final char leftChar = left.charAt(i); From f6129b70f0fddad602d4ed2f40f0ebddb69edb35 Mon Sep 17 00:00:00 2001 From: Denver Coneybeare Date: Mon, 7 Jul 2025 21:09:47 -0400 Subject: [PATCH 2/2] mvn com.spotify.fmt:fmt-maven-plugin:format --- .../src/main/java/com/google/cloud/firestore/Order.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/google-cloud-firestore/src/main/java/com/google/cloud/firestore/Order.java b/google-cloud-firestore/src/main/java/com/google/cloud/firestore/Order.java index cfb6c5a24..c38214022 100644 --- a/google-cloud-firestore/src/main/java/com/google/cloud/firestore/Order.java +++ b/google-cloud-firestore/src/main/java/com/google/cloud/firestore/Order.java @@ -177,7 +177,7 @@ public static int compareUtf8Strings(String left, String right) { // direct comparison of the UTF-16 code units, as would be done in case 1, would erroneously // produce the _opposite_ ordering, because 0xFFFD is _greater than_ 0xD83D. As it turns out, // this relative ordering holds for all comparisons of UTF-16 code points requiring a surrogate - // pair with those that do not. + // pair with those that do not. final int length = Math.min(left.length(), right.length()); for (int i = 0; i < length; i++) { final char leftChar = left.charAt(i);