[Python-checkins] CVS: python/dist/src/Objects object.c,2.159,2.160

[Tim Peters]

Update of /cvsroot/python/python/dist/src/Objects
In directory usw-pr-cvs1:/tmp/cvs-serv5704/python/Objects

Modified Files:
	object.c 
Log Message:
No code change -- just trying to document the return conditions for all
the internal comparison routines.


Index: object.c
===================================================================
RCS file: /cvsroot/python/python/dist/src/Objects/object.c,v
retrieving revision 2.159
retrieving revision 2.160
diff -C2 -d -r2.159 -r2.160
*** object.c	2001/10/22 16:30:36	2.159
--- object.c	2001/11/04 05:57:16	2.160
***************
*** 397,403 ****
     -1 for exception (including the case where try_rich_compare() returns an
        object that's not a Boolean);
!    0 if the outcome is false;
!    1 if the outcome is true;
!    2 if this particular rich comparison is not implemented or undefined.
  */
  static int
--- 397,403 ----
     -1 for exception (including the case where try_rich_compare() returns an
        object that's not a Boolean);
!     0 if the outcome is false;
!     1 if the outcome is true;
!     2 if this particular rich comparison is not implemented or undefined.
  */
  static int
***************
*** 423,430 ****
  /* Try rich comparisons to determine a 3-way comparison.  Return:
     -2 for an exception;
!    -1 if v < w;
!    0 if v == w;
!    1 if v > w;
!    2 if this particular rich comparison is not implemented or undefined.
  */
  static int
--- 423,430 ----
  /* Try rich comparisons to determine a 3-way comparison.  Return:
     -2 for an exception;
!    -1 if v  < w;
!     0 if v == w;
!     1 if v  > w;
!     2 if this particular rich comparison is not implemented or undefined.
  */
  static int
***************
*** 456,463 ****
  /* Try a 3-way comparison, returning an int.  Return:
     -2 for an exception;
!    -1 if v < w;
!    0 if v == w;
!    1 if v > w;
!    2 if this particular 3-way comparison is not implemented or undefined.
  */
  static int
--- 456,463 ----
  /* Try a 3-way comparison, returning an int.  Return:
     -2 for an exception;
!    -1 if v <  w;
!     0 if v == w;
!     1 if v  > w;
!     2 if this particular 3-way comparison is not implemented or undefined.
  */
  static int
***************
*** 524,530 ****
  /* Final fallback 3-way comparison, returning an int.  Return:
     -2 if an error occurred;
!    -1 if v < w;
!    0 if v == w;
!    1 if v > w.
  */
  static int
--- 524,530 ----
  /* Final fallback 3-way comparison, returning an int.  Return:
     -2 if an error occurred;
!    -1 if v <  w;
!     0 if v == w;
!     1 if v >  w.
  */
  static int
***************
*** 591,597 ****
  /* Do a 3-way comparison, by hook or by crook.  Return:
     -2 for an exception;
!    -1 if v < w;
      0 if v == w;
!     1 if v > w;
     If the object implements a tp_compare function, it returns
     whatever this function returns (whether with an exception or not).
--- 591,597 ----
  /* Do a 3-way comparison, by hook or by crook.  Return:
     -2 for an exception;
!    -1 if v <  w;
      0 if v == w;
!     1 if v >  w;
     If the object implements a tp_compare function, it returns
     whatever this function returns (whether with an exception or not).
***************
*** 724,727 ****
--- 724,734 ----
  }
  
+ /* Compare v to w.  Return
+    -1 if v <  w or exception (PyErr_Occurred() true in latter case).
+     0 if v == w.
+     1 if v > w.
+    XXX The docs (C API manual) say the return value is undefined in case
+    XXX of error.
+ */
  int
  PyObject_Compare(PyObject *v, PyObject *w)
***************
*** 772,775 ****
--- 779,783 ----
  }
  
+ /* Return (new reference to) Py_True or Py_False. */
  static PyObject *
  convert_3way_to_object(int op, int c)
***************
*** 789,793 ****
  }
  	
! 
  static PyObject *
  try_3way_to_rich_compare(PyObject *v, PyObject *w, int op)
--- 797,806 ----
  }
  	
! /* We want a rich comparison but don't have one.  Try a 3-way cmp instead.
!    Return
!    NULL      if error
!    Py_True   if v op w
!    Py_False  if not (v op w)
! */
  static PyObject *
  try_3way_to_rich_compare(PyObject *v, PyObject *w, int op)
***************
*** 803,806 ****
--- 816,825 ----
  }
  
+ /* Do rich comparison on v and w.  Return
+    NULL      if error
+    Else a new reference to an object other than Py_NotImplemented, usually(?):
+    Py_True   if v op w
+    Py_False  if not (v op w)
+ */
  static PyObject *
  do_richcmp(PyObject *v, PyObject *w, int op)
***************
*** 842,845 ****
--- 861,871 ----
  }
  
+ /* Return:
+    NULL for exception;
+    NotImplemented if this particular rich comparison is not implemented or
+      undefined;
+    some object not equal to NotImplemented if it is implemented
+      (this latter object may not be a Boolean).
+ */
  PyObject *
  PyObject_RichCompare(PyObject *v, PyObject *w, int op)