hash_map_remove Subroutine

   subroutine hash_map_remove(this, key, err)
      !! Remove `key` from the map.
      !!
      !! The entry disappears from the iteration order and every remaining
      !! entry keeps its relative position: entries inserted before it are
      !! untouched, entries inserted after it move down one index. The key
      !! itself is forgotten completely, so inserting it again afterwards is a
      !! fresh insertion that lands at the *end* of the iteration order.
      !!
      !! Removing a key that is not in the map leaves the map unchanged and
      !! reports `ERROR_VALIDATION` in `err`. When `err` is absent the call is
      !! simply a no-op.
      class(hash_map_t), intent(inout) :: this
      character(len=*), intent(in) :: key
      type(error_t), intent(out), optional :: err

      integer(default_int) :: entry, klen, kstart, i

      entry = find_entry(this, key)
      if (entry <= 0) then
         if (present(err)) then
            call err%set(ERROR_VALIDATION, "pic_hash_map: key not found: '"//key//"'")
         end if
         return
      end if

      kstart = this%key_start(entry)
      klen = this%key_size(entry)

      do i = kstart + klen, this%pool_used
         this%key_pool(i - klen) = this%key_pool(i)
      end do
      this%pool_used = this%pool_used - klen

      do i = entry, this%n_entries - 1
         this%key_start(i) = this%key_start(i + 1) - klen
         this%key_size(i) = this%key_size(i + 1)
         this%entry_value(i) = this%entry_value(i + 1)
      end do
      this%n_entries = this%n_entries - 1

      call rebuild_buckets(this)
   end subroutine hash_map_remove