[win32] integrate mainline
[p5sagit/p5-mst-13.2.git] / pp_ctl.c
index f5454ec..9753fcf 100644 (file)
--- a/pp_ctl.c
+++ b/pp_ctl.c
@@ -33,9 +33,8 @@ static I32 dopoptolabel _((char *label));
 static I32 dopoptoloop _((I32 startingblock));
 static I32 dopoptosub _((I32 startingblock));
 static void save_lines _((AV *array, SV *sv));
-static int sortcv _((const void *, const void *));
-static int sortcmp _((const void *, const void *));
-static int sortcmp_locale _((const void *, const void *));
+static I32 sortcv _((SV *a, SV *b));
+static void qsortsv _((SV **array, size_t num_elts, I32 (*fun)(SV *a, SV *b)));
 static OP *doeval _((int gimme, OP** startop));
 
 static I32 sortcxix;
@@ -87,10 +86,12 @@ PP(pp_regcomp) {
     else {
        t = SvPV(tmpstr, len);
 
-       /* JMR: Check against the last compiled regexp */
-       if ( ! pm->op_pmregexp  || ! pm->op_pmregexp->precomp
-           || strnNE(pm->op_pmregexp->precomp, t, len) 
-           || pm->op_pmregexp->precomp[len]) {
+       /* JMR: Check against the last compiled regexp
+          To know for sure, we'd need the length of precomp.
+          But we don't have it, so we must ... take a guess. */
+       if (!pm->op_pmregexp || !pm->op_pmregexp->precomp ||
+           memNE(pm->op_pmregexp->precomp, t, len + 1))
+       {
            if (pm->op_pmregexp) {
                ReREFCNT_dec(pm->op_pmregexp);
                pm->op_pmregexp = Null(REGEXP*);        /* crucial if regcomp aborts */
@@ -546,11 +547,12 @@ PP(pp_grepstart)
     ENTER;                                     /* enter outer scope */
 
     SAVETMPS;
-#if 0
-    SAVE_DEFSV;
+#ifdef USE_THREADS
+    /* SAVE_DEFSV does *not* suffice here */
+    save_sptr(&THREADSV(0));
 #else
-    save_sptr(av_fetch(thr->threadsv, find_threadsv("_"), FALSE));
-#endif
+    SAVESPTR(GvSV(defgv));
+#endif /* USE_THREADS */
     ENTER;                                     /* enter inner scope */
     SAVESPTR(curpm);
 
@@ -739,7 +741,7 @@ PP(pp_sort)
            }
            sortcxix = cxstack_ix;
 
-           qsort((char*)(myorigmark+1), max, sizeof(SV*), sortcv);
+           qsortsv(myorigmark+1, max, sortcv);
 
            POPBLOCK(cx,curpm);
            SWITCHSTACK(sortstack, oldstack);
@@ -750,8 +752,8 @@ PP(pp_sort)
     else {
        if (max > 1) {
            MEXTEND(SP, 20);    /* Can't afford stack realloc on signal. */
-           qsort((char*)(ORIGMARK+1), max, sizeof(SV*),
-                 (op->op_private & OPpLOCALE) ? sortcmp_locale : sortcmp);
+           qsortsv(ORIGMARK+1, max,
+                 (op->op_private & OPpLOCALE) ? sv_cmp_locale : sv_cmp);
        }
     }
     stack_sp = ORIGMARK + max;
@@ -1009,7 +1011,7 @@ dounwind(I32 cxix)
     while (cxstack_ix > cxix) {
        cx = &cxstack[cxstack_ix];
        DEBUG_l(PerlIO_printf(Perl_debug_log, "Unwinding block %ld, type %s\n",
-                             (long) cxstack_ix+1, block_type[cx->cx_type]));
+                             (long) cxstack_ix, block_type[cx->cx_type]));
        /* Note: we don't need to restore the base context info till the end. */
        switch (cx->cx_type) {
        case CXt_SUBST:
@@ -1049,11 +1051,14 @@ die_where(char *message)
            if (svp) {
                if (!SvIOK(*svp)) {
                    static char prefix[] = "\t(in cleanup) ";
+                   SV *err = ERRSV;
                    sv_upgrade(*svp, SVt_IV);
                    (void)SvIOK_only(*svp);
-                   SvGROW(ERRSV, SvCUR(ERRSV)+sizeof(prefix)+klen);
-                   sv_catpvn(ERRSV, prefix, sizeof(prefix)-1);
-                   sv_catpvn(ERRSV, message, klen);
+                   if (!SvPOK(err))
+                       sv_setpv(err,"");
+                   SvGROW(err, SvCUR(err)+sizeof(prefix)+klen);
+                   sv_catpvn(err, prefix, sizeof(prefix)-1);
+                   sv_catpvn(err, message, klen);
                }
                sv_inc(*svp);
            }
@@ -1129,6 +1134,7 @@ PP(pp_caller)
     register PERL_CONTEXT *cx;
     I32 dbcxix;
     I32 gimme;
+    HV *hv;
     SV *sv;
     I32 count = 0;
 
@@ -1158,14 +1164,22 @@ PP(pp_caller)
     }
 
     if (GIMME != G_ARRAY) {
-       dTARGET;
-
-       sv_setpv(TARG, HvNAME(cx->blk_oldcop->cop_stash));
-       PUSHs(TARG);
+       hv = cx->blk_oldcop->cop_stash;
+       if (!hv)
+           PUSHs(&sv_undef);
+       else {
+           dTARGET;
+           sv_setpv(TARG, HvNAME(hv));
+           PUSHs(TARG);
+       }
        RETURN;
     }
 
-    PUSHs(sv_2mortal(newSVpv(HvNAME(cx->blk_oldcop->cop_stash), 0)));
+    hv = cx->blk_oldcop->cop_stash;
+    if (!hv)
+       PUSHs(&sv_undef);
+    else
+       PUSHs(sv_2mortal(newSVpv(HvNAME(hv), 0)));
     PUSHs(sv_2mortal(newSVpv(SvPVX(GvSV(cx->blk_oldcop->cop_filegv)), 0)));
     PUSHs(sv_2mortal(newSViv((I32)cx->blk_oldcop->cop_line)));
     if (!MAXARG)
@@ -1211,25 +1225,23 @@ PP(pp_caller)
            AvREAL_off(dbargs);         /* XXX Should be REIFY */
        }
 
-       if (AvMAX(dbargs) < AvFILL(ary) + off)
-           av_extend(dbargs, AvFILL(ary) + off);
-       Copy(AvALLOC(ary), AvARRAY(dbargs), AvFILL(ary) + 1 + off, SV*);
-       AvFILL(dbargs) = AvFILL(ary) + off;
+       if (AvMAX(dbargs) < AvFILLp(ary) + off)
+           av_extend(dbargs, AvFILLp(ary) + off);
+       Copy(AvALLOC(ary), AvARRAY(dbargs), AvFILLp(ary) + 1 + off, SV*);
+       AvFILLp(dbargs) = AvFILLp(ary) + off;
     }
     RETURN;
 }
 
-static int
-sortcv(const void *a, const void *b)
+static I32
+sortcv(SV *a, SV *b)
 {
     dTHR;
-    SV * const *str1 = (SV * const *)a;
-    SV * const *str2 = (SV * const *)b;
     I32 oldsaveix = savestack_ix;
     I32 oldscopeix = scopestack_ix;
     I32 result;
-    GvSV(firstgv) = *str1;
-    GvSV(secondgv) = *str2;
+    GvSV(firstgv) = a;
+    GvSV(secondgv) = b;
     stack_sp = stack_base;
     op = sortcop;
     runops();
@@ -1245,18 +1257,6 @@ sortcv(const void *a, const void *b)
     return result;
 }
 
-static int
-sortcmp(const void *a, const void *b)
-{
-    return sv_cmp(*(SV * const *)a, *(SV * const *)b);
-}
-
-static int
-sortcmp_locale(const void *a, const void *b)
-{
-    return sv_cmp_locale(*(SV * const *)a, *(SV * const *)b);
-}
-
 PP(pp_reset)
 {
     djSP;
@@ -1347,8 +1347,9 @@ PP(pp_enteriter)
        SAVESPTR(*svp);
     }
     else {
-       svp = &GvSV((GV*)POPs);                 /* symbol table variable */
-       SAVESPTR(*svp);
+       GV *gv = (GV*)POPs;
+       (void)save_scalar(gv);
+       svp = &GvSV(gv);                        /* symbol table variable */
     }
 
     ENTER;
@@ -1359,7 +1360,7 @@ PP(pp_enteriter)
        cx->blk_loop.iterary = (AV*)SvREFCNT_inc(POPs);
     else {
        cx->blk_loop.iterary = curstack;
-       AvFILL(curstack) = sp - stack_base;
+       AvFILLp(curstack) = sp - stack_base;
        cx->blk_loop.iterix = MARK - stack_base;
     }
 
@@ -1721,11 +1722,14 @@ PP(pp_goto)
            if (cxix < cxstack_ix)
                dounwind(cxix);
            TOPBLOCK(cx);
+           if (cx->cx_type == CXt_EVAL && cx->blk_eval.old_op_type == OP_ENTEREVAL) 
+               DIE("Can't goto subroutine from an eval-string");
            mark = stack_sp;
-           if (cx->blk_sub.hasargs) {   /* put @_ back onto stack */
+           if (cx->cx_type == CXt_SUB &&
+               cx->blk_sub.hasargs) {   /* put @_ back onto stack */
                AV* av = cx->blk_sub.argarray;
                
-               items = AvFILL(av) + 1;
+               items = AvFILLp(av) + 1;
                stack_sp++;
                EXTEND(stack_sp, items); /* @_ could have been extended. */
                Copy(AvARRAY(av), stack_sp, items, SV*);
@@ -1737,7 +1741,8 @@ PP(pp_goto)
                AvREAL_off(av);
                av_clear(av);
            }
-           if (!(CvDEPTH(cx->blk_sub.cv) = cx->blk_sub.olddepth))
+           if (cx->cx_type == CXt_SUB &&
+               !(CvDEPTH(cx->blk_sub.cv) = cx->blk_sub.olddepth))
                SvREFCNT_dec(cx->blk_sub.cv);
            oldsave = scopestack[scopestack_ix - 1];
            LEAVE_SCOPE(oldsave);
@@ -1767,6 +1772,12 @@ PP(pp_goto)
            else {
                AV* padlist = CvPADLIST(cv);
                SV** svp = AvARRAY(padlist);
+               if (cx->cx_type == CXt_EVAL) {
+                   in_eval = cx->blk_eval.old_in_eval;
+                   eval_root = cx->blk_eval.old_eval_root;
+                   cx->cx_type = CXt_SUB;
+                   cx->blk_sub.hasargs = 0;
+               }
                cx->blk_sub.cv = cv;
                cx->blk_sub.olddepth = CvDEPTH(cv);
                CvDEPTH(cv)++;
@@ -1775,10 +1786,10 @@ PP(pp_goto)
                else {  /* save temporaries on recursion? */
                    if (CvDEPTH(cv) == 100 && dowarn)
                        sub_crush_depth(cv);
-                   if (CvDEPTH(cv) > AvFILL(padlist)) {
+                   if (CvDEPTH(cv) > AvFILLp(padlist)) {
                        AV *newpad = newAV();
                        SV **oldpad = AvARRAY(svp[CvDEPTH(cv)-1]);
-                       I32 ix = AvFILL((AV*)svp[1]);
+                       I32 ix = AvFILLp((AV*)svp[1]);
                        svp = AvARRAY(svp[0]);
                        for ( ;ix > 0; ix--) {
                            if (svp[ix] != &sv_undef) {
@@ -1812,7 +1823,7 @@ PP(pp_goto)
                            AvFLAGS(av) = AVf_REIFY;
                        }
                        av_store(padlist, CvDEPTH(cv), (SV*)newpad);
-                       AvFILL(padlist) = CvDEPTH(cv);
+                       AvFILLp(padlist) = CvDEPTH(cv);
                        svp = AvARRAY(padlist);
                    }
                }
@@ -1820,7 +1831,7 @@ PP(pp_goto)
                if (!cx->blk_sub.hasargs) {
                    AV* av = (AV*)curpad[0];
                    
-                   items = AvFILL(av) + 1;
+                   items = AvFILLp(av) + 1;
                    if (items) {
                        /* Mark is at the end of the stack. */
                        EXTEND(sp, items);
@@ -1860,7 +1871,7 @@ PP(pp_goto)
                        }
                    }
                    Copy(mark,AvARRAY(av),items,SV*);
-                   AvFILL(av) = items - 1;
+                   AvFILLp(av) = items - 1;
                    
                    while (items--) {
                        if (*mark)
@@ -2119,7 +2130,7 @@ sv_compile_2op(SV *sv, OP** startop, char *code, AV** avp)
     dSP;                               /* Make POPBLOCK work. */
     PERL_CONTEXT *cx;
     SV **newsp;
-    I32 gimme;
+    I32 gimme = 0;   /* SUSPECT - INITIALZE TO WHAT?  NI-S */
     I32 optype;
     OP dummy;
     OP *oop = op, *rop;
@@ -2173,6 +2184,7 @@ doeval(int gimme, OP** startop)
     HV *newstash;
     CV *caller;
     AV* comppadlist;
+    I32 i;
 
     in_eval = 1;
 
@@ -2189,6 +2201,16 @@ doeval(int gimme, OP** startop)
     SAVEI32(max_intro_pending);
 
     caller = compcv;
+    for (i = cxstack_ix - 1; i >= 0; i--) {
+       PERL_CONTEXT *cx = &cxstack[i];
+       if (cx->cx_type == CXt_EVAL)
+           break;
+       else if (cx->cx_type == CXt_SUB) {
+           caller = cx->blk_sub.cv;
+           break;
+       }
+    }
+
     SAVESPTR(compcv);
     compcv = (CV*)NEWSV(1104,0);
     sv_upgrade((SV *)compcv, SVt_PVCV);
@@ -2336,6 +2358,7 @@ PP(pp_require)
     register PERL_CONTEXT *cx;
     SV *sv;
     char *name;
+    STRLEN len;
     char *tryname;
     SV *namesv = Nullsv;
     SV** svp;
@@ -2350,12 +2373,12 @@ PP(pp_require)
                SvPV(sv,na),patchlevel);
        RETPUSHYES;
     }
-    name = SvPV(sv, na);
-    if (!*name)
+    name = SvPV(sv, len);
+    if (!(name && len > 0 && *name))
        DIE("Null filename used");
     TAINT_PROPER("require");
     if (op->op_type == OP_REQUIRE &&
-      (svp = hv_fetch(GvHVn(incgv), name, SvCUR(sv), 0)) &&
+      (svp = hv_fetch(GvHVn(incgv), name, len, 0)) &&
       *svp != &sv_undef)
        RETPUSHYES;
 
@@ -2378,7 +2401,7 @@ PP(pp_require)
     )
     {
        tryname = name;
-       tryrsfp = PerlIO_open(name,"r");
+       tryrsfp = PerlIO_open(name,PERL_SCRIPT_MODE);
     }
     else {
        AV *ar = GvAVn(incgv);
@@ -2401,7 +2424,7 @@ PP(pp_require)
                sv_setpvf(namesv, "%s/%s", dir, name);
 #endif
                tryname = SvPVX(namesv);
-               tryrsfp = PerlIO_open(tryname, "r");
+               tryrsfp = PerlIO_open(tryname, PERL_SCRIPT_MODE);
                if (tryrsfp) {
                    if (tryname[0] == '.' && tryname[1] == '/')
                        tryname += 2;
@@ -2589,10 +2612,10 @@ PP(pp_leaveeval)
      * (Note that the fact that compcv and friends are still set here
      * is, AFAIK, an accident.)  --Chip
      */
-    if (AvFILL(comppad_name) >= 0) {
+    if (AvFILLp(comppad_name) >= 0) {
        SV **svp = AvARRAY(comppad_name);
        I32 ix;
-       for (ix = AvFILL(comppad_name); ix >= 0; ix--) {
+       for (ix = AvFILLp(comppad_name); ix >= 0; ix--) {
            SV *sv = svp[ix];
            if (sv && sv != &sv_undef && *SvPVX(sv) == '&') {
                SvREFCNT_dec(sv);
@@ -2617,6 +2640,7 @@ PP(pp_leaveeval)
     assert(CvDEPTH(compcv) == 1);
 #endif
     CvDEPTH(compcv) = 0;
+    lex_end();
 
     if (optype == OP_REQUIRE &&
        !(gimme == G_SCALAR ? SvTRUE(*sp) : sp > newsp))
@@ -2625,13 +2649,13 @@ PP(pp_leaveeval)
        char *name = cx->blk_eval.old_name;
        (void)hv_delete(GvHVn(incgv), name, strlen(name), G_DISCARD);
        retop = die("%s did not return a true value", name);
+       /* die_where() did LEAVE, or we won't be here */
+    }
+    else {
+       LEAVE;
+       if (!(save_flags & OPf_SPECIAL))
+           sv_setpv(ERRSV,"");
     }
-
-    lex_end();
-    LEAVE;
-
-    if (!(save_flags & OPf_SPECIAL))
-       sv_setpv(ERRSV,"");
 
     RETURNOP(retop);
 }
@@ -2881,3 +2905,683 @@ doparseform(SV *sv)
     SvCOMPILED_on(sv);
 }
 
+/*
+ * The rest of this file was derived from source code contributed
+ * by Tom Horsley.
+ *
+ * NOTE: this code was derived from Tom Horsley's qsort replacement
+ * and should not be confused with the original code.
+ */
+
+/* Copyright (C) Tom Horsley, 1997. All rights reserved.
+
+   Permission granted to distribute under the same terms as perl which are
+   (briefly):
+
+    This program is free software; you can redistribute it and/or modify
+    it under the terms of either:
+
+       a) the GNU General Public License as published by the Free
+       Software Foundation; either version 1, or (at your option) any
+       later version, or
+
+       b) the "Artistic License" which comes with this Kit.
+
+   Details on the perl license can be found in the perl source code which
+   may be located via the www.perl.com web page.
+
+   This is the most wonderfulest possible qsort I can come up with (and
+   still be mostly portable) My (limited) tests indicate it consistently
+   does about 20% fewer calls to compare than does the qsort in the Visual
+   C++ library, other vendors may vary.
+
+   Some of the ideas in here can be found in "Algorithms" by Sedgewick,
+   others I invented myself (or more likely re-invented since they seemed
+   pretty obvious once I watched the algorithm operate for a while).
+
+   Most of this code was written while watching the Marlins sweep the Giants
+   in the 1997 National League Playoffs - no Braves fans allowed to use this
+   code (just kidding :-).
+
+   I realize that if I wanted to be true to the perl tradition, the only
+   comment in this file would be something like:
+
+   ...they shuffled back towards the rear of the line. 'No, not at the
+   rear!'  the slave-driver shouted. 'Three files up. And stay there...
+
+   However, I really needed to violate that tradition just so I could keep
+   track of what happens myself, not to mention some poor fool trying to
+   understand this years from now :-).
+*/
+
+/* ********************************************************** Configuration */
+
+#ifndef QSORT_ORDER_GUESS
+#define QSORT_ORDER_GUESS 2    /* Select doubling version of the netBSD trick */
+#endif
+
+/* QSORT_MAX_STACK is the largest number of partitions that can be stacked up for
+   future processing - a good max upper bound is log base 2 of memory size
+   (32 on 32 bit machines, 64 on 64 bit machines, etc). In reality can
+   safely be smaller than that since the program is taking up some space and
+   most operating systems only let you grab some subset of contiguous
+   memory (not to mention that you are normally sorting data larger than
+   1 byte element size :-).
+*/
+#ifndef QSORT_MAX_STACK
+#define QSORT_MAX_STACK 32
+#endif
+
+/* QSORT_BREAK_EVEN is the size of the largest partition we should insertion sort.
+   Anything bigger and we use qsort. If you make this too small, the qsort
+   will probably break (or become less efficient), because it doesn't expect
+   the middle element of a partition to be the same as the right or left -
+   you have been warned).
+*/
+#ifndef QSORT_BREAK_EVEN
+#define QSORT_BREAK_EVEN 6
+#endif
+
+/* ************************************************************* Data Types */
+
+/* hold left and right index values of a partition waiting to be sorted (the
+   partition includes both left and right - right is NOT one past the end or
+   anything like that).
+*/
+struct partition_stack_entry {
+   int left;
+   int right;
+#ifdef QSORT_ORDER_GUESS
+   int qsort_break_even;
+#endif
+};
+
+/* ******************************************************* Shorthand Macros */
+
+/* Note that these macros will be used from inside the qsort function where
+   we happen to know that the variable 'elt_size' contains the size of an
+   array element and the variable 'temp' points to enough space to hold a
+   temp element and the variable 'array' points to the array being sorted
+   and 'compare' is the pointer to the compare routine.
+
+   Also note that there are very many highly architecture specific ways
+   these might be sped up, but this is simply the most generally portable
+   code I could think of.
+*/
+
+/* Return < 0 == 0 or > 0 as the value of elt1 is < elt2, == elt2, > elt2
+*/
+#define qsort_cmp(elt1, elt2) \
+   ((*compare)(array[elt1], array[elt2]))
+
+#ifdef QSORT_ORDER_GUESS
+#define QSORT_NOTICE_SWAP swapped++;
+#else
+#define QSORT_NOTICE_SWAP
+#endif
+
+/* swaps contents of array elements elt1, elt2.
+*/
+#define qsort_swap(elt1, elt2) \
+   STMT_START { \
+      QSORT_NOTICE_SWAP \
+      temp = array[elt1]; \
+      array[elt1] = array[elt2]; \
+      array[elt2] = temp; \
+   } STMT_END
+
+/* rotate contents of elt1, elt2, elt3 such that elt1 gets elt2, elt2 gets
+   elt3 and elt3 gets elt1.
+*/
+#define qsort_rotate(elt1, elt2, elt3) \
+   STMT_START { \
+      QSORT_NOTICE_SWAP \
+      temp = array[elt1]; \
+      array[elt1] = array[elt2]; \
+      array[elt2] = array[elt3]; \
+      array[elt3] = temp; \
+   } STMT_END
+
+/* ************************************************************ Debug stuff */
+
+#ifdef QSORT_DEBUG
+
+static void
+break_here()
+{
+   return; /* good place to set a breakpoint */
+}
+
+#define qsort_assert(t) (void)( (t) || (break_here(), 0) )
+
+static void
+doqsort_all_asserts(
+   void * array,
+   size_t num_elts,
+   size_t elt_size,
+   int (*compare)(const void * elt1, const void * elt2),
+   int pc_left, int pc_right, int u_left, int u_right)
+{
+   int i;
+
+   qsort_assert(pc_left <= pc_right);
+   qsort_assert(u_right < pc_left);
+   qsort_assert(pc_right < u_left);
+   for (i = u_right + 1; i < pc_left; ++i) {
+      qsort_assert(qsort_cmp(i, pc_left) < 0);
+   }
+   for (i = pc_left; i < pc_right; ++i) {
+      qsort_assert(qsort_cmp(i, pc_right) == 0);
+   }
+   for (i = pc_right + 1; i < u_left; ++i) {
+      qsort_assert(qsort_cmp(pc_right, i) < 0);
+   }
+}
+
+#define qsort_all_asserts(PC_LEFT, PC_RIGHT, U_LEFT, U_RIGHT) \
+   doqsort_all_asserts(array, num_elts, elt_size, compare, \
+                 PC_LEFT, PC_RIGHT, U_LEFT, U_RIGHT)
+
+#else
+
+#define qsort_assert(t) ((void)0)
+
+#define qsort_all_asserts(PC_LEFT, PC_RIGHT, U_LEFT, U_RIGHT) ((void)0)
+
+#endif
+
+/* ****************************************************************** qsort */
+
+void
+qsortsv(
+   SV ** array,
+   size_t num_elts,
+   I32 (*compare)(SV *a, SV *b))
+{
+   register SV * temp;
+
+   struct partition_stack_entry partition_stack[QSORT_MAX_STACK];
+   int next_stack_entry = 0;
+
+   int part_left;
+   int part_right;
+#ifdef QSORT_ORDER_GUESS
+   int qsort_break_even;
+   int swapped;
+#endif
+
+   /* Make sure we actually have work to do.
+   */
+   if (num_elts <= 1) {
+      return;
+   }
+
+   /* Setup the initial partition definition and fall into the sorting loop
+   */
+   part_left = 0;
+   part_right = (int)(num_elts - 1);
+#ifdef QSORT_ORDER_GUESS
+   qsort_break_even = QSORT_BREAK_EVEN;
+#else
+#define qsort_break_even QSORT_BREAK_EVEN
+#endif
+   for ( ; ; ) {
+      if ((part_right - part_left) >= qsort_break_even) {
+         /* OK, this is gonna get hairy, so lets try to document all the
+            concepts and abbreviations and variables and what they keep
+            track of:
+
+            pc: pivot chunk - the set of array elements we accumulate in the
+                middle of the partition, all equal in value to the original
+                pivot element selected. The pc is defined by:
+
+                pc_left - the leftmost array index of the pc
+                pc_right - the rightmost array index of the pc
+
+                we start with pc_left == pc_right and only one element
+                in the pivot chunk (but it can grow during the scan).
+
+            u:  uncompared elements - the set of elements in the partition
+                we have not yet compared to the pivot value. There are two
+                uncompared sets during the scan - one to the left of the pc
+                and one to the right.
+
+                u_right - the rightmost index of the left side's uncompared set
+                u_left - the leftmost index of the right side's uncompared set
+
+                The leftmost index of the left sides's uncompared set
+                doesn't need its own variable because it is always defined
+                by the leftmost edge of the whole partition (part_left). The
+                same goes for the rightmost edge of the right partition
+                (part_right).
+
+                We know there are no uncompared elements on the left once we
+                get u_right < part_left and no uncompared elements on the
+                right once u_left > part_right. When both these conditions
+                are met, we have completed the scan of the partition.
+
+                Any elements which are between the pivot chunk and the
+                uncompared elements should be less than the pivot value on
+                the left side and greater than the pivot value on the right
+                side (in fact, the goal of the whole algorithm is to arrange
+                for that to be true and make the groups of less-than and
+                greater-then elements into new partitions to sort again).
+
+            As you marvel at the complexity of the code and wonder why it
+            has to be so confusing. Consider some of the things this level
+            of confusion brings:
+
+            Once I do a compare, I squeeze every ounce of juice out of it. I
+            never do compare calls I don't have to do, and I certainly never
+            do redundant calls.
+
+            I also never swap any elements unless I can prove there is a
+            good reason. Many sort algorithms will swap a known value with
+            an uncompared value just to get things in the right place (or
+            avoid complexity :-), but that uncompared value, once it gets
+            compared, may then have to be swapped again. A lot of the
+            complexity of this code is due to the fact that it never swaps
+            anything except compared values, and it only swaps them when the
+            compare shows they are out of position.
+         */
+         int pc_left, pc_right;
+         int u_right, u_left;
+
+         int s;
+
+         pc_left = ((part_left + part_right) / 2);
+         pc_right = pc_left;
+         u_right = pc_left - 1;
+         u_left = pc_right + 1;
+
+         /* Qsort works best when the pivot value is also the median value
+            in the partition (unfortunately you can't find the median value
+            without first sorting :-), so to give the algorithm a helping
+            hand, we pick 3 elements and sort them and use the median value
+            of that tiny set as the pivot value.
+
+            Some versions of qsort like to use the left middle and right as
+            the 3 elements to sort so they can insure the ends of the
+            partition will contain values which will stop the scan in the
+            compare loop, but when you have to call an arbitrarily complex
+            routine to do a compare, its really better to just keep track of
+            array index values to know when you hit the edge of the
+            partition and avoid the extra compare. An even better reason to
+            avoid using a compare call is the fact that you can drop off the
+            edge of the array if someone foolishly provides you with an
+            unstable compare function that doesn't always provide consistent
+            results.
+
+            So, since it is simpler for us to compare the three adjacent
+            elements in the middle of the partition, those are the ones we
+            pick here (conveniently pointed at by u_right, pc_left, and
+            u_left). The values of the left, center, and right elements
+            are refered to as l c and r in the following comments.
+         */
+
+#ifdef QSORT_ORDER_GUESS
+         swapped = 0;
+#endif
+         s = qsort_cmp(u_right, pc_left);
+         if (s < 0) {
+            /* l < c */
+            s = qsort_cmp(pc_left, u_left);
+            /* if l < c, c < r - already in order - nothing to do */
+            if (s == 0) {
+               /* l < c, c == r - already in order, pc grows */
+               ++pc_right;
+               qsort_all_asserts(pc_left, pc_right, u_left + 1, u_right - 1);
+            } else if (s > 0) {
+               /* l < c, c > r - need to know more */
+               s = qsort_cmp(u_right, u_left);
+               if (s < 0) {
+                  /* l < c, c > r, l < r - swap c & r to get ordered */
+                  qsort_swap(pc_left, u_left);
+                  qsort_all_asserts(pc_left, pc_right, u_left + 1, u_right - 1);
+               } else if (s == 0) {
+                  /* l < c, c > r, l == r - swap c&r, grow pc */
+                  qsort_swap(pc_left, u_left);
+                  --pc_left;
+                  qsort_all_asserts(pc_left, pc_right, u_left + 1, u_right - 1);
+               } else {
+                  /* l < c, c > r, l > r - make lcr into rlc to get ordered */
+                  qsort_rotate(pc_left, u_right, u_left);
+                  qsort_all_asserts(pc_left, pc_right, u_left + 1, u_right - 1);
+               }
+            }
+         } else if (s == 0) {
+            /* l == c */
+            s = qsort_cmp(pc_left, u_left);
+            if (s < 0) {
+               /* l == c, c < r - already in order, grow pc */
+               --pc_left;
+               qsort_all_asserts(pc_left, pc_right, u_left + 1, u_right - 1);
+            } else if (s == 0) {
+               /* l == c, c == r - already in order, grow pc both ways */
+               --pc_left;
+               ++pc_right;
+               qsort_all_asserts(pc_left, pc_right, u_left + 1, u_right - 1);
+            } else {
+               /* l == c, c > r - swap l & r, grow pc */
+               qsort_swap(u_right, u_left);
+               ++pc_right;
+               qsort_all_asserts(pc_left, pc_right, u_left + 1, u_right - 1);
+            }
+         } else {
+            /* l > c */
+            s = qsort_cmp(pc_left, u_left);
+            if (s < 0) {
+               /* l > c, c < r - need to know more */
+               s = qsort_cmp(u_right, u_left);
+               if (s < 0) {
+                  /* l > c, c < r, l < r - swap l & c to get ordered */
+                  qsort_swap(u_right, pc_left);
+                  qsort_all_asserts(pc_left, pc_right, u_left + 1, u_right - 1);
+               } else if (s == 0) {
+                  /* l > c, c < r, l == r - swap l & c, grow pc */
+                  qsort_swap(u_right, pc_left);
+                  ++pc_right;
+                  qsort_all_asserts(pc_left, pc_right, u_left + 1, u_right - 1);
+               } else {
+                  /* l > c, c < r, l > r - rotate lcr into crl to order */
+                  qsort_rotate(u_right, pc_left, u_left);
+                  qsort_all_asserts(pc_left, pc_right, u_left + 1, u_right - 1);
+               }
+            } else if (s == 0) {
+               /* l > c, c == r - swap ends, grow pc */
+               qsort_swap(u_right, u_left);
+               --pc_left;
+               qsort_all_asserts(pc_left, pc_right, u_left + 1, u_right - 1);
+            } else {
+               /* l > c, c > r - swap ends to get in order */
+               qsort_swap(u_right, u_left);
+               qsort_all_asserts(pc_left, pc_right, u_left + 1, u_right - 1);
+            }
+         }
+         /* We now know the 3 middle elements have been compared and
+            arranged in the desired order, so we can shrink the uncompared
+            sets on both sides
+         */
+         --u_right;
+         ++u_left;
+         qsort_all_asserts(pc_left, pc_right, u_left, u_right);
+
+         /* The above massive nested if was the simple part :-). We now have
+            the middle 3 elements ordered and we need to scan through the
+            uncompared sets on either side, swapping elements that are on
+            the wrong side or simply shuffling equal elements around to get
+            all equal elements into the pivot chunk.
+         */
+
+         for ( ; ; ) {
+            int still_work_on_left;
+            int still_work_on_right;
+
+            /* Scan the uncompared values on the left. If I find a value
+               equal to the pivot value, move it over so it is adjacent to
+               the pivot chunk and expand the pivot chunk. If I find a value
+               less than the pivot value, then just leave it - its already
+               on the correct side of the partition. If I find a greater
+               value, then stop the scan.
+            */
+            while (still_work_on_left = (u_right >= part_left)) {
+               s = qsort_cmp(u_right, pc_left);
+               if (s < 0) {
+                  --u_right;
+               } else if (s == 0) {
+                  --pc_left;
+                  if (pc_left != u_right) {
+                     qsort_swap(u_right, pc_left);
+                  }
+                  --u_right;
+               } else {
+                  break;
+               }
+               qsort_assert(u_right < pc_left);
+               qsort_assert(pc_left <= pc_right);
+               qsort_assert(qsort_cmp(u_right + 1, pc_left) <= 0);
+               qsort_assert(qsort_cmp(pc_left, pc_right) == 0);
+            }
+
+            /* Do a mirror image scan of uncompared values on the right
+            */
+            while (still_work_on_right = (u_left <= part_right)) {
+               s = qsort_cmp(pc_right, u_left);
+               if (s < 0) {
+                  ++u_left;
+               } else if (s == 0) {
+                  ++pc_right;
+                  if (pc_right != u_left) {
+                     qsort_swap(pc_right, u_left);
+                  }
+                  ++u_left;
+               } else {
+                  break;
+               }
+               qsort_assert(u_left > pc_right);
+               qsort_assert(pc_left <= pc_right);
+               qsort_assert(qsort_cmp(pc_right, u_left - 1) <= 0);
+               qsort_assert(qsort_cmp(pc_left, pc_right) == 0);
+            }
+
+            if (still_work_on_left) {
+               /* I know I have a value on the left side which needs to be
+                  on the right side, but I need to know more to decide
+                  exactly the best thing to do with it.
+               */
+               if (still_work_on_right) {
+                  /* I know I have values on both side which are out of
+                     position. This is a big win because I kill two birds
+                     with one swap (so to speak). I can advance the
+                     uncompared pointers on both sides after swapping both
+                     of them into the right place.
+                  */
+                  qsort_swap(u_right, u_left);
+                  --u_right;
+                  ++u_left;
+                  qsort_all_asserts(pc_left, pc_right, u_left, u_right);
+               } else {
+                  /* I have an out of position value on the left, but the
+                     right is fully scanned, so I "slide" the pivot chunk
+                     and any less-than values left one to make room for the
+                     greater value over on the right. If the out of position
+                     value is immediately adjacent to the pivot chunk (there
+                     are no less-than values), I can do that with a swap,
+                     otherwise, I have to rotate one of the less than values
+                     into the former position of the out of position value
+                     and the right end of the pivot chunk into the left end
+                     (got all that?).
+                  */
+                  --pc_left;
+                  if (pc_left == u_right) {
+                     qsort_swap(u_right, pc_right);
+                     qsort_all_asserts(pc_left, pc_right-1, u_left, u_right-1);
+                  } else {
+                     qsort_rotate(u_right, pc_left, pc_right);
+                     qsort_all_asserts(pc_left, pc_right-1, u_left, u_right-1);
+                  }
+                  --pc_right;
+                  --u_right;
+               }
+            } else if (still_work_on_right) {
+               /* Mirror image of complex case above: I have an out of
+                  position value on the right, but the left is fully
+                  scanned, so I need to shuffle things around to make room
+                  for the right value on the left.
+               */
+               ++pc_right;
+               if (pc_right == u_left) {
+                  qsort_swap(u_left, pc_left);
+                  qsort_all_asserts(pc_left+1, pc_right, u_left+1, u_right);
+               } else {
+                  qsort_rotate(pc_right, pc_left, u_left);
+                  qsort_all_asserts(pc_left+1, pc_right, u_left+1, u_right);
+               }
+               ++pc_left;
+               ++u_left;
+            } else {
+               /* No more scanning required on either side of partition,
+                  break out of loop and figure out next set of partitions
+               */
+               break;
+            }
+         }
+
+         /* The elements in the pivot chunk are now in the right place. They
+            will never move or be compared again. All I have to do is decide
+            what to do with the stuff to the left and right of the pivot
+            chunk.
+
+            Notes on the QSORT_ORDER_GUESS ifdef code:
+
+            1. If I just built these partitions without swapping any (or
+               very many) elements, there is a chance that the elements are
+               already ordered properly (being properly ordered will
+               certainly result in no swapping, but the converse can't be
+               proved :-).
+
+            2. A (properly written) insertion sort will run faster on
+               already ordered data than qsort will.
+
+            3. Perhaps there is some way to make a good guess about
+               switching to an insertion sort earlier than partition size 6
+               (for instance - we could save the partition size on the stack
+               and increase the size each time we find we didn't swap, thus
+               switching to insertion sort earlier for partitions with a
+               history of not swapping).
+
+            4. Naturally, if I just switch right away, it will make
+               artificial benchmarks with pure ascending (or descending)
+               data look really good, but is that a good reason in general?
+               Hard to say...
+         */
+
+#ifdef QSORT_ORDER_GUESS
+         if (swapped < 3) {
+#if QSORT_ORDER_GUESS == 1
+            qsort_break_even = (part_right - part_left) + 1;
+#endif
+#if QSORT_ORDER_GUESS == 2
+            qsort_break_even *= 2;
+#endif
+#if QSORT_ORDER_GUESS == 3
+            int prev_break = qsort_break_even;
+            qsort_break_even *= qsort_break_even;
+            if (qsort_break_even < prev_break) {
+               qsort_break_even = (part_right - part_left) + 1;
+            }
+#endif
+         } else {
+            qsort_break_even = QSORT_BREAK_EVEN;
+         }
+#endif
+
+         if (part_left < pc_left) {
+            /* There are elements on the left which need more processing.
+               Check the right as well before deciding what to do.
+            */
+            if (pc_right < part_right) {
+               /* We have two partitions to be sorted. Stack the biggest one
+                  and process the smallest one on the next iteration. This
+                  minimizes the stack height by insuring that any additional
+                  stack entries must come from the smallest partition which
+                  (because it is smallest) will have the fewest
+                  opportunities to generate additional stack entries.
+               */
+               if ((part_right - pc_right) > (pc_left - part_left)) {
+                  /* stack the right partition, process the left */
+                  partition_stack[next_stack_entry].left = pc_right + 1;
+                  partition_stack[next_stack_entry].right = part_right;
+#ifdef QSORT_ORDER_GUESS
+                  partition_stack[next_stack_entry].qsort_break_even = qsort_break_even;
+#endif
+                  part_right = pc_left - 1;
+               } else {
+                  /* stack the left partition, process the right */
+                  partition_stack[next_stack_entry].left = part_left;
+                  partition_stack[next_stack_entry].right = pc_left - 1;
+#ifdef QSORT_ORDER_GUESS
+                  partition_stack[next_stack_entry].qsort_break_even = qsort_break_even;
+#endif
+                  part_left = pc_right + 1;
+               }
+               qsort_assert(next_stack_entry < QSORT_MAX_STACK);
+               ++next_stack_entry;
+            } else {
+               /* The elements on the left are the only remaining elements
+                  that need sorting, arrange for them to be processed as the
+                  next partition.
+               */
+               part_right = pc_left - 1;
+            }
+         } else if (pc_right < part_right) {
+            /* There is only one chunk on the right to be sorted, make it
+               the new partition and loop back around.
+            */
+            part_left = pc_right + 1;
+         } else {
+            /* This whole partition wound up in the pivot chunk, so
+               we need to get a new partition off the stack.
+            */
+            if (next_stack_entry == 0) {
+               /* the stack is empty - we are done */
+               break;
+            }
+            --next_stack_entry;
+            part_left = partition_stack[next_stack_entry].left;
+            part_right = partition_stack[next_stack_entry].right;
+#ifdef QSORT_ORDER_GUESS
+            qsort_break_even = partition_stack[next_stack_entry].qsort_break_even;
+#endif
+         }
+      } else {
+         /* This partition is too small to fool with qsort complexity, just
+            do an ordinary insertion sort to minimize overhead.
+         */
+         int i;
+         /* Assume 1st element is in right place already, and start checking
+            at 2nd element to see where it should be inserted.
+         */
+         for (i = part_left + 1; i <= part_right; ++i) {
+            int j;
+            /* Scan (backwards - just in case 'i' is already in right place)
+               through the elements already sorted to see if the ith element
+               belongs ahead of one of them.
+            */
+            for (j = i - 1; j >= part_left; --j) {
+               if (qsort_cmp(i, j) >= 0) {
+                  /* i belongs right after j
+                  */
+                  break;
+               }
+            }
+            ++j;
+            if (j != i) {
+               /* Looks like we really need to move some things
+               */
+              temp = array[i];
+              for (--i; i >= j; --i)
+                 array[i + 1] = array[i];
+               array[j] = temp;
+            }
+         }
+
+         /* That partition is now sorted, grab the next one, or get out
+            of the loop if there aren't any more.
+         */
+
+         if (next_stack_entry == 0) {
+            /* the stack is empty - we are done */
+            break;
+         }
+         --next_stack_entry;
+         part_left = partition_stack[next_stack_entry].left;
+         part_right = partition_stack[next_stack_entry].right;
+#ifdef QSORT_ORDER_GUESS
+         qsort_break_even = partition_stack[next_stack_entry].qsort_break_even;
+#endif
+      }
+   }
+
+   /* Believe it or not, the array is sorted at this point! */
+}