Github user paul-rogers commented on a diff in the pull request:
https://github.com/apache/drill/pull/1164#discussion_r174327601
--- Diff: exec/vector/src/main/codegen/templates/VariableLengthVectors.java
---
@@ -514,6 +516,22 @@ public boolean isNull(int index){
* The equivalent Java primitive is '${minor.javaType!type.javaType}'
*
* NB: this class is automatically generated from ValueVectorTypes.tdd
using FreeMarker.
+ * </p>
+ * <h2>Contract</h2>
+ * <p>
+ * Variable length vectors do not support random writes. All set
methods must be called for with a monotonically increasing consecutive sequence
of indexes.
+ * It is possible to trim the vector by setting the value count to be
less than the number of values currently container in the vector with {@link
#setValueCount(int)}, then
+ * the process of setting values starts with the index after the last
index.
+ * </p>
+ * <p>
+ * It is also possible to back track and set the value at an index
earlier than the current index, however, the caller must assume that all data
container after the last
+ * set index is corrupted.
+ * </p>
+ * <h2>Notes</h2>
+ * <p>
+ * There is no gaurantee the data buffer for the {@link
VariableWidthVector} will have enough space to contain the data you set unless
you use setSafe. If you
+ * use set you may get array index out of bounds exceptions.
--- End diff --
Said another way, either 1) be careful to manage your own memory, or 2)
call `setSafe()`. That is, in fact, why `setSafe()` exists.
---
