underestimatedCount in Swift's Dictionary -

according documentation, swift's dictionary type has property named underestimatedcount:

a value less or equal number of elements in collection.

anybody knows why on westeros considered useful??!

baffles me...

summary: technically speaking, underestimatedcount belongs sequence, , gets inherited collection, , dictionary. dictionary doesn't override default implementation returns zero.

---

looking @ source code, seems underestimatedcount used indicator determine amount of growth of mutable collection when new items added it.

here's snippet stringcore.swift:

public mutating func append<s : sequence>(contentsof s: s)   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, stringcharacterview.swift:

public mutating func append<s : sequence>(contentsof newelements: s)     s.iterator.element == character {     reservecapacity(_core.count + newelements.underestimatedcount)     c in newelements {       self.append(c)     }   } 

or better, arrays.swift.gyb:

public mutating func append<s : sequence>(contentsof newelements: s)     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, find 1 implementation underestimatedcount, in sequence, , 1 returns zero.

at time seems underestimatedcount has more value custom implementations of collections/sequences, standard swift collections apple has idea growth of those.