[issue9802] Document 'stability' of builtin min() and max()

[Matthew Woodcraft]

New submission from Matthew Woodcraft <matthew at woodcraft.me.uk>:

In CPython, the builtin max() and min() have the property that if there are items with equal keys, the first item is returned. From a quick look at their source, I think this is true for Jython and IronPython too.

I propose making this a documented guarantee.

On Python-dev, Raymond Hettinger said:
<<
That seems like a reasonable request. This behavior has been around for a very long time is unlikely to change. Elsewhere, we've made efforts to document sort stability (i.e. sorted(), heapq.nlargest(), heapq.nsmallest, merge(), etc).
>>
(<http://mail.python.org/pipermail/python-dev/2010-September/103543.html>)

I'm attaching a patch with a concrete suggestion for a change to
functions.rst, modelled on the documentation of heapq.nlargest().

----------
assignee: docs at python
components: Documentation
files: maxmin.patch
keywords: patch
messages: 115892
nosy: docs at python, mattheww
priority: normal
severity: normal
status: open
title: Document 'stability' of builtin min() and max()
type: feature request
Added file: http://bugs.python.org/file18802/maxmin.patch

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue9802>
_______________________________________