masscollaborationlabs/emacs
2
0
Fork 0
mirror of https://github.com/masscollaborationlabs/emacs.git synced 2025-07-18 18:00:11 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Doc fixes in avl-tree.el

Browse source 
* lisp/emacs-lisp/avl-tree.el (avl-tree--root)
(avl-tree--dir-to-sign, avl-tree--sign-to-dir)
(avl-tree--del-balance, avl-tree--enter-balance)
(avl-tree--do-copy, avl-tree--stack-repopulate, avl-tree-empty)
(avl-tree-delete, avl-tree-member, avl-tree-member-p)
(avl-tree-map, avl-tree-mapc, avl-tree-mapf, avl-tree-mapcar)
(avl-tree-copy, avl-tree-clear, avl-tree-stack)
(avl-tree-stack-first): Fix doc strings to be less verbose and to
have the first line a complete sentence.
This commit is contained in:
Eli Zaretskii 2021-04-28 19:36:42 +03:00
parent 4fc6afb913
commit 2feeebe40a
1 changed files with 24 additions and 27 deletions
Download patch file Download diff file Expand all files Collapse all files

51
lisp/emacs-lisp/avl-tree.el
View file

@ -74,7 +74,7 @@
cmpfun) cmpfun)
(defmacro avl-tree--root (tree) (defmacro avl-tree--root (tree)
"Return the root node for an AVL tree. INTERNAL USE ONLY." "Return the root node for an AVL TREE. INTERNAL USE ONLY."
`(avl-tree--node-left (avl-tree--dummyroot ,tree))) `(avl-tree--node-left (avl-tree--dummyroot ,tree)))
;; ---------------------------------------------------------------- ;; ----------------------------------------------------------------
@ -117,11 +117,11 @@ NODE is the node, and BRANCH is the branch.
`(- 1 ,dir)) `(- 1 ,dir))
(defmacro avl-tree--dir-to-sign (dir) (defmacro avl-tree--dir-to-sign (dir)
"Convert direction (0,1) to sign factor (-1,+1)." "Convert direction DIR (0,1) to sign factor (-1,+1)."
`(1- (* 2 ,dir))) `(1- (* 2 ,dir)))
(defmacro avl-tree--sign-to-dir (dir) (defmacro avl-tree--sign-to-dir (dir)
"Convert sign factor (-x,+x) to direction (0,1)." "Convert sign factor in DIR (-x,+x) to direction (0,1)."
`(if (< ,dir 0) 0 1)) `(if (< ,dir 0) 0 1))
@ -129,7 +129,7 @@ NODE is the node, and BRANCH is the branch.
;; Deleting data ;; Deleting data
(defun avl-tree--del-balance (node branch dir) (defun avl-tree--del-balance (node branch dir)
"Rebalance a tree after deleting a node. "Rebalance a tree after deleting a NODE.
The deletion was done from the left (DIR=0) or right (DIR=1) sub-tree The deletion was done from the left (DIR=0) or right (DIR=1) sub-tree
of the left (BRANCH=0) or right (BRANCH=1) child of NODE. of the left (BRANCH=0) or right (BRANCH=1) child of NODE.
Return t if the height of the tree has shrunk." Return t if the height of the tree has shrunk."
@ -247,9 +247,9 @@ the related data."
;; Entering data ;; Entering data
(defun avl-tree--enter-balance (node branch dir) (defun avl-tree--enter-balance (node branch dir)
"Rebalance tree after an insertion "Rebalance tree after insertion of NODE.
into the left (DIR=0) or right (DIR=1) sub-tree of the NODE was inserted into the left (DIR=0) or right (DIR=1) sub-tree
left (BRANCH=0) or right (BRANCH=1) child of NODE. of the left (BRANCH=0) or right (BRANCH=1) child of NODE.
Return t if the height of the tree has grown." Return t if the height of the tree has grown."
(let ((br (avl-tree--node-branch node branch)) (let ((br (avl-tree--node-branch node branch))
;; opposite direction: 0,1 -> 1,0 ;; opposite direction: 0,1 -> 1,0
@ -379,7 +379,8 @@ itself."
;;; INTERNAL USE ONLY ;;; INTERNAL USE ONLY
(defun avl-tree--do-copy (root) (defun avl-tree--do-copy (root)
"Copy the AVL tree with ROOT as root. Highly recursive." "Copy the AVL tree wiath ROOT as root.
This function is highly recursive."
(if (null root) (if (null root)
nil nil
(avl-tree--node-create (avl-tree--node-create
@ -405,8 +406,9 @@ itself."
\n(fn OBJ)") \n(fn OBJ)")
(defun avl-tree--stack-repopulate (stack) (defun avl-tree--stack-repopulate (stack)
"Recursively push children of the node at the head of STACK onto the "Recursively push children of STACK onto the front.
front of the STACK, until a leaf is reached." This pushes the children of the node at the head of STACK onto
the front of STACK, until a leaf node is reached."
(let ((node (car (avl-tree--stack-store stack))) (let ((node (car (avl-tree--stack-store stack)))
(dir (if (avl-tree--stack-reverse stack) 1 0))) (dir (if (avl-tree--stack-reverse stack) 1 0)))
(when node ; check for empty stack (when node ; check for empty stack
@ -429,7 +431,7 @@ and returns non-nil if A is less than B, and nil otherwise.
\n(fn TREE)") \n(fn TREE)")
(defun avl-tree-empty (tree) (defun avl-tree-empty (tree)
"Return t if AVL tree TREE is empty, otherwise return nil." "Return t if AVL TREE is empty, otherwise return nil."
(null (avl-tree--root tree))) (null (avl-tree--root tree)))
(defun avl-tree-enter (tree data &optional updatefun) (defun avl-tree-enter (tree data &optional updatefun)
@ -451,7 +453,7 @@ Returns the new data."
0 data updatefun))) 0 data updatefun)))
(defun avl-tree-delete (tree data &optional test nilflag) (defun avl-tree-delete (tree data &optional test nilflag)
"Delete the element matching DATA from the AVL tree TREE. "Delete the element matching DATA from the AVL TREE.
Matching uses the comparison function previously specified in Matching uses the comparison function previously specified in
`avl-tree-create' when TREE was created. `avl-tree-create' when TREE was created.
@ -473,7 +475,7 @@ value is non-nil."
(defun avl-tree-member (tree data &optional nilflag) (defun avl-tree-member (tree data &optional nilflag)
"Return the element in the AVL tree TREE which matches DATA. "Return the element in the AVL TREE which matches DATA.
Matching uses the comparison function previously specified in Matching uses the comparison function previously specified in
`avl-tree-create' when TREE was created. `avl-tree-create' when TREE was created.
@ -496,7 +498,7 @@ for you.)"
(defun avl-tree-member-p (tree data) (defun avl-tree-member-p (tree data)
"Return t if an element matching DATA exists in the AVL tree TREE. "Return t if an element matching DATA exists in the AVL TREE.
Otherwise return nil. Matching uses the comparison function Otherwise return nil. Matching uses the comparison function
previously specified in `avl-tree-create' when TREE was created." previously specified in `avl-tree-create' when TREE was created."
(let ((flag '(nil))) (let ((flag '(nil)))
@ -504,7 +506,7 @@ previously specified in `avl-tree-create' when TREE was created."
(defun avl-tree-map (fun tree &optional reverse) (defun avl-tree-map (fun tree &optional reverse)
"Modify all elements in the AVL tree TREE by applying function FUN. "Modify all elements in the AVL TREE by applying function FUN.
Each element is replaced by the return value of FUN applied to Each element is replaced by the return value of FUN applied to
that element. that element.
@ -520,8 +522,7 @@ order if REVERSE is non-nil."
(defun avl-tree-mapc (fun tree &optional reverse) (defun avl-tree-mapc (fun tree &optional reverse)
"Apply function FUN to all elements in AVL tree TREE, "Apply function FUN to all elements in AVL TREE, for side-effect only.
for side-effect only.
FUNCTION is applied to the elements in ascending order, or FUNCTION is applied to the elements in ascending order, or
descending order if REVERSE is non-nil." descending order if REVERSE is non-nil."
@ -534,8 +535,7 @@ descending order if REVERSE is non-nil."
(defun avl-tree-mapf (defun avl-tree-mapf
(fun combinator tree &optional reverse) (fun combinator tree &optional reverse)
"Apply function FUN to all elements in AVL tree TREE, "Apply FUN to all elements in AVL TREE, combine results using COMBINATOR.
and combine the results using COMBINATOR.
The FUNCTION is applied and the results are combined in ascending The FUNCTION is applied and the results are combined in ascending
order, or descending order if REVERSE is non-nil." order, or descending order if REVERSE is non-nil."
@ -553,8 +553,7 @@ order, or descending order if REVERSE is non-nil."
(defun avl-tree-mapcar (fun tree &optional reverse) (defun avl-tree-mapcar (fun tree &optional reverse)
"Apply function FUN to all elements in AVL tree TREE, "Apply FUN to all elements in AVL TREE, and make a list of the results.
and make a list of the results.
The function is applied and the list constructed in ascending The function is applied and the list constructed in ascending
order, or descending order if REVERSE is non-nil. order, or descending order if REVERSE is non-nil.
@ -586,7 +585,7 @@ is more efficient."
(avl-tree--node-data node)))) (avl-tree--node-data node))))
(defun avl-tree-copy (tree) (defun avl-tree-copy (tree)
"Return a copy of the AVL tree TREE." "Return a copy of the AVL TREE."
(let ((new-tree (avl-tree-create (avl-tree--cmpfun tree)))) (let ((new-tree (avl-tree-create (avl-tree--cmpfun tree))))
(setf (avl-tree--root new-tree) (avl-tree--do-copy (avl-tree--root tree))) (setf (avl-tree--root new-tree) (avl-tree--do-copy (avl-tree--root tree)))
new-tree)) new-tree))
@ -608,13 +607,12 @@ is more efficient."
treesize)) treesize))
(defun avl-tree-clear (tree) (defun avl-tree-clear (tree)
"Clear the AVL tree TREE." "Clear the AVL TREE."
(setf (avl-tree--root tree) nil)) (setf (avl-tree--root tree) nil))
(defun avl-tree-stack (tree &optional reverse) (defun avl-tree-stack (tree &optional reverse)
"Return an object that behaves like a sorted stack "Return an object that behaves like a sorted stack of all elements of TREE.
of all elements of TREE.
If REVERSE is non-nil, the stack is sorted in reverse order. If REVERSE is non-nil, the stack is sorted in reverse order.
\(See also `avl-tree-stack-pop'). \(See also `avl-tree-stack-pop').
@ -655,8 +653,7 @@ a null element stored in the AVL tree.)"
(defun avl-tree-stack-first (avl-tree-stack &optional nilflag) (defun avl-tree-stack-first (avl-tree-stack &optional nilflag)
"Return the first element of AVL-TREE-STACK, without removing it "Return the first element of AVL-TREE-STACK, without removing it from stack.
from the stack.
Returns nil if the stack is empty, or NILFLAG if specified. Returns nil if the stack is empty, or NILFLAG if specified.
\(The latter allows an empty stack to be distinguished from \(The latter allows an empty stack to be distinguished from