Add readonly iterators and support value mutations only from non-readonly iterators

[fxamacker]

This PR:

• Updates Optimize atree to reduce Flow's mtrie size and reduce number of reads #292
• Replaces Add ReadOnly iterators and refactor other iterators #329

Changes:

• Adds readonly iterators that match current iterator API (except for the "ReadOnly" suffix added to some function names).
• Refactors API of non-readonly iterators because register inlining will require more parameters for MapIterator.
• Support mutations of values returned from non-readonly iterators

For readonly iterators, the caller is responsible for preventing changes to child containers during iteration because mutations of child containers are not guaranteed to persist.

For non-readonly iterators, two additional parameters are needed to update child container in parent map when child container is modified.

---

• Targeted PR against main branch
• Linked to Github issue with discussion and accepted design OR link to spec that describes this work
• Code follows the standards mentioned here
• Updated relevant documentation
• Re-reviewed Files changed in the Github PR explorer
• Added appropriate labels

[bluesign]

For readonly iterators, the caller is responsible for preventing changes to child containers during iteration because mutations of child containers are not guaranteed to persist.

Is there are non-deterministic case there?

[codecov-commenter]

Codecov Report

Attention: 37 lines in your changes are missing coverage. Please review.

Comparison is base (8d02bbc) 62.59% compared to head (f671189) 62.62%.
Report is 1 commits behind head on fxamacker/inline-array-and-map.

Additional details and impacted files

@@                        Coverage Diff                         @@
##           fxamacker/inline-array-and-map     #345      +/-   ##
==================================================================
+ Coverage                           62.59%   62.62%   +0.03%     
==================================================================
  Files                                  15       15              
  Lines                               10492    10559      +67     
==================================================================
+ Hits                                 6567     6613      +46     
- Misses                               2989     3004      +15     
- Partials                              936      942       +6     

Files	Coverage Δ
array.go	68.10% <80.32%> (-0.04%)	⬇️
map.go	65.30% <70.23%> (+0.01%)	⬆️

... and 1 file with indirect coverage changes

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[fxamacker]

For readonly iterators, the caller is responsible for preventing changes to child containers during iteration because mutations of child containers are not guaranteed to persist.

Is there are non-deterministic case there?

Hi @bluesign, the readonly iterators will only be used internally in Cadence to reduce overhead. So "not guaranteed to persist" won't be a problem in this case.

[turbolent]

Nice!

[turbolent]

Great work!

I mainly reviewed the array and map code changes, I didn't look to deep into the tests