qsort.hsf 2.3 KB

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