docs: public void put(String fieldName, IonValue value)
      {
          checkForLock();
  
          validateFieldName(fieldName);
          if (value != null) validateNewChild(value);
  
          int lowestRemovedIndex = get_child_count();
          boolean any_removed = false;
  
          // first we remove the any existing fields
          // associated with fieldName (which may be none)
          if (_field_map != null && _field_map_duplicate_count == 0)
          {
              // we have a map and no duplicates so the index
              // (aka map) is all we need to find the only
              // value associated with fieldName, if there is one
              Integer idx = _field_map.get(fieldName);
              if (idx != null) {
                  lowestRemovedIndex = idx.intValue();
                  remove_field_from_field_map(fieldName, lowestRemovedIndex);
                  remove_child(lowestRemovedIndex);
                  any_removed = true;
              }
          }
          else {
              // either we don't have a map (index) or there
              // are duplicates in both cases we have to
              // scan the child list directly.
              // Walk backwards to minimize array movement
              // as we remove fields as we encounter them.
              int copies_removed = 0;
              for (int ii = get_child_count(); ii > 0; )
              {
                  ii--;
                  IonValueLite child = get_child(ii);
                  if (fieldName.equals(child.getFieldNameSymbol().getText()))
                  {
                      // done by remove_child: child.detachFromContainer();
                      remove_child(ii);
                      lowestRemovedIndex = ii;
                      copies_removed++;
                      any_removed = true;
                  }
              }
              if (any_removed) {
                  remove_field(fieldName, lowestRemovedIndex, copies_removed);
              }
          }
          if (any_removed) {
              patch_map_elements_helper(lowestRemovedIndex);
              patch_elements_helper(lowestRemovedIndex);
          }
  
          // once we've removed any existing copy we now add,
          // this (delete + add == put) turns out be be the
          // right choice since:
          //   1 - because of possible duplicates we can't
          //       guarantee the idx is stable
          //   2 - we have to maintain the hash and that
          //       really means we end up with the delete
          //       anyway
          // strictly speaking this approach, while simpler,
          // is more expensive when we don't have a has and
          // the value already exists, and it's not at the
          // end of the field list anyway.
          if (value != null) {
              add(fieldName, value);
          }
      }