underestimatedCount in Swift's Dictionary

Question

According to the documentation, Swift's Dictionary type has this property named underestimatedCount:

A value less than or equal to the number of elements in the collection.

Anybody knows why on Westeros is this considered useful??!

Baffles me...

Answer 1

Summary: technically speaking, underestimatedCount belongs to Sequence, and gets inherited by Collection, and Dictionary. Dictionary doesn't override the default implementation that returns zero.

---

Looking at the source code, it seems that underestimatedCount is used as an indicator to determine the amount of the growth of a mutable collection when new items are added to it.

Here's a snippet from StringCore.Swift:

public mutating func append<S : Sequence>(contentsOf s: S)
  where S.Iterator.Element == UTF16.CodeUnit {

...........

  let growth = s.underestimatedCount
  var iter = s.makeIterator()

  if _fastPath(growth > 0) {
    let newSize = count + growth
    let destination = _growBuffer(newSize, minElementWidth: width)

Similarily, from StringCharacterView.swift:

public mutating func append<S : Sequence>(contentsOf newElements: S)
    where S.Iterator.Element == Character {
    reserveCapacity(_core.count + newElements.underestimatedCount)
    for c in newElements {
      self.append(c)
    }
  }

Or even better, from Arrays.swift.gyb:

public mutating func append<S : Sequence>(contentsOf newElements: S)
    where S.Iterator.Element == Element {
    let oldCount = self.count
    let capacity = self.capacity
    let newCount = oldCount + newElements.underestimatedCount

    if newCount > capacity {
      self.reserveCapacity(
        Swift.max(newCount, _growArrayCapacity(capacity)))
      }
    _arrayAppendSequence(&self._buffer, newElements)
  }

Oddly enough, I could find only one implementation for underestimatedCount, in Sequence, and that one returns zero.

At this time is seems that the underestimatedCount has more value to custom implementations of collections/sequences, as for the standard Swift collections Apple has already a good idea about the growth of those.