TIP #298: Revise Shared Value Rules for Tcl_GetBignumAndClearObj
_____________________________________________________________________________
TIP:	298
Title:	Revise Shared Value Rules for Tcl_GetBignumAndClearObj
Version:	$Revision: 1.6 $
Authors:	Don Porter <dgp@users.sf.net>
State:	Final
Type:	Project
Tcl-Version:	8.5
Vote:	Done
Created:	Wed Nov 22 00:00:00 UTC 2006
Keywords:	Tcl, Tcl_Obj
Abstract
This TIP proposes a revision to Tcl_GetBignumAndClearObj to make it easier to use.
Background
Tcl_GetBignumAndClearObj was added by [237]. Because mp_int values can be big, the interface is offered to avoid making a copy when the value already in the internal representation of an unshared Tcl_Obj will no longer be needed and can be moved instead of copied.
The basic intent was fine, but in practice, callers must go through these gymnastics to use it:
 if (Tcl_IsShared(objPtr)) 
     Tcl_GetBignumFromObj(interp, objPtr, &bigValue);
  else 
     Tcl_GetBignumAndClearObj(interp, objPtr, &bigValue);
 
It would make for a much more pleasant interface to move the test for a shared value into the routine itself.
Proposed Change
When passed a shared objPtr, Tcl_GetBignumAndClearObj will no longer panic, but will fall back to the copying behavior of Tcl_GetBignumFromObj. The use of the Tcl_GetBignumAndClearObj interface by a caller no longer means an assertion that objPtr is unshared, and no longer guarantees that objPtr will in fact be cleared, but merely indicates the caller will not be using the value anymore, and does not mind if it is cleared. That's all the caller should care about anyway.
Because of these changes in the implications and guarantees, the function is also renamed to Tcl_TakeBignumFromObj.
With these changes, the code above may be simplified to:
 Tcl_TakeBignumFromObj(interp, objPtr, &bigValue);
Compatibility
This is a incompatible change only with 8.5 alpha releases.
Reference Implementation
Available from [http://sourceforge.net/tracker/index.php?func=detail&aid=1601243&group_id=10894&atid=360894].
Copyright
This document has been placed in the public domain.
_____________________________________________________________________________
Colophon
TIP AutoGenerator - written by Donal K. Fellows