<head>
 <body>
  <toc>
   <these>
    <get>
     <stripped>
      <h1 class="title">sort</h1>
      <div id="mainSection">
       <table>
        <col style="width: 5%"/>
        <tr>
         <td>
          <b>Definition:</b>
         </td>
         <td>
         <a href="sequence.htm">sequence</a> res = sort(<a href="sequence.htm">sequence</a> s, <a href="integer.htm">integer</a> order=ASCENDING)
         </td>
        </tr>
        <tr>
         <td>
          <b>Description:</b>
         </td>
         <td>
            Sort s using a fast sorting algorithm. The elements of s can be any mix of atoms or sequences.
         </td>
        </tr>
        <tr>
         <td>
          <a href="p2js.htm"><span class="pwap2js"><b>pwa/p2js:</b></span></a>
         </td>
         <td>
          Supported, may however trigger p2js violations, that usually need sort(<a href="deep_copy.htm">deep_copy</a>(s)) to fix.
         </td>
        </tr>
        <tr>
         <td>
          <b>Notes:</b>
         </td>
         <td>
            Atoms come before sequences, and sequences are sorted "alphabetically" where the first elements are more significant 
            than the later elements, and with case sensitively (whereby 'Z' is before 'a').
            <br>
            <br>
            The builtin constants ASCENDING and DESCENDING should be used for the order parameter, if required. That parameter 
            was added for compatibility with Euphoria, and likewise the constants NORMAL_ORDER and REVERSE_ORDER, which are
            (as per Euphoria) just aliases for ASCENDING and DESCENDING respectively, and therefore behave identically.
            <br>
            <br>
            For a case-insensitive sort, see "Another Example" in <a href="tagset.htm">tagset</a>().
            <br>
            <br>
            TIP: Should you experience a "p2js violation: relies on copy on write semantics" inside the sort() routine itself,
            use the call stack to determine where a call to <a href="deep_copy.htm">deep_copy</a>() should best be placed.
            <small>Update (1.0.1): "without debug" in builtins/sort.e c/should (now) land you on the right line.</small>
            In the majority of cases, <small><code>s = sort(s)</code></small> should work under with js without alteration 
            because s is a routine-local variable, but a deep_copy will be needed if it isn&rsquo;t or res!=s or some other
            variable still shares a reference to it. For obvious reasons sort() tries hard <i>(very hard)</i> to do everything
            in-situ so you can&rsquo;t be too upset or surprised when it needs a deep_copy(), and the latter is quite unlikely
            to do any more work or eat any more memory than some pre-"with js" version of that code always used to anyway. 
            Similar advice applies to <a href="unique.htm">unique</a>().
         </td>
        </tr>
        <tr>
         <td>
          <b>Example 1:</b>
         </td>
         <td>
<!--eucode>
x = 0 & sort({7,5,3,8}) & 0
-- x is set to {0, 3, 5, 7, 8, 0}
</eucode-->
<pre>
<font color="#000000">x</font><font color="#0000FF"> =</font><font color="#000000"> 0</font><font color="#0000FF"> &amp;</font><font color="#5E005E"> sort</font><font color="#0000FF">(</font><font color="#800000">{</font><font color="#000000">7</font><font color="#0000FF">,</font><font color="#000000">5</font><font color="#0000FF">,</font><font color="#000000">3</font><font color="#0000FF">,</font><font color="#000000">8</font><font color="#800000">}</font><font color="#0000FF">) &amp;</font><font color="#000000"> 0
</font><font color="#000080"><i>-- x is set to {0, 3, 5, 7, 8, 0}</i></font>
</pre>
         </td>
        </tr>
        <tr>
         <td>
          <b>Example 2:</b>
         </td>
         <td>
<!--eucode>
y = sort({"Smith", "Jones", "Doe", 5.5, 4, 6})
-- y is {4, 5.5, 6, "Doe", "Jones", "Smith"}
</eucode-->
<pre>
<font color="#000000">y</font><font color="#0000FF"> =</font><font color="#5E005E"> sort</font><font color="#0000FF">(</font><font color="#800000">{</font><font color="#008000">"Smith"</font><font color="#0000FF">,</font><font color="#008000"> "Jones"</font><font color="#0000FF">,</font><font color="#008000"> "Doe"</font><font color="#0000FF">,</font><font color="#000000"> 5.5</font><font color="#0000FF">,</font><font color="#000000"> 4</font><font color="#0000FF">,</font><font color="#000000"> 6</font><font color="#800000">}</font><font color="#0000FF">)
</font><font color="#000080"><i>-- y is {4, 5.5, 6, "Doe", "Jones", "Smith"}</i></font>
</pre>
         </td>
        </tr>
        <tr>
         <td>
          <b>Example 3:</b>
         </td>
         <td>
<!--eucode>
database = sort({{"Smith",    95.0, 29},
                 {"Jones",   77.2, 31},
                 {"Clinton", 88.7, 44}})
-- The 3 database "records" will be sorted by the first "field"
-- i.e. by name. Where the first field (element) is equal it
-- will be sorted by the second field etc.
-- after sorting, database is:
               {{"Clinton", 88.7, 44},
                {"Jones",   77.2, 31},
                {"Smith",   95.0, 29}}
</eucode-->
<pre>
<font color="#000000">database</font><font color="#0000FF"> =</font><font color="#5E005E"> sort</font><font color="#0000FF">(</font><font color="#800000">{</font><font color="#800080">{</font><font color="#008000">"Smith"</font><font color="#0000FF">,   </font><font color="#000000"> 95.0</font><font color="#0000FF">,</font><font color="#000000"> 29</font><font color="#800080">}</font><font color="#0000FF">,
</font><font color="#800080">                 {</font><font color="#008000">"Jones"</font><font color="#0000FF">,  </font><font color="#000000"> 77.2</font><font color="#0000FF">,</font><font color="#000000"> 31</font><font color="#800080">}</font><font color="#0000FF">,
</font><font color="#800080">                 {</font><font color="#008000">"Clinton"</font><font color="#0000FF">,</font><font color="#000000"> 88.7</font><font color="#0000FF">,</font><font color="#000000"> 44</font><font color="#800080">}</font><font color="#800000">}</font><font color="#0000FF">)
</font><font color="#000080"><i>-- The 3 database "records" will be sorted by the first "field"
-- i.e. by name. Where the first field (element) is equal it
-- will be sorted by the second field etc.
-- after sorting, database is:
</i></font><font color="#0000FF">               {</font><font color="#800000">{</font><font color="#008000">"Clinton"</font><font color="#0000FF">,</font><font color="#000000"> 88.7</font><font color="#0000FF">,</font><font color="#000000"> 44</font><font color="#800000">}</font><font color="#0000FF">,
</font><font color="#800000">                {</font><font color="#008000">"Jones"</font><font color="#0000FF">,  </font><font color="#000000"> 77.2</font><font color="#0000FF">,</font><font color="#000000"> 31</font><font color="#800000">}</font><font color="#0000FF">,
</font><font color="#800000">                {</font><font color="#008000">"Smith"</font><font color="#0000FF">,  </font><font color="#000000"> 95.0</font><font color="#0000FF">,</font><font color="#000000"> 29</font><font color="#800000">}</font><font color="#0000FF">}</font>
</pre>
         </td>
        </tr>
        <tr>
         <td>
          <b>Implementation:</b>
         </td>
         <td>
            See builtins\sort.e (an autoinclude) for details of the actual implementation.
         </td>
        </tr>
        <tr>
         <td>
          <b>See Also:</b>
         </td>
         <td>
          <a href="custom_sort.htm">custom_sort</a>,
          <a href="compare.htm">compare</a>,
          <a href="match.htm">match</a>,
          <a href="find.htm">find</a>
         </td>
        </tr>
        <tr id="Technicalia" style="display:none;">
         <td>
          <a href="glossary.htm#technicalia">
           <b>Technicalia</b>
          </a>
         </td>
         <td>
            In Phix, ASCENDING is defined as -1 (as is NORMAL_ORDER) and DESCENDING as +1 (as is REVSERSE_ORDER), 
            however Euphoria defines them the other way round, and then, for no sensible reason I can think of, 
            inverts the parameter (literally, <code>if order>=0 then order = -1 else order = 1 end if</code>) at 
            the start of both sort() and custom_sort(). Let me know if I missed something.
         </td>
        </tr>
       </table>
       <img src="images/sprites/tech.open.png" title="Expand/Shrink" alt="Expand/Shrink" style="display:block;clear:both;" onload="setStartT(this);" onclick="changeImageT(this);" />
      </div>
     </stripped>
    </get>
   </these>
  </toc>
 </body>
</head>
