qsort.hsf 2.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142
  1. [Main]
  2. Name=qsort
  3. Type=Function
  4. Subtype=tigcc.a
  5. Header Files=stdlib.h
  6. Definition=void qsort (void *BasePtr, unsigned short NoOfElements, unsigned short Width, compare_t cmp_func);
  7. [Description]
  8. Sorts an area of items.
  9. [Explanation]
  10. qsort sorts the entries in a table by repeatedly calling the user-defined
  11. comparison function pointed to by <I>cmp_func</I>. <I>BasePtr</I> points to the base
  12. (0-th element) of the table to be sorted. <I>NoOfElement</I> is the number of
  13. entries in the table. <I>Width</I> is the size of each entry in the table, in
  14. bytes. <I>cmp_func</I>, the comparison function, accepts two arguments,
  15. <I>elem1</I> and <I>elem2</I>, each a pointer to an entry in the table.
  16. The comparison function compares each of the pointed-to items (*<I>elem1</I> and
  17. *<I>elem2</I>), and returns a short integer based on the result of the comparison:
  18. <UL>
  19. <LI>If *<I>elem1</I> &lt; *<I>elem2</I>, <I>cmp_func</I> should return an integer &lt; 0.</LI>
  20. <LI>If *<I>elem1</I> == *<I>elem2</I>, <I>cmp_func</I> should return 0.</LI>
  21. <LI>If *<I>elem1</I> &gt; *<I>elem2</I>, <I>cmp_func</I> should return an integer &gt; 0.</LI>
  22. </UL>
  23. In the comparison, the less-than symbol (&lt;) means the left element should
  24. appear before the right element in the final, sorted sequence. Similarly, the
  25. greater-than symbol (&gt;) means the left element should appear after the right element
  26. in the final, sorted sequence.
  27. <BR><BR>
  28. The ANSI standard proposes that the comparison function has to return a long integer.
  29. However, <A HREF="$$LINK(string.h/strcmp)">strcmp</A>, which is frequently
  30. used as a comparison function, returns a short integer.
  31. <BR><BR>
  32. <B>Note: if speed matters, create a qsort() routine in your program, and inline the comparison
  33. function and element copy/swap codes. Your routine will be significantly faster and smaller that way.</B>
  34. <BR><BR>
  35. Here is a complete example of usage (called "Sort Integers"):
  36. $$EXAMPLE(Sort Integers.c)
  37. Note that the function <A HREF="$$LINK(string.h/strcmp)">strcmp</A> is ideal for string comparisons.
  38. However, its parameters are not void pointers. This may be solved using a typecast like
  39. <PRE>qsort (<I>StringArray</I>, <I>NoOfStrings</I>, <I>LenOfEachString</I>, (compare_t) strcmp);
  40. </PRE>