bug#21305: 25.0.50; `get-buffer-window-list' doc - what order?

[Drew Adams <drew.adams@oracle.com>]

[-- Attachment #1: Type: text/plain, Size: 228 bytes --]

> `get-buffer-window-list' is in window.el.  Couldn't you try giving
> it a fourth argument, say SORT, which, if `lru-first' or `mru-first',
> would cause it to return the windows in the corresponding order?

Patch attached.

[-- Attachment #2: window-2015-08-22.patch --]
[-- Type: application/octet-stream, Size: 2238 bytes --]

diff -uw window.el window-patched-2015-08-22.el
--- window.el	2015-08-22 07:17:03.887665500 -0700
+++ window-patched-2015-08-22.el	2015-08-22 07:26:37.984069400 -0700
@@ -2296,11 +2296,10 @@
 	  (setq best-window window))))
     best-window))
 
-(defun get-buffer-window-list (&optional buffer-or-name minibuf all-frames)
+(defun get-buffer-window-list (&optional buffer-or-name minibuf all-frames sort)
   "Return list of all windows displaying BUFFER-OR-NAME, or nil if none.
 BUFFER-OR-NAME may be a buffer or the name of an existing buffer
-and defaults to the current buffer.  If the selected window displays
-BUFFER-OR-NAME, it will be the first in the resulting list.
+and defaults to the current buffer.
 
 MINIBUF t means include the minibuffer window even if the
 minibuffer is not active.  MINIBUF nil or omitted means include
@@ -2324,14 +2323,28 @@
 
 - A frame means consider all windows on that frame only.
 
-Anything else means consider all windows on the selected frame
-and no others."
+Anything else for ALL-FRAMES means consider all windows on the
+selected frame and no others.
+
+By default (SORT is nil), the order of the windows in the result is
+unspecified, except that if the selected window shows BUFFER-OR-NAME
+then it is first.
+
+Non-nil SORT means return the windows sorted by last use time:
+- `mru' means most  recently used comes first
+- `lru' means least recently used comes first"
   (let ((buffer (window-normalize-buffer buffer-or-name))
 	windows)
     (dolist (window (window-list-1 (selected-window) minibuf all-frames))
-      (when (eq (window-buffer window) buffer)
-	(setq windows (cons window windows))))
-    (nreverse windows)))
+      (when (eq (window-buffer window) buffer)	(setq windows  (cons window windows))))
+    (setq windows  (nreverse windows))
+    (when sort
+      (let ((pred  (case sort
+                     (lru (lambda (w1 w2) (time-less-p (window-use-time w1) (window-use-time w2))))
+                     (mru (lambda (w1 w2) (time-less-p (window-use-time w2) (window-use-time w1)))))))
+        (setq windows  (sort windows pred))))
+    windows))
+
 
 (defun minibuffer-window-active-p (window)
   "Return t if WINDOW is the currently active minibuffer window."