Bug 176197
| Summary: | [PATCH] Add example to qsort.3 | ||||||||
|---|---|---|---|---|---|---|---|---|---|
| Product: | Documentation | Reporter: | Fernando <fapesteguia> | ||||||
| Component: | Books & Articles | Assignee: | Giorgos Keramidas <keramida> | ||||||
| Status: | Closed FIXED | ||||||||
| Severity: | Affects Only Me | ||||||||
| Priority: | Normal | ||||||||
| Version: | Latest | ||||||||
| Hardware: | Any | ||||||||
| OS: | Any | ||||||||
| Attachments: |
|
||||||||
|
Description
Fernando
2013-02-16 18:00:00 UTC
Responsible Changed From-To: freebsd-doc->keramida I'll take care of this. State Changed From-To: open->patched Fixed in /head with revision 246917. I made a few tiny changes to the sample program, like rename str_compare to int_compare (since it compares int values not strings), and replacing the p1/p2 casted duplicates inside the function with: int *left = (int *)p1; int *right = (int *)p2; and then using *left/*right in the comparisons. Many thanks for the original idea & patch though :-) Author: keramida (doc committer) Date: Tue Feb 19 23:57:39 2013 New Revision: 247014 URL: http://svnweb.freebsd.org/changeset/base/247014 Log: Add a sample program that shows how a custom comparison function and qsort(3) can work together to sort an array of integers. PR: docs/176197 Submitted by: Fernando, fapesteguia at opensistemas.com Approved by: gjb (mentor) MFC after: 1 week Modified: head/lib/libc/stdlib/qsort.3 Modified: head/lib/libc/stdlib/qsort.3 ============================================================================== --- head/lib/libc/stdlib/qsort.3 Tue Feb 19 23:46:51 2013 (r247013) +++ head/lib/libc/stdlib/qsort.3 Tue Feb 19 23:57:39 2013 (r247014) @@ -32,7 +32,7 @@ .\" @(#)qsort.3 8.1 (Berkeley) 6/4/93 .\" $FreeBSD$ .\" -.Dd September 30, 2003 +.Dd February 20, 2013 .Dt QSORT 3 .Os .Sh NAME @@ -211,6 +211,52 @@ Previous versions of did not permit the comparison routine itself to call .Fn qsort 3 . This is no longer true. +.Sh EXAMPLES +A sample program that sorts an array of +.Vt int +values in place using +.Fn qsort , +and then prints the sorted array to standard output is: +.Bd -literal +#include <stdio.h> +#include <stdlib.h> +#include <string.h> + +/* + * Custom comparison function that can compare 'int' values through pointers + * passed by qsort(3). + */ +static int +int_compare(const void *p1, const void *p2) +{ + int *left = (int *)p1; + int *right = (int *)p2; + + if (*left < *right) + return (-1); + else if (*left > *right) + return (1); + else + return (0); +} + +/* + * Sort an array of 'int' values and print it to standard output. + */ +int +main(void) +{ + int int_array[] = { 4, 5, 9, 3, 0, 1, 7, 2, 8, 6 }; + const int array_size = sizeof(int_array) / sizeof(int_array[0]); + int k; + + qsort(&int_array, array_size, sizeof(int), int_compare); + for (k = 0; k < array_size; k++) + printf(" %d", int_array[k]); + printf("\\n"); + exit(EXIT_SUCCESS); +} +.Ed .Sh ERRORS The .Fn heapsort _______________________________________________ svn-src-all@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/svn-src-all To unsubscribe, send any mail to "svn-src-all-unsubscribe@freebsd.org" Thanks Giorgios for the commit. I agree with the changes. They improve readability of the code. I plan to submit more examples for some man pages. In fact I did it before this PR, but I forgot to put [PATCH] at the beginning of the subject. The one I'm talking about is: http://www.freebsd.org/cgi/query-pr.cgi?pr=173448 Could you have a look at it? Cheers. Hi, please have a look at the attached patch, which contains some small improvements for the qsort exmaple. Christoph I would apply the patch especially because the cast away of constness in the pointers. Though it is a common idiom, I would rather keep the two if statements instead of the single return line. As this is an example I think it is clearer that way. Cheers. Author: keramida (doc committer) Date: Sat Feb 23 12:31:52 2013 New Revision: 247189 URL: http://svnweb.freebsd.org/changeset/base/247189 Log: Now that qsort(3) has a sample comparison function, point to that example from bsearch(3) too, so that we don't have to duplicate the example code in both places. PR: docs/176197 Reviewed by: stefanf Approved by: remko (mentor), gjb (mentor) MFC after: 1 week Modified: head/lib/libc/stdlib/bsearch.3 Modified: head/lib/libc/stdlib/bsearch.3 ============================================================================== --- head/lib/libc/stdlib/bsearch.3 Sat Feb 23 12:00:51 2013 (r247188) +++ head/lib/libc/stdlib/bsearch.3 Sat Feb 23 12:31:52 2013 (r247189) @@ -32,7 +32,7 @@ .\" @(#)bsearch.3 8.3 (Berkeley) 4/19/94 .\" $FreeBSD$ .\" -.Dd April 19, 1994 +.Dd February 22, 2013 .Dt BSEARCH 3 .Os .Sh NAME @@ -71,6 +71,12 @@ less than, equal to, or greater than zer .Fa key object is found, respectively, to be less than, to match, or be greater than the array member. +See the +.Fa int_compare +sample function in +.Xr qsort 3 +for a comparison function that is also compatible with +.Fn bsearch . .Sh RETURN VALUES The .Fn bsearch _______________________________________________ svn-src-all@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/svn-src-all To unsubscribe, send any mail to "svn-src-all-unsubscribe@freebsd.org" Author: keramida (doc committer) Date: Mon Feb 25 19:08:46 2013 New Revision: 247275 URL: http://svnweb.freebsd.org/changeset/base/247275 Log: MFH r247014, r247050 and r247051. Add a sample program that shows how a custom comparison function and qsort(3) can work together to sort an array of integers. PR: docs/176197 Submitted by: Fernando, fapesteguia at opensistemas.com Christoph Mallon, christoph.mallon at gmx.de Approved by: gjb (mentor), remko (mentor) Modified: stable/9/lib/libc/stdlib/qsort.3 Directory Properties: stable/9/lib/libc/ (props changed) Modified: stable/9/lib/libc/stdlib/qsort.3 ============================================================================== --- stable/9/lib/libc/stdlib/qsort.3 Mon Feb 25 19:05:40 2013 (r247274) +++ stable/9/lib/libc/stdlib/qsort.3 Mon Feb 25 19:08:46 2013 (r247275) @@ -32,7 +32,7 @@ .\" @(#)qsort.3 8.1 (Berkeley) 6/4/93 .\" $FreeBSD$ .\" -.Dd September 30, 2003 +.Dd February 20, 2013 .Dt QSORT 3 .Os .Sh NAME @@ -205,6 +205,46 @@ functions return no value. .Pp .Rv -std heapsort mergesort +.Sh EXAMPLES +A sample program that sorts an array of +.Vt int +values in place using +.Fn qsort , +and then prints the sorted array to standard output is: +.Bd -literal +#include <stdio.h> +#include <stdlib.h> + +/* + * Custom comparison function that can compare 'int' values through pointers + * passed by qsort(3). + */ +static int +int_compare(const void *p1, const void *p2) +{ + int left = *(const int *)p1; + int right = *(const int *)p2; + + return ((left > right) - (left < right)); +} + +/* + * Sort an array of 'int' values and print it to standard output. + */ +int +main(void) +{ + int int_array[] = { 4, 5, 9, 3, 0, 1, 7, 2, 8, 6 }; + const size_t array_size = sizeof(int_array) / sizeof(int_array[0]); + size_t k; + + qsort(&int_array, array_size, sizeof(int_array[0]), int_compare); + for (k = 0; k < array_size; k++) + printf(" %d", int_array[k]); + puts(""); + return (EXIT_SUCCESS); +} +.Ed .Sh COMPATIBILITY Previous versions of .Fn qsort _______________________________________________ svn-src-all@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/svn-src-all To unsubscribe, send any mail to "svn-src-all-unsubscribe@freebsd.org" Author: keramida (doc committer) Date: Mon Feb 25 19:09:13 2013 New Revision: 247276 URL: http://svnweb.freebsd.org/changeset/base/247276 Log: MFH r247014, r247050 and r247051. Add a sample program that shows how a custom comparison function and qsort(3) can work together to sort an array of integers. PR: docs/176197 Submitted by: Fernando, fapesteguia at opensistemas.com Christoph Mallon, christoph.mallon at gmx.de Approved by: gjb (mentor), remko (mentor) Modified: stable/8/lib/libc/stdlib/qsort.3 Directory Properties: stable/8/lib/libc/ (props changed) Modified: stable/8/lib/libc/stdlib/qsort.3 ============================================================================== --- stable/8/lib/libc/stdlib/qsort.3 Mon Feb 25 19:08:46 2013 (r247275) +++ stable/8/lib/libc/stdlib/qsort.3 Mon Feb 25 19:09:13 2013 (r247276) @@ -32,7 +32,7 @@ .\" @(#)qsort.3 8.1 (Berkeley) 6/4/93 .\" $FreeBSD$ .\" -.Dd September 30, 2003 +.Dd February 20, 2013 .Dt QSORT 3 .Os .Sh NAME @@ -205,6 +205,46 @@ functions return no value. .Pp .Rv -std heapsort mergesort +.Sh EXAMPLES +A sample program that sorts an array of +.Vt int +values in place using +.Fn qsort , +and then prints the sorted array to standard output is: +.Bd -literal +#include <stdio.h> +#include <stdlib.h> + +/* + * Custom comparison function that can compare 'int' values through pointers + * passed by qsort(3). + */ +static int +int_compare(const void *p1, const void *p2) +{ + int left = *(const int *)p1; + int right = *(const int *)p2; + + return ((left > right) - (left < right)); +} + +/* + * Sort an array of 'int' values and print it to standard output. + */ +int +main(void) +{ + int int_array[] = { 4, 5, 9, 3, 0, 1, 7, 2, 8, 6 }; + const size_t array_size = sizeof(int_array) / sizeof(int_array[0]); + size_t k; + + qsort(&int_array, array_size, sizeof(int_array[0]), int_compare); + for (k = 0; k < array_size; k++) + printf(" %d", int_array[k]); + puts(""); + return (EXIT_SUCCESS); +} +.Ed .Sh COMPATIBILITY Previous versions of .Fn qsort _______________________________________________ svn-src-all@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/svn-src-all To unsubscribe, send any mail to "svn-src-all-unsubscribe@freebsd.org" Author: keramida (doc committer) Date: Mon Feb 25 19:09:41 2013 New Revision: 247277 URL: http://svnweb.freebsd.org/changeset/base/247277 Log: MFH r247014, r247050 and r247051. Add a sample program that shows how a custom comparison function and qsort(3) can work together to sort an array of integers. PR: docs/176197 Submitted by: Fernando, fapesteguia at opensistemas.com Christoph Mallon, christoph.mallon at gmx.de Approved by: gjb (mentor), remko (mentor) Modified: stable/7/lib/libc/stdlib/qsort.3 Directory Properties: stable/7/lib/libc/ (props changed) Modified: stable/7/lib/libc/stdlib/qsort.3 ============================================================================== --- stable/7/lib/libc/stdlib/qsort.3 Mon Feb 25 19:09:13 2013 (r247276) +++ stable/7/lib/libc/stdlib/qsort.3 Mon Feb 25 19:09:41 2013 (r247277) @@ -32,7 +32,7 @@ .\" @(#)qsort.3 8.1 (Berkeley) 6/4/93 .\" $FreeBSD$ .\" -.Dd September 30, 2003 +.Dd February 20, 2013 .Dt QSORT 3 .Os .Sh NAME @@ -205,6 +205,46 @@ functions return no value. .Pp .Rv -std heapsort mergesort +.Sh EXAMPLES +A sample program that sorts an array of +.Vt int +values in place using +.Fn qsort , +and then prints the sorted array to standard output is: +.Bd -literal +#include <stdio.h> +#include <stdlib.h> + +/* + * Custom comparison function that can compare 'int' values through pointers + * passed by qsort(3). + */ +static int +int_compare(const void *p1, const void *p2) +{ + int left = *(const int *)p1; + int right = *(const int *)p2; + + return ((left > right) - (left < right)); +} + +/* + * Sort an array of 'int' values and print it to standard output. + */ +int +main(void) +{ + int int_array[] = { 4, 5, 9, 3, 0, 1, 7, 2, 8, 6 }; + const size_t array_size = sizeof(int_array) / sizeof(int_array[0]); + size_t k; + + qsort(&int_array, array_size, sizeof(int_array[0]), int_compare); + for (k = 0; k < array_size; k++) + printf(" %d", int_array[k]); + puts(""); + return (EXIT_SUCCESS); +} +.Ed .Sh COMPATIBILITY Previous versions of .Fn qsort _______________________________________________ svn-src-all@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/svn-src-all To unsubscribe, send any mail to "svn-src-all-unsubscribe@freebsd.org" State Changed From-To: patched->closed Merged to stable/9 stable/8 and stable/7 branches. Thanks! |
