clarify documentation/spec of OFFSET and OFFSET_END properties (#1761)

* clarify documentation/spec of OFFSET and OFFSET_END properties
ShiftLeftSecurity · Mar 20, 2024 · 23dab11 · 23dab11
1 parent d825dfd
commit 23dab11
Show file tree

Hide file tree

Showing 3 changed files with 12 additions and 9 deletions.
diff --git a/domainClasses/src/main/generated/io/shiftleft/codepropertygraph/generated/Properties.java b/domainClasses/src/main/generated/io/shiftleft/codepropertygraph/generated/Properties.java
@@ -203,15 +203,16 @@ it is referenced but not defined in the code (applies both to insular
 public static final overflowdb.PropertyKey<String> NODE_LABEL = new overflowdb.PropertyKey<>("NODE_LABEL");
 
 /** Start offset into the CONTENT property of the corresponding FILE node.
-The offset is measure in characters so parts of the content can easily
+The offset is such that parts of the content can easily
 be accessed via `content.substring(offset, offsetEnd)`.
+This means that the offset must be measured in utf16 encoding (i.e. neither in
+characters/codeunits nor in byte-offsets into a utf8 encoding).
 E.g. for METHOD nodes this start offset points to the start of the methods
 source code in the string holding the source code of the entire file. */
 public static final overflowdb.PropertyKey<Integer> OFFSET = new overflowdb.PropertyKey<>("OFFSET");
 
 /** End offset (exclusive) into the CONTENT property of the corresponding FILE node.
-The end offset is measure in characters so parts of the content can easily
-be accessed via `content.substring(offset, offsetEnd)`.
+See OFFSET documentation for finer details.
 E.g. for METHOD nodes this end offset points to the first code position which is
 not part of the method. */
 public static final overflowdb.PropertyKey<Integer> OFFSET_END = new overflowdb.PropertyKey<>("OFFSET_END");

diff --git a/domainClasses/src/main/generated/io/shiftleft/codepropertygraph/generated/PropertyNames.java b/domainClasses/src/main/generated/io/shiftleft/codepropertygraph/generated/PropertyNames.java
@@ -203,15 +203,16 @@ it is referenced but not defined in the code (applies both to insular
 public static final String NODE_LABEL = "NODE_LABEL";
 
 /** Start offset into the CONTENT property of the corresponding FILE node.
-The offset is measure in characters so parts of the content can easily
+The offset is such that parts of the content can easily
 be accessed via `content.substring(offset, offsetEnd)`.
+This means that the offset must be measured in utf16 encoding (i.e. neither in
+characters/codeunits nor in byte-offsets into a utf8 encoding).
 E.g. for METHOD nodes this start offset points to the start of the methods
 source code in the string holding the source code of the entire file. */
 public static final String OFFSET = "OFFSET";
 
 /** End offset (exclusive) into the CONTENT property of the corresponding FILE node.
-The end offset is measure in characters so parts of the content can easily
-be accessed via `content.substring(offset, offsetEnd)`.
+See OFFSET documentation for finer details.
 E.g. for METHOD nodes this end offset points to the first code position which is
 not part of the method. */
 public static final String OFFSET_END = "OFFSET_END";

diff --git a/schema/src/main/scala/io/shiftleft/codepropertygraph/schema/FileSystem.scala b/schema/src/main/scala/io/shiftleft/codepropertygraph/schema/FileSystem.scala
@@ -113,8 +113,10 @@ object FileSystem extends SchemaBase {
         valueType = ValueType.Int,
         comment = """
             |Start offset into the CONTENT property of the corresponding FILE node.
-            |The offset is measure in characters so parts of the content can easily
+            |The offset is such that parts of the content can easily
             |be accessed via `content.substring(offset, offsetEnd)`.
+            |This means that the offset must be measured in utf16 encoding (i.e. neither in
+            |characters/codeunits nor in byte-offsets into a utf8 encoding).
             |E.g. for METHOD nodes this start offset points to the start of the methods
             |source code in the string holding the source code of the entire file.
         """.stripMargin
@@ -127,8 +129,7 @@ object FileSystem extends SchemaBase {
         valueType = ValueType.Int,
         comment = """
           |End offset (exclusive) into the CONTENT property of the corresponding FILE node.
-          |The end offset is measure in characters so parts of the content can easily
-          |be accessed via `content.substring(offset, offsetEnd)`.
+          |See OFFSET documentation for finer details.
           |E.g. for METHOD nodes this end offset points to the first code position which is
           |not part of the method.
         """.stripMargin