TIP #76: MAKE 'REGSUB' RETURN A STRING 
========================================
 Version:      $Revision: 1.3 $
 Author:       Bruce Hartweg <B.Hartweg_at_compaq.com>
               Donal K. Fellows <dkf_at_users.sf.net>
 State:        Final
 Type:         Project
 Tcl-Version:  8.4
 Vote:         Done
 Created:      Thursday, 29 November 2001
 URL:          https://tip.tcl-lang.org76.html
 Post-History: 

-------------------------------------------------------------------------

 ABSTRACT 
==========

 This TIP proposes altering the [regsub] command so that it can return 
 the substituted string as the result of the command. 

 RATIONALE 
===========

 In many of the most common uses of the [regsub] command, the 
 substituted string is used only once in the immediately following 
 command. However, the [regsub] command only provides the substituted 
 string via a variable, with the result of the command itself being the 
 number of substitutions performed. For many uses of the command, it is 
 the substituted string though that is the most useful result, 
 especially if some other transformation is going to be applied to it 
 (like further [regsub] commands or some other Tcl command like one of 
 the [string] subcommands or [subst].) This TIP proposes a mechanism for 
 providing the ability to return the string as the command's result, and 
 in a way that is backward-compatible with existing scripts. 

 SPECIFICATION 
===============

      regsub ?switches? exp string subSpec ?varName?

 If /varName/ is supplied the new string is written there and the number 
 of substitutions are returned (same as current behavior). If /varName/ 
 is not supplied than the new string is returned as the result of the 
 [regsub] command. 

 REFERENCE IMPLEMENTATION 
==========================

 This is a pretty easy change, although I do not currently have an 
 environment where I can actually build and test this the following 
 should create the desired behavior. 

 File: /tcl/generic/tclCmdMZ.c/ 

 Function: /Tcl_RegsubObjCmd/ 

 Currently (v 1.52): 

       if (objc - idx != 4) {
            Tcl_WrongNumArgs(interp, 1, objv,
                    "?switches? exp string subSpec varName");
            return TCL_ERROR;
       }

 which should be changed to: 

       objc -= idx;
       if (objc != 3 || objc != 4) {
            Tcl_WrongNumArgs(interp, 1, objv,
                    "?switches? exp string subSpec ?varName?");
            return TCL_ERROR;
       }

 and then at the end change this: 

       if (Tcl_ObjSetVar2(interp, objv[3], NULL, resultPtr, 0) == NULL) {
            Tcl_AppendResult(interp, "couldn't set variable \"",
                    Tcl_GetString(objv[3]), "\"", (char *) NULL);
            result = TCL_ERROR;
       } else {
            /*
             * Set the interpreter's object result to an integer object
             * holding the number of matches.
             */
   
            Tcl_SetIntObj(Tcl_GetObjResult(interp), numMatches);
       }

 to this: 

       if (objc == 4) {
           if (Tcl_ObjSetVar2(interp, objv[3], NULL, resultPtr, 0) == NULL) {
               Tcl_AppendResult(interp, "couldn't set variable \"",
                        Tcl_GetString(objv[3]), "\"", (char *) NULL);
               result = TCL_ERROR;
           } else {
               /*
                * Set the interpreter's object result to an integer object
                * holding the number of matches.
                */
   
               Tcl_SetIntObj(Tcl_GetObjResult(interp), numMatches);
           }
       } else {
              /*
               * No varname supplied, return string as result
               */
              Tcl_SetObjResult(interp, resultPtr);
       }

 And then minor updates to the man page to show that /varName/ is 
 optional. 

 COPYRIGHT 
===========

 This document has been placed in the public domain. 

-------------------------------------------------------------------------

 TIP AutoGenerator - written by Donal K. Fellows