math: Improve comments.

[pspp] / src / math / sort.h

diff --git a/src/math/sort.h b/src/math/sort.h
index ea2c16b2e14a8a8ed1c2fbe0f838bb92bdcd4870..2f1d3899a864aef42a9273cf3588c984df38c558 100644 (file)
--- a/src/math/sort.h
+++ b/src/math/sort.h
@@ -1,5 +1,5 @@
 /* PSPP - a program for statistical analysis.
-   Copyright (C) 1997-9, 2000, 2006 Free Software Foundation, Inc.
+   Copyright (C) 1997-9, 2000, 2006, 2009 Free Software Foundation, Inc.
 
    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
@@ -17,15 +17,32 @@
 #ifndef MATH_SORT_H
 #define MATH_SORT_H 1
 
-#include <stddef.h>
-#include <stdbool.h>
+/* Support for sorting cases.
 
-struct case_ordering;
+   Use sort_create_writer() to sort cases in the most general way:
+
+   - Create a casewriter with sort_create_writer(), specifying the sort
+     criteria.
+   - Write all of the cases to be sorted to the casewriter, e.g. with
+     casewriter_write().
+   - Obtain the sorted results with casewriter_make_reader().
+
+  sort_execute() and sort_execute_1var() are shortcuts for situations where the
+  cases are already available from a casereader.
+
+  All of these functions can efficiently sort data bigger than memory. */
+
+struct subcase;
+struct caseproto;
+struct variable;
 
 extern int min_buffers ;
 extern int max_buffers ;
 
-struct casewriter *sort_create_writer (struct case_ordering *, size_t value_cnt);
-struct casereader *sort_execute (struct casereader *, struct case_ordering *);
+struct casewriter *sort_create_writer (const struct subcase *,
+                                       const struct caseproto *);
+struct casereader *sort_execute (struct casereader *, const struct subcase *);
+struct casereader *sort_execute_1var (struct casereader *,
+                                      const struct variable *);
 
 #endif /* math/sort.h */