• #153: [OrderedDictionary][doc] Update docs for merge/filter operations
• #155: Remove Swift PM Artifacts to avoid Generated Schemes in Xcode
• #156: Reinstate custom schemes under Utils/swift-collections.xcworkspace
• #161: [Xcode] Update schemes & file template
• #160: [OrderedCollection] Use standard temp allocation facility, if available
• #162: [OrderedSet] Work around weird name lookup issue in compiler
• #165: Force-inline _modify accessors to work around a performance issue

• @inline(__always) has a detrimental effect when used on large functions. Let's not do that.
• Speed up invariant checking with COLLECTIONS_INTERNAL_CHECKS (resolves #69)
• Replace naked ints with _Node, precalculating levels for each offset (resolves #71)
• Rebase heap operations on UMBP instead Array, eliminating unnecessary index validation (resolves #75)
• ~Add some (slightly questionable) effects attributes to heap internals.~
• Optimize removals and heap construction

Checklist

• [X] I've read the Contribution Guidelines
• [X] My contributions are licensed under the Swift license.
• [X] I've followed the coding style of the rest of the project.
• [ ] I've added tests covering all new code paths my change adds to the project (if appropriate).
• [ ] I've added benchmarks covering new functionality (if appropriate).
• [X] I've verified that my change does not break any existing tests or introduce unexplained benchmark regressions.
• [ ] I've updated the documentation if necessary.

If have two OrderedSets of what are essentially UUIDs (wrapped in Tagged). Finding the intersection from setA works.

setA.intersection(setB)

But taking the two, same, sets and flipping the order causes an out of bounds crash in RandomAccessCollection+Offsets.swift#28.

setB.intersection(setA)

The items in the sets are 1389 vs. 1388 if that could somehow matter.

Here's a stack trace if it helps:

#0	0x000000018f8d9a3c in _swift_runtime_on_report ()
#1	0x000000018f949530 in _swift_stdlib_reportFatalErrorInFile ()
#2	0x000000018f64b5d8 in closure #1 in closure #1 in closure #1 in _assertionFailure(_:_:file:line:flags:) ()
#3	0x000000018f64b37c in closure #1 in closure #1 in _assertionFailure(_:_:file:line:flags:) ()
#4	0x000000018f64ad2c in _assertionFailure(_:_:file:line:flags:) ()
#5	0x000000018f64aff0 in _fatalErrorMessage(_:_:file:line:flags:) ()
#6	0x000000018f848f8c in UnsafeBufferPointer.subscript.read ()
#7	0x000000018f848dfc in protocol witness for Collection.subscript.read in conformance UnsafeBufferPointer<τ_0_0> ()
#8	0x00000001046bf4c0 in RandomAccessCollection.subscript.getter at swift-collections/Sources/OrderedCollections/Utilities/RandomAccessCollection+Offsets.swift:28
#9	0x000000010467d904 in _HashTable.UnsafeHandle._find<τ_0_0>(_:in:) at swift-collections/Sources/OrderedCollections/HashTable/_HashTable+UnsafeHandle.swift:299
#10	0x00000001046bd5e4 in closure #1 in closure #1 in OrderedSet._find_inlined(_:) at swift-collections/Sources/OrderedCollections/OrderedSet/OrderedSet.swift:396
#11	0x00000001046bd648 in thunk for @callee_guaranteed (@unowned _HashTable.UnsafeHandle) -> (@unowned Int?, @unowned _HashTable.Bucket, @error @owned Error) ()
#12	0x00000001046bf154 in partial apply for thunk for @callee_guaranteed (@unowned _HashTable.UnsafeHandle) -> (@unowned Int?, @unowned _HashTable.Bucket, @error @owned Error) ()
#13	0x00000001046837d8 in closure #1 in _HashTable.read<τ_0_0>(_:) at swift-collections/Sources/OrderedCollections/HashTable/_HashTable.swift:151
#14	0x0000000104683ec0 in partial apply for closure #1 in _HashTable.read<τ_0_0>(_:) ()
#15	0x000000018f730e18 in ManagedBuffer.withUnsafeMutablePointers<τ_0_0>(_:) ()
#16	0x00000001046836fc in _HashTable.read<τ_0_0>(_:) at swift-collections/Sources/OrderedCollections/HashTable/_HashTable.swift:149
#17	0x00000001046bd454 in closure #1 in OrderedSet._find_inlined(_:) at swift-collections/Sources/OrderedCollections/OrderedSet/OrderedSet.swift:395
#18	0x00000001046bd6e0 in thunk for @callee_guaranteed (@unowned UnsafeBufferPointer<τ_0_0>) -> (@unowned Int?, @unowned _HashTable.Bucket, @error @owned Error) ()
#19	0x00000001046bebe8 in partial apply for thunk for @callee_guaranteed (@unowned UnsafeBufferPointer<τ_0_0>) -> (@unowned Int?, @unowned _HashTable.Bucket, @error @owned Error) ()
#20	0x000000018f62ef9c in ContiguousArray.withUnsafeBufferPointer<τ_0_0>(_:) ()
#21	0x00000001046bd180 in OrderedSet._find_inlined(_:) atswift-collections/Sources/OrderedCollections/OrderedSet/OrderedSet.swift:391
#22	0x00000001046ab544 in OrderedSet.contains(_:) at swift-collections/Sources/OrderedCollections/OrderedSet/OrderedSet+Partial SetAlgebra+Basics.swift:47
#23	0x00000001046abdb8 in OrderedSet.intersection(_:) at swift-collections/Sources/OrderedCollections/OrderedSet/OrderedSet+Partial SetAlgebra+Operations.swift:164

Information

• Package version: version 0.0.7?
• Platform version: iOS 15, iPhone 12 Pro simulator.
• Swift version: I assume Swift 5.5 (Xcode 13 beta 5)

Checklist

• [ ] If possible, I've reproduced the issue using the main branch of this package.
• [x] I've searched for existing GitHub issues.

Did not attempt to reproduce on main as swift-collections is a sub-dependency on one of my dependencies. But could absolutely try if requested. Getting late where I am 😅

Steps to Reproduce

I have not been able to reproduce this issue unfortunately. I'm doing this a on a few different pairs of sets, and only one of them with this specific type (Tagged<Product, UUID> — product being a custom struct) causes the issue. The other sets are also Tagged<X, UUID>.

Happy to attempt to provide more attempts to reproduce. The inner workings of all this is a bit over my head though.

Expected behavior

I expect the "call order" to not matter.

Actual behavior

Out of bounds crash.

Failed to compile using SPM.

TLDR (log file attached below)

Abort Trap: 6

<unknown>:0: error: fatal error encountered while reading from module 'OrderedCollections'; please file a bug report with your project and the crash log
<unknown>:0: note: module 'OrderedCollections' full misc version is '5.3.2(5.3.2)/Apple Swift version 5.3.2 (swiftlang-1200.0.45 clang-1200.0.32.28)'

*** DESERIALIZATION FAILURE (please include this section in any bug report) ***
result not found
Cross-reference to module 'OrderedCollections'
... OrderedSet
... in an extension in module 'OrderedCollections'
... Element

Information

• Package version: What tag or branch of swift-collections are you using?
  • 0.0.1
• Platform version: Please tell us the version number of your operating system.
  • macOS: 11.2.1 (20D74)
  • Xcode: 12.4 (12D4e)
  • Simulator/device: Doesn't seem to matter
• Swift version: Paste the output of swift --version here.
  • Apple Swift version 5.3.2 (swiftlang-1200.0.45 clang-1200.0.32.28)
  • Target: x86_64-apple-darwin20.3.0

EDIT: Adding more details today

~ > sw_vers                                                                                                            system
ProductName:	macOS
ProductVersion:	11.2.3
BuildVersion:	20D91

~ > uname -a                                                                                                           system
Darwin ****.local 20.3.0 Darwin Kernel Version 20.3.0: Thu Jan 21 00:07:06 PST 2021; root:xnu-7195.81.3~1/RELEASE_X86_64 x86_64

~ > swift --version                                                                                                    system
Apple Swift version 5.3.2 (swiftlang-1200.0.45 clang-1200.0.32.28)
Target: x86_64-apple-darwin20.3.0

~ > clang --version                                                                                                    system
Apple clang version 12.0.0 (clang-1200.0.32.29)
Target: x86_64-apple-darwin20.3.0
Thread model: posix
InstalledDir: /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin`

Checklist

• [X] If possible, I've reproduced the issue using the main branch of this package.
• [X] I've searched for existing GitHub issues.

Steps to Reproduce

• Create new iOS app in Xcode (just default code)
• Set up SPM to include this repo at v 0.0.1 (same for main)
• Build
  • iOS app target fails (log file attached below)
  • Collections target fails
  • CollectionsBenchmark target fails
  • DequeModule succeeds
  • OrderedCollections target fails
  • swift-collections-benchmark fails
  • swift-collections-benchmark-Package succeeds
  • swift-collections-Package fails

Expected behavior

Expect SPM to compile the targets in this repo

Actual behavior

Build fails. see attached build log

Description

This is an extraction of the heap implementation hammered out in #51.

Detailed Design

One of the big advantages of using a min-max heap is that we don't need to bifurcate into a min heap or max heap and keep track of which kind is used — you can pop min or max, as needed. This makes it very useful as the backing storage for a double-ended priority queue.

public struct Heap<Element: Comparable> {
    public var isEmpty: Bool
    public var count: Int

    // Read-only view into the underlying array
    public var unordered: [Element]

    // Initializers
    public init()
    public init<S: Sequence>(_ elements: S)

    // Mutations
    public mutating func insert(_ element: Element)
    public mutating func insert<S: Sequence>(contentsOf: S)
    public func min() -> Element?
    public func max() -> Element?
    public mutating func popMin() -> Element?
    public mutating func popMax() -> Element?
    public mutating func removeMin() -> Element
    public mutating func removeMax() -> Element
}

// Array literal
extension Heap: ExpressibleByArrayLiteral {
    public init(arrayLiteral elements: Element...)
}

// Iteration
extension Heap {
    public struct Iterator: Sequence, IteratorProtocol {}

    public var ascending: Iterator
    public var descending: Iterator
}

Future Directions

• Add replaceMin and replaceMax (@timvermeulen has a branch of this already)
• Implement a priority queue on top of this (that work will be picked back up in #51)

Documentation

The public APIs have largely been documented. An overview document has been added to the Documentation directory that is adapted from the API review and code comments.

Testing

There are unit tests for the added Heap type.

Performance

Performance tests have been added (including comparable tests against a CFBinaryHeap). We may want to revisit the library JSON to ensure we have the desired comparisons defined. (Can somebody with a better understanding of how all of that works/is structured take a look? Maybe @lorentey?)

Source Impact

This is purely additive. No existing APIs were changed, deprecated, or removed.

Checklist

• [X] I've read the Contribution Guidelines
• [X] My contributions are licensed under the Swift license.
• [X] I've followed the coding style of the rest of the project.
• [X] I've added tests covering all new code paths my change adds to the project (to the extent possible).
• [X] I've added benchmarks covering new functionality (if appropriate).
• [X] I've verified that my change does not break any existing tests or introduce unexpected benchmark regressions.
• [x] I've updated the documentation (if appropriate).

This is the first in a series of subsequent PRs with large-scale logic changes. This first one concentrates on the representation of node storage, and the patterns of accessing it:

• Switch to using ManagedBuffer to represent node storage. This has useful performance benefits, but it significantly complicates access to node data. We no longer have direct access to the underlying raw storage: everything needs to go through closures passed to ManagedBuffer.withUnsafeMutablePointers.
• Introduce struct _Node and struct _Node.UnsafeHandle to represent a (strong) reference to a hash tree node, and a convenient handle for node storage, respectively. Use these instead of directly accessing the ManagedBuffer object, whenever feasible. (_Node holds the implementation of all the actual tree operations -- it provides mutating methods to manipulate a (sub)tree, providing a workable illusion of value semantics on the level of individual subtrees. UnsafeHandle provides both read-only and mutable views into storage inside a node -- mutating operations require (and assume) that the corresponding _Node holds a uniquely held reference to the storage object.)
• Implement separate paths for in-place mutations vs copy-on-write operation, optimizing both flavors.
• Go to great lengths to eliminate unnecessary retain-release traffic, whenever possible.
• Push subtree counts into parent nodes by moving the corresponding field from the node header into the _Node struct. (This results in a cool ~20x speedup for jumping around in the tree by integer offsets.)
• Implement a type-punned empty root singleton, to allow creating empty trees without allocating anything.

The implementation of dictionary operations remain conceptually unchanged for now (although the details look superficially different now) -- future updates will start tweaking things in earnest.

Checklist

• [X] I've read the Contribution Guidelines
• [X] My contributions are licensed under the Swift license.
• [X] I've followed the coding style of the rest of the project.
• [ ] I've added tests covering all new code paths my change adds to the project (if appropriate).
• [ ] I've added benchmarks covering new functionality (if appropriate).
• [X] I've verified that my change does not break any existing tests or introduce unexplained benchmark regressions.
• [ ] I've updated the documentation if necessary.

Consider the following simple function (the operation is not useful, it's just intended to be complex enough to defeat being optimized away and simple enough to make the generated assembly simple):

func twiddle(index: Int, twiddle: UInt8, deque: inout Deque<UInt8>) {
    deque[index] ^= twiddle
}

When compiled in release mode using swift-collections 1.0.2 and current main (c3fdcf7), this generates the following assembly on my arm64 Mac:

_$s18alloc_modify_repro10DequeReproV7twiddle5indexAD5dequeySi_s5UInt8V0D6Module0D0VyAHGztFZTf4nnnd_n:        // function signature specialization <Arg[3] = Dead> of static alloc_modify_repro.DequeRepro.twiddle(index: Swift.Int, twiddle: Swift.UInt8, deque: inout DequeModule.Deque<Swift.UInt8>) -> ()
sub        sp, sp, #0x40                               ; CODE XREF=_$s18alloc_modify_repro10DequeReproV4mainyyFZTf4d_n+208
stp        x20, x19, [sp, #0x20]
stp        fp, lr, [sp, #0x30]
add        fp, sp, #0x30
mov        x19, x1
mov        x1, x0                                      ; argument #2 for method _$s11DequeModule0A0VyxSiciMs5UInt8V_Tg5
mov        x0, sp                                      ; argument #1 for method _$s11DequeModule0A0VyxSiciMs5UInt8V_Tg5
mov        x20, x2
bl         _$s11DequeModule0A0VyxSiciMs5UInt8V_Tg5     ; generic specialization <Swift.UInt8> of DequeModule.Deque.subscript.modify : (Swift.Int) -> A
mov        x8, x0
ldrb       w9, [x1]
eor        w9, w9, w19
strb       w9, [x1]
mov        x0, sp
mov        w1, #0x0
blr        x8
ldp        fp, lr, [sp, #0x30]
ldp        x20, x19, [sp, #0x20]
add        sp, sp, #0x40
ret

As you can see, _modify has not been inlined but it has been specialized. As a result, the call to the continuation has been split and delayed (visible as blr x8).

_modify has compiled to:

_$s11DequeModule0A0VyxSiciMs5UInt8V_Tg5:        // generic specialization <Swift.UInt8> of DequeModule.Deque.subscript.modify : (Swift.Int) -> A
stp        x24, x23, [sp, #-0x40]!                     ; CODE XREF=_$s18alloc_modify_repro10DequeReproV7twiddle5indexAD5dequeySi_s5UInt8V0D6Module0D0VyAHGztFZTf4nnnd_n+32
stp        x22, x21, [sp, #0x10]
stp        x20, x19, [sp, #0x20]
stp        fp, lr, [sp, #0x30]
add        fp, sp, #0x30
mov        x21, x1
mov        x22, x0
mov        w0, #0x28                                   ; argument "size" for method imp___stubs__malloc
bl         imp___stubs__malloc                         ; malloc
str        x0, [x22]
stp        x21, x20, [x0]
tbnz       x21, 0x3f, loc_100012600

mov        x19, x0
ldr        x23, [x20]
mov        x0, #0x0
bl         _$sSo10HeapObjectVMa                        ; type metadata accessor for __C.HeapObject
ldr        x8, [x23, #0x18]
cmp        x8, x21
b.le       loc_100012604

add        x22, x19, #0x20
mov        x0, x23                                     ; argument "arg0" for method imp___stubs__swift_isUniquelyReferenced_nonNull_native
bl         imp___stubs__swift_isUniquelyReferenced_nonNull_native ; swift_isUniquelyReferenced_nonNull_native
tbnz       w0, 0x0, loc_1000125b0

bl         _$s11DequeModule0A0V8_StorageV15_makeUniqueCopyyyFs5UInt8V_Tg5 ; generic specialization <Swift.UInt8> of DequeModule.Deque._Storage._makeUniqueCopy() -> ()

loc_1000125b0:
ldr        x8, [x20]                                   ; CODE XREF=_$s11DequeModule0A0VyxSiciMs5UInt8V_Tg5+88
ldr        x9, [x8, #0x20]!
str        x9, [x19, #0x10]
add        x9, x9, x21
ldur       x10, [x8, #-0x10]
str        x10, [x19, #0x18]
cmp        x9, x10
csel       x10, xzr, x10, lt
sub        x9, x9, x10
add        x8, x8, x9
ldrb       w8, [x8, #0x8]
strb       w8, [x19, #0x20]
adr        x0, #0x100012608
nop
mov        x1, x22
ldp        fp, lr, [sp, #0x30]
ldp        x20, x19, [sp, #0x20]
ldp        x22, x21, [sp, #0x10]
ldp        x24, x23, [sp], #0x40
ret

loc_100012600:
brk        #0x1                                        ; CODE XREF=_$s11DequeModule0A0VyxSiciMs5UInt8V_Tg5+44

loc_100012604:
brk        #0x1                                        ; CODE XREF=_$s11DequeModule0A0VyxSiciMs5UInt8V_Tg5+72

Notice the call to malloc at the start of the function. This call drastically dominates the performance of _modify, and it makes Deque extremely difficult to use in performance sensitive code.

Information

• Package version: 1.0.2 or main (c3fdcf7)
• Platform version: 21G83
• Swift version: swift-driver version: 1.45.2 Apple Swift version 5.6.1 (swiftlang-5.6.0.323.66 clang-1316.0.20.12) Target: arm64-apple-macosx12.0

Checklist

• [X] If possible, I've reproduced the issue using the main branch of this package.
• [X] I've searched for existing GitHub issues.

Steps to Reproduce

Use the above code sample in an empty Swift project that depends on swift-collections.

Expected behavior

No allocations in _modify.

Actual behavior

A direct call to malloc and a subsequent call to free.

Candidate commit:

~~da3a73ed90a17ac37b42e238b48a678d340f563f on release/1.0~~ ~~1337897dc6a878fe97a83f1549d49ddf6d093651 on release/1.0~~ 48254824bb4248676bf7ce56014ff57b142b77eb on release/1.0

I'm trying to build a CLI tool in GitHub Actions with a dependency on this package. It's building fine on macOS but it fails to build on Ubuntu 20.04.2 LTS fails. I'm using fwal/setup-swift@v1 to install Swift on the ubuntu environment. I apologise if this is not an issue on the package itself.

Information

• Package version: Tried both 0.0.3 and the most recent commit c0549b6
• Platform version: Ubuntu 20.04.2 LTS
• Swift version: Swift version 5.4 (swift-5.4-RELEASE) | Target: x86_64-unknown-linux-gnu

Checklist

• [x] If possible, I've reproduced the issue using the main branch of this package.
• [x] I've searched for existing GitHub issues.

Actual behavior

The compiler error is as follows:

gnu/debug/DequeModule.swiftmodule
2021-06-16T14:48:22.9117174Z <unknown>:0: error: fatal error encountered while reading from module 'DequeModule'; please submit a bug report (https://swift.org/contributing/#reporting-bugs) and include the project
2021-06-16T14:48:22.9119412Z <unknown>:0: note: module 'DequeModule' full misc version is '5.4(5.4)/Swift version 5.4 (swift-5.4-RELEASE)'
2021-06-16T14:48:22.9120239Z 
2021-06-16T14:48:22.9121042Z *** DESERIALIZATION FAILURE (please include this section in any bug report) ***
2021-06-16T14:48:22.9121888Z result not found
2021-06-16T14:48:22.9122743Z Cross-reference to module 'DequeModule'
2021-06-16T14:48:22.9123511Z ... Deque
2021-06-16T14:48:22.9124310Z ... in an extension in module 'DequeModule'
2021-06-16T14:48:22.9125028Z ... Element
2021-06-16T14:48:22.9125472Z 
2021-06-16T14:48:22.9126669Z Please submit a bug report (https://swift.org/contributing/#reporting-bugs) and include the project and the crash backtrace.
2021-06-16T14:48:22.9127715Z Stack dump:
2021-06-16T14:48:22.9174473Z 1.	Swift version 5.4 (swift-5.4-RELEASE)
2021-06-16T14:48:22.9175397Z 2.	While evaluating request ASTLoweringRequest(Lowering AST to SIL for module DequeModule)
2021-06-16T14:48:22.9176720Z 3.	While deserializing SIL function "$s11DequeModule0A0VAASERzlE6encode2toys7Encoder_p_tKF"
2021-06-16T14:48:22.9178025Z 4.	While reading from 'DequeModule'
2021-06-16T14:48:22.9179066Z 5.	While finishing conformance for protocol conformance to 'Sequence' (in module 'Swift') for type 'Deque<Element>'

Full logs

As @Lukasa discovered in #164, the _modify accessor in Deque's index subscript tends to call malloc unless it happens to get inlined into the caller. Try to prevent this performance bottleneck by force-inlining this accessor.

To mitigate potential code size issues, move the preparation/finalization steps into separate functions that aren't force-inlined.

Resolves #164.

Checklist

• [X] I've read the Contribution Guidelines
• [X] My contributions are licensed under the Swift license.
• [X] I've followed the coding style of the rest of the project.
• [ ] I've added tests covering all new code paths my change adds to the project (if appropriate).
• [ ] I've added benchmarks covering new functionality (if appropriate).
• [X] I've verified that my change does not break any existing tests or introduce unexplained benchmark regressions.
• [ ] I've updated the documentation if necessary.

• Fix issues reported by @benrimmington (thanks!)
• Update wording on evolving Swift toolchain requirements
• Update contributor guide on adding a new data structure to better reflect reality
• Add an extra sentence on combinatorial tests

Resolves #209

Checklist

• [X] I've read the Contribution Guidelines
• [X] My contributions are licensed under the Swift license.
• [X] I've followed the coding style of the rest of the project.
• [ ] I've added tests covering all new code paths my change adds to the project (if appropriate).
• [ ] I've added benchmarks covering new functionality (if appropriate).
• [ ] I've verified that my change does not break any existing tests or introduce unexplained benchmark regressions.
• [X] I've updated the documentation if necessary.

This is not fully documented and could use conditional MutableCollection/Equatable/Hashable conformances, but it's a pretty complete implementation that you could use as a starting point.

I assume I'm wrong here, asking for education mostly :)

The code looks like this:

/// Recommended node size of a given B-Tree
@inlinable
@inline(__always)
internal static var defaultLeafCapacity: Int {
  #if DEBUG
  return 5
  #else
  let capacityInBytes = 2000
  return Swift.min(16, capacityInBytes / MemoryLayout<Key>.stride)
  #endif
}

From my reading the max leaf capacity is 16? Is that right? I would expect (without really understanding much of the code here) performance to be better if leaves could contain more then 16 elements when element size is small.

I realize the docs say this code is still unstable, but it's never too early to ask for more, right? 😉

There should be something analogous to partitioningIndex(where:) for the sorted associative containers. An example of why: I have a multimap K:V where the chance of having multiple V's for any K is very low and for any K, all Vs are unique. The best storage format is roughly as a sorted set of lexicographically ordered (K,V) pairs. There should be a way to find the beginning and end of the sequence of contiguous items with a given K value, without (obviously) the cost of treating the tree as a flat collection and using indices.

In fact I'm very surprised not to see something like this in the BTree source (though it's so spread out, I may have missed it); it seems like contains and perhaps a few other things might be able to be built upon it. Thanks!

It currently takes some mental gymnastics or deep data structures background to grok if OrderedDictionary's keys and values are ordered. These minor additions to the docs make that more explicit. If this sort of change is welcome I'm happy to clarify some of the other data structures as well.

Checklist

• [x] I've read the Contribution Guidelines
• [x] My contributions are licensed under the Swift license.
• [x] I've followed the coding style of the rest of the project.
• [n/a] I've added tests covering all new code paths my change adds to the project (if appropriate).
• [n/a] I've added benchmarks covering new functionality (if appropriate).
• [n/a] I've verified that my change does not break any existing tests or introduce unexplained benchmark regressions.
• [x] I've updated the documentation if necessary.

Just wanted to bring this up real quick: The current README.md lists BitSet and BitArray and links both to respective files in the Documentation/ folder -- but none of these exist. Couldn't see an obvious deletion from the commit messages; so is this WIP or did the files go missing, maybe?