PERFORCE change 159308 for review

[Gabor Kovesdan]

http://perforce.freebsd.org/chv.cgi?CH=159308

Change 159308 by gabor at gabor_server on 2009/03/16 19:19:44

	- Add some comments to the code

Affected files ...

.. //depot/projects/soc2008/gabor_textproc/newsort/coll.c#2 edit
.. //depot/projects/soc2008/gabor_textproc/newsort/file.c#2 edit
.. //depot/projects/soc2008/gabor_textproc/newsort/mem.c#2 edit
.. //depot/projects/soc2008/gabor_textproc/newsort/msort.c#2 edit
.. //depot/projects/soc2008/gabor_textproc/newsort/sort.c#2 edit

Differences ...

==== //depot/projects/soc2008/gabor_textproc/newsort/coll.c#2 (text+ko) ====

@@ -38,6 +38,9 @@
 static int		 numcoll(const wchar_t *, const wchar_t *);
 static int		 wcscasecoll(const wchar_t *, const wchar_t *);
 
+/*
+ * Rips out leading blanks (-b).
+ */
 static wchar_t
 *ignore_leading_blanks(wchar_t *str) {
 
@@ -47,6 +50,9 @@
 	return (str);
 }
 
+/*
+ * Rips out nonprinting characters (-i).
+ */
 static wchar_t
 *ignore_nonprinting(wchar_t *str) {
 	wchar_t		*ret;
@@ -64,6 +70,10 @@
 
 }
 
+/*
+ * Rips out any characters that are not alphanumeric characters
+ * nor blanks (-d).
+ */
 static wchar_t
 *dictionary_order(wchar_t *str) {
 	wchar_t		*ret;
@@ -80,6 +90,11 @@
 	return (ret);
 }
 
+/*
+ * Preprocesses a line applying the necessary transformations
+ * specified by command line options and returns the preprocessed
+ * string, which can be used to compare.
+ */
 static wchar_t
 *preproc(const wchar_t *s) {
 	wchar_t		*ret, *sp, *ep;
@@ -120,6 +135,12 @@
 	return (ret);
 }
 
+/*
+ * Compares the given strings.  Returns a positive number if
+ * the first precedes the second, a negative number if the second is
+ * the preceding one, and zero if they are equal.  This function calls
+ * the underlying collate functions, which done the actual comparison.
+ */
 int
 coll(const wchar_t *s1, const wchar_t *s2) {
 	wchar_t		*ps1, *ps2;
@@ -137,6 +158,9 @@
 			(rflag ? wcscoll(ps2, ps1) : wcscoll(ps1, ps2)));
 }
 
+/*
+ * A case insensitive version of wcscoll().
+ */
 static int
 wcscasecoll(const wchar_t *s1, const wchar_t *s2) {
 	int		 len1, len2;
@@ -159,6 +183,9 @@
 	return (len2 - len1);
 }
 
+/*
+ * Implements general numeric sort (-g).
+ */
 static int
 numcoll(const wchar_t *s1, const wchar_t *s2) {
 	int		n1 = 0, n2 = 0;
@@ -184,6 +211,11 @@
 	}
 }
 
+/*
+ * A helper function for monthcoll.  If a line matches
+ * a month name, it returns (number of the month - 1),
+ * while if there is no match, it just return -1.
+ */
 static int
 month_score(const wchar_t *s) {
 	char		*tmp;
@@ -231,6 +263,9 @@
 	return (-1);
 }
 
+/*
+ * Implements month sort (-M).
+ */
 static int
 monthcoll(const wchar_t *s1, const wchar_t *s2) {
 	int	 val;

==== //depot/projects/soc2008/gabor_textproc/newsort/file.c#2 (text+ko) ====

@@ -36,6 +36,10 @@
 
 #include "sort.h"
 
+/*
+ * Prints the internal buffer to a file or to stdout if
+ * "-" is given as output filename.
+ */
 void
 print(char *fn) {
 	FILE		*file = NULL;
@@ -48,6 +52,10 @@
 	fclose(file);
 }
 
+/*
+ * Checks if the given file is sorted.  Stops at the first disorder,
+ * prints the disordered line and returns 1.
+ */
 int
 check(char *fn) {
 	int		 pos = 1;
@@ -81,6 +89,10 @@
 	return (0);
 }
 
+/*
+ * Opens a file.  If the given filename is "-", stdout will be
+ * opened.
+ */
 FILE
 *openfile(char *fn, char *mode) {
 	FILE	*file;
@@ -104,6 +116,9 @@
 	return (file);
 }
 
+/*
+ * Reads a file into the internal buffer.
+ */
 int
 procfile(FILE *file) {
 	wchar_t		*line, *item;
@@ -124,6 +139,9 @@
 	return (0);
 }
 
+/*
+ * Calculates the optimal buffer size.
+ */
 int
 optbufsize(char *fn) {
 	struct stat	 st;
@@ -142,6 +160,10 @@
 		return (st.st_size/OPT_SLICES);
 }
 
+/*
+ * Prints the content of f1 to f2, which can also be
+ * stdout.
+ */
 void
 printfile(FILE *f1, FILE *f2) {
 	wchar_t		*s, *tmp;
@@ -156,6 +178,10 @@
 	fclose(f1);
 }
 
+/*
+ * Merges the two given files into the third file, which can be
+ * stdout.
+ */
 void
 merge_files(char *fn1, char *fn2, char *fn3) {
 	FILE		*f1, *f2, *f3;

==== //depot/projects/soc2008/gabor_textproc/newsort/mem.c#2 (text+ko) ====

@@ -29,6 +29,9 @@
 
 #include "sort.h"
 
+/*
+ * Safe malloc().
+ */
 void *
 sort_malloc(size_t size)
 {
@@ -39,6 +42,9 @@
 	return (ptr);
 }
 
+/*
+ * Safe realloc().
+ */
 void *
 sort_realloc(void *ptr, size_t size)
 {

==== //depot/projects/soc2008/gabor_textproc/newsort/msort.c#2 (text+ko) ====

@@ -28,6 +28,9 @@
 
 #include "sort.h"
 
+/*
+ * Merges two arrays and returns the result.
+ */
 wchar_t
 **merge(wchar_t **left, int leftn, wchar_t **right, int rightn) {
 	wchar_t	**result;
@@ -51,6 +54,10 @@
 	return (result);
 }
 
+/*
+ * This is the well-known recursive merge sort
+ * algorithm.
+ */
 wchar_t
 **merge_sort(wchar_t **arr, int len) {
 	wchar_t	**left, **right, **result;

==== //depot/projects/soc2008/gabor_textproc/newsort/sort.c#2 (text+ko) ====