xHarbour Reference Documentation > Function Reference

CSetRef()

Queries or changes the pass-by-reference mode for several string functions.

Syntax

CSetRef( [<lNewMode>] ) --> lOldMode

Arguments

<lNewSetting> [ ]

Optionally, a logical value can be passed. .T. (true) switches the pass-by-reference mode on, while .F. (false) switches it off.

Return

The function returns the previous pass-by-reference mode as a logical value.

Description

The previous pass-by-reference mode is initially set to .F. (false) and can be switched on by passing .T. (true). The following functions recognize the previous pass-by-reference mode:

Functions recognizing CSetRef()

AddAscii()	CharSort()	ReplAll()
Blank()	CharSwap()	ReplLeft()
CharAdd()	CharXor()	ReplRight()
CharAnd()	Crypt()	TokenLower()
CharMirr()	JustLeft()	TokenUpper()
CharNot()	JustRight()	WordRepl()
CharOr()	PosChar()	WordSwap()
CharRelRep()	PosRepl()
CharRepl()	RangeRepl()

If the pass-by-reference mode is On, these functions operate on the original input string when it is passed by reference, rather than creating a copy of the input string and returning the processed copy as a result. In addition, these functions do not return a character string but a logical value when the pass-by-reference mode is On. The input string passed by reference becomes the return value, thus saving memory on string operations.

Info

See also:	CSetAtMuPa()
Category:	CT:String manipulation , Character functions
Source:	ct\ctstr.c
LIB:	xhb.lib
DLL:	xhbdll.dll

Example

// The example demonstrates the effect of the pass-by-reference
// mode by sorting a character string.

   PROCEDURE Main
      LOCAL cString := "xHarbour compiler"
      LOCAL cInput  := cString
      LOCAL cResult

      // extra memory for cResult required
      CSetRef( .F. )
      cResult := CharSort( @cInput )

      ? Valtype( cResult )     // result: C
      ? cResult                // result:  Habceilmooprrrux
      ? cInput                 // result:  Habceilmooprrrux

      cInput := cString

      // no extra memory for cResult required
      CSetRef( .T. )
      cResult := CharSort( @cInput )

      ? Valtype( cResult )     // result: L
      ? cResult                // result: .F.
      ? cInput                 // result:  Habceilmooprrrux
   RETURN