1 files changed, 43 insertions, 0 deletions
diff --git a/src/main/java/com/code_intelligence/jazzer/mutation/annotation/WithUtf8Length.java b/src/main/java/com/code_intelligence/jazzer/mutation/annotation/WithUtf8Length.java
new file mode 100644
index 00000000..00b1f463
--- /dev/null
+++ b/src/main/java/com/code_intelligence/jazzer/mutation/annotation/WithUtf8Length.java
@@ -0,0 +1,43 @@
+/*
+ * Copyright 2023 Code Intelligence GmbH
+ *
+ * Licensed 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 com.code_intelligence.jazzer.mutation.annotation;
+
+import static java.lang.annotation.ElementType.TYPE_USE;
+import static java.lang.annotation.RetentionPolicy.RUNTIME;
+
+import java.lang.annotation.Retention;
+import java.lang.annotation.Target;
+
+/**
+ * An annotation that applies to {@link String} to <strong>limit the length of the UTF-8
+ * encoding</strong> of the string. In practical terms, this means that strings given this
+ * annotation will sometimes have a {@link String#length()} of less than
+ * {@code min} but will never exceed {@code max}. <p> Due to the fact that our String mutator is
+ * backed by the byte array mutator, it's difficult to know how many characters we'll get from the
+ * byte array we get from libfuzzer. Rather than reuse {@link WithLength} for strings which may give
+ * the impression that {@link String#length()} will return a value between {@code min} and {@code
+ * max}, we use this annotation to help make clear that the string consists of between
+ * {@code min} and {@code max} UTF-8 bytes, not necessarily (UTF-16) characters.
+ */
+@Target(TYPE_USE)
+@Retention(RUNTIME)
+@AppliesTo(String.class)
+public @interface WithUtf8Length {
+  int min() default 0;
+
+  int max() default 1000;
+}