Add support for iterating only loaded values

[fxamacker]

Closes #303

Description

Added new functions and structs for a special iterators required by Stable Cadence:

• Array.IterateLoadedValues()
• ArrayLoadedValueIterator
• OrderedMap.IterateLoadedValues()
• MapLoadedValueIterator etc.

They have same API as regular iterators except that they only return already loaded elements.

---

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

[codecov-commenter]

Codecov Report

Merging #311 (646edb4) into main (a996413) will increase coverage by 0.45%. The diff coverage is 73.64%.

@@            Coverage Diff             @@
##             main     #311      +/-   ##
==========================================
+ Coverage   64.55%   65.01%   +0.45%     
==========================================
  Files          14       14              
  Lines        8019     8387     +368     
==========================================
+ Hits         5177     5453     +276     
- Misses       2164     2236      +72     
- Partials      678      698      +20     

Impacted Files	Coverage Δ
storage.go	74.33% <45.45%> (-0.19%)	:arrow_down:
storable.go	56.17% <61.90%> (+1.76%)	:arrow_up:
map.go	67.20% <73.86%> (+0.49%)	:arrow_up:
array.go	70.29% <77.37%> (+0.48%)	:arrow_up:

[turbolent]

Maybe Supun (once he's back), Ramtin (once he's back), and/or someone else from the execution team can have a look as well before we merge

[turbolent]

@SupunS could you please also have a look here?

[ramtinms]

I might need some context on this one.

• Who would be the final user of this feature? cadence runtime code and or would it be directly exposed to the user's scripts?
• How often the Atree internal cache of slabs is purged? I assume is at least once per transaction otherwise we might return values without reading them from the storage and cause missing register errors.

[fxamacker]

@ramtinms Thanks for taking a look!

I might need some context on this one. Who would be the final user of this feature? cadence runtime code and or would it be directly exposed to the user's scripts?

I think the plan is Cadence runtime. Bastian and Supun provided some context in reply to this comment on the issue.

How often the Atree internal cache of slabs is purged? I assume is at least once per transaction otherwise we might return values without reading them from the storage and cause missing register errors.

I think internal cache is purged on commit but I'm not sure how often commit is called. Maybe @turbolent or @janezpodhostnik can provide more info about how often that happens.