list: add more comments

This commit is contained in:
Danny Robson 2019-09-10 14:46:55 +10:00
parent 932b93ce5e
commit 5106038734

View File

@ -16,6 +16,9 @@
#include <utility> #include <utility>
namespace cruft::list { namespace cruft::list {
/// Return the total number of nodes in the list
///
/// It is safe to call this function with a null node pointer.
template <typename NodeT> template <typename NodeT>
std::size_t std::size_t
size (NodeT const *head) size (NodeT const *head)
@ -149,7 +152,14 @@ namespace cruft::list {
} }
/// An in-place merge sort for singly linked lists. /// Sort a linked list using a supplied comparator.
///
/// The current implementation uses an in-place merge sort.
///
/// Each nodes successor may be modified, but the data will not be.
///
/// Returns the head of the newly sorted list. The caller _must_ reset
/// their stored head node with this value otherwise data may be lost.
template <typename NodeT, typename ComparatorT> template <typename NodeT, typename ComparatorT>
NodeT* NodeT*
sort [[nodiscard]] [[using gnu: nonnull, returns_nonnull]] ( sort [[nodiscard]] [[using gnu: nonnull, returns_nonnull]] (
@ -170,6 +180,7 @@ namespace cruft::list {
} }
/// Sort a linked list using the default (value) comparator.
template <typename NodeT> template <typename NodeT>
NodeT* NodeT*
sort [[nodiscard]] [[using gnu: nonnull, returns_nonnull]] ( sort [[nodiscard]] [[using gnu: nonnull, returns_nonnull]] (