Removes is_at_container_start() and documents is_at_iterator_start(), move_at_start(), enter_at_container_start() (#1638)

* Removes is_at_container_start() and documents is_at_iterator_start()

* More documentation.

.vscode/settings.json

@@ -3,5 +3,8 @@
         {"column": 95 },
         {"column": 120 }
     ],
-    "files.trimTrailingWhitespace": true
+    "files.trimTrailingWhitespace": true,
+    "files.associations": {
+        "array": "cpp"
+    }
 }

include/simdjson/generic/ondemand/array-inl.h

@@ -76,13 +76,6 @@ simdjson_really_inline simdjson_result<size_t> array::count_elements() & noexcep
   // If the array is empty (i.e., we already scanned past it), then we use a
   // fast path and return 0.
   if(!iter.is_open()) { return 0; }
-  // The count_elements method should always be called before you have begun
-  // iterating through the array.
-  // To open a new array you need to be at a `[`.
-#ifdef SIMDJSON_DEVELOPMENT_CHECKS
-  // array::begin() makes the same check.
-  if(!iter.is_at_container_start()) { return OUT_OF_ORDER_ITERATION; }
-#endif
   size_t count{0};
   // Important: we do not consume any of the values.
   for(simdjson_unused auto v : *this) { count++; }

include/simdjson/generic/ondemand/value_iterator-inl.h

@@ -604,9 +604,6 @@ simdjson_really_inline error_code value_iterator::incorrect_type_error(const cha
 simdjson_really_inline bool value_iterator::is_at_start() const noexcept {
   return _json_iter->token.index == _start_position;
 }
-simdjson_really_inline bool value_iterator::is_at_container_start() const noexcept {
-  return _json_iter->token.index == _start_position + 1;
-}
 simdjson_really_inline bool value_iterator::is_at_iterator_start() const noexcept {
   // We can legitimately be either at the first value ([1]), or after the array if it's empty ([]).
   auto delta = _json_iter->token.index - _start_position;

include/simdjson/generic/ondemand/value_iterator.h

@@ -281,12 +281,22 @@ public:
 
   /** @} */
 protected:
-  /* updates the index so that at_start() is true and syncs the depth. */
+  /**
+   * move_at_start(): moves us so that we are pointing at the beginning of
+   * the container. It updates the index so that at_start() is true and it
+   * syncs the depth. The user can then create a new container instance.
+   *
+   * Usage: used with value::count_elements()
+   **/
    simdjson_really_inline void move_at_start() noexcept;
   /**
-   * enter_at_container_start is similar to move_at_start()
+   * enter_at_container_start moves at the beginning of the container
-   * except that it sets the depth to indicate that we are inside the
+   * and sets the depth to indicate that we are inside the
-   * container and then it accesses the first element
+   * container and ready to access the first element. It is only
+   * safely used with non-empty containers. The caller is responsible
+   * to ensure that the container is not empty!
+   *
+   * Usage: used with array::count_elements().
    **/
   simdjson_really_inline void enter_at_container_start() noexcept;
   /* Useful for debugging and logging purposes. */
@@ -306,7 +316,12 @@ protected:
   simdjson_really_inline error_code incorrect_type_error(const char *message) const noexcept;
 
   simdjson_really_inline bool is_at_start() const noexcept;
-  simdjson_really_inline bool is_at_container_start() const noexcept;
+  /**
+   * is_at_iterator_start() returns true on an array or object after it has just been
+   * created, whether the instance is empty or not.
+   *
+   * Usage: used by array::begin() in debug mode (SIMDJSON_DEVELOPMENT_CHECKS)
+   */
   simdjson_really_inline bool is_at_iterator_start() const noexcept;
   inline void assert_at_start() const noexcept;
   inline void assert_at_container_start() const noexcept;