Harbour Reference Guide

AddMonth()Source code  |  | Improve this doc

add months to a date
Syntax
AddMonth( [<dDate>,] <nMonths> ) → dShiftedDate
Description
TODO: add documentation
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 date and time functions

BoM()Source code  |  | Improve this doc

Begin of Month
Syntax
BoM( [<dDate>] ) → dDateBeginOfMonth
Description
TODO: add documentation
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 date and time functions
See also

BoQ()Source code  |  | Improve this doc

Begin of Quarter
Syntax
BoQ( [<dDate>] ) → dDateBeginOfQuarter
Description
TODO: add documentation
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 date and time functions
See also

BoY()Source code  |  | Improve this doc

Begin of Year
Syntax
BoY( [<dDate>] ) → dDateBeginOfYear
Description
TODO: add documentation
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 date and time functions
See also

CToDoW()Source code  |  | Improve this doc

convert name of day of the week to its ordinal number
Syntax
CToDoW( <cName> ) → nOrdinal
Description
TODO: add documentation
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 date and time functions
See also

CToMonth()Source code  |  | Improve this doc

convert name of month to its ordinal number
Syntax
CToMonth( <cName> ) → nOrdinal
Description
TODO: add documentation
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 date and time functions
See also

DMY()Source code  |  | Improve this doc

Returns the date as a string in DD Month YY format
Syntax
DMY( [<dDate>][, <lMode>] ) → cDateString
Description

Returns the date as a string in DD Month YY format. If lMode is TRUE, a "." is inserted after the DD.

TODO: add further documentation

Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 date and time functions
See also

DoY()Source code  |  | Improve this doc

Determines the day of the year for a specific date
Syntax
DMY( [<dDate>] ) → nDayOfYear
Description

Determines the day of the year for a specific date if dDate is invalid, returns 0.

TODO: add further documentation

Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 date and time functions

EoM()Source code  |  | Improve this doc

End of Month
Syntax
EoM( [<dDate>] ) → dDateEndOfMonth
Description
TODO: add documentation
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 date and time functions
See also

EoQ()Source code  |  | Improve this doc

End of Quarter
Syntax
EoQ( [<dDate>] ) → dDateEndOfQuarter
Description
TODO: add documentation
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 date and time functions
See also

EoY()Source code  |  | Improve this doc

End of Year
Syntax
EoY( [<dDate>] ) → dDateEndOfYear
Description
TODO: add documentation
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 date and time functions
See also

IsLeap()Source code  |  | Improve this doc

determines of year of date is a leap year
Syntax
IsLeap( [<dDate>] ) → lIsLeap
Description
TODO: add further documentation
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 date and time functions

LastDayOM()Source code  |  | Improve this doc

Returns the the number of days in the month.
Syntax
LastDayOM( [<dDate|nMonth>] ) → nDaysInMonth
Description

dDate|nMonth can be a date or a month number. If empty uses the system date. If nMonth is a 2, LastDayOM() will not know if it is a leap year or not. If dDate is invalid, returns 0

TODO: add further documentation

Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 date and time functions
See also

MDY()Source code  |  | Improve this doc

Returns the date as a string in Month DD, YY or Month DD, YYYY
Syntax
MDY( [<dDate>] ) → cDateString
Description

Returns the date as a string in Month DD, YY or Month DD, YYYY. If dDate is NULL, the system date is used.

TODO: add further documentation

Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 date and time functions
See also

NToCDoW()Source code  |  | Improve this doc

(num of day) → day name
Syntax
NToCDoW( <nDay> ) → cDay
Description
TODO: add documentation
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 date and time functions
See also

NToCMonth()Source code  |  | Improve this doc

(num of month ) → Month Name
Syntax
NToCMonth( <nMonth> ) → cMonth
Description
TODO: add documentation
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 date and time functions
See also

Quarter()Source code  |  | Improve this doc

Returns a number equal to the quarter in which a date falls
Syntax
Quarter( [<dDate>] ) → nQuarter
Description

Returns a number equal to the quarter in which dDate falls. If dDate is empty, the system date is employed.

TODO: add further documentation

Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 date and time functions

SetDate()Source code  |  | Improve this doc

Sets the system date
Syntax
SetDate( <dDate>, [<lMode>] ) → lSet
Arguments
dDate Designates which date to use to set the system date.
lMode Designates whether the date should also be set in the CMOS-RAM of an AT. The default is do not write (.F.). Note that in Windows platform this adjust is automatic, therefore this parameter is without effect.
Returns
SetDate() returns .T. when the date is successfully set.
Description
When you use this function to set the system date from within your application, all files acquire this date with each write procedure.
Examples
LOCAL dNewDate

// Set the system date in each case; but the hardware clock only
// on an AT:

dNewDate := hb_SToD( "19910730" )
IF IsAt()
   SetDate( dNewDate, .T. )
ELSE
   SetDate( dNewDate )
ENDIF

// Or, more compactly:

SetDate( dNewDate, IsAt() )
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on Linux
Available on Windows
File
Library is hbct.
Tag
CT3 date and time functions
See also

SetTime()Source code  |  | Improve this doc

Sets the system clock
Syntax
SetTime( <cTime>, [<lMode>] ) → lSet
Arguments
cTime Designates a character string that contains the time that is to become the system time.
lMode Designates whether the time should also be set in the CMOS-RAM of an AT. The default is do not write to CMOS-RAM. Note that in Windows platform this adjust is automatic, therefore this parameter is without effect.
Returns
The function returns .T. when the time is set successfully.
Description
When you use this function to convert the time into the system time from within your application, all files acquire this time with each write procedure.
Examples
LOCAL cNewTime

// Set the system time in each case; but the hardware clock only
// on an AT:

cNewTime := "10:20:00"
IF IsAt()
   SetTime( cNewTime, .T. )
ELSE
   SetTime( cNewTime )
ENDIF

// Or, more compactly:

SetTime( cNewTime, IsAt() )
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on Linux
Available on Windows
File
Library is hbct.
Tag
CT3 date and time functions
See also

TimeValid()Source code  |  | Improve this doc

Determines whether a specified time is valid
Syntax
TimeValid( <cTime> ) → lValid
Arguments
cTime Designates a character string that contains the time to test.
Returns
TimeValid() returns .T. when cTime is a valid time; or .F. when cTime is an invalid time.
Description

With input that requires time manipulation, writing your own UDF to check time inputs was unavoidable up to now. TimeValid() permits Complete checking of a time designation. You can use this function effectively with a VALID clause within a READ mask.

Note

Note the format for time designations. There must always be two digits for hours, minutes, seconds, and hundredths; otherwise, the time it is regarded as invalid. Valid examples are "12", "12:59", "12:59:59", and "12:59:59:99". By contrast, invalid examples are "24", "12:60", or "12:1", and/or "12:". If you work with time strings that are not completely filled and that you need to check with TimeValid(), then they must be RTrim()-med prior to the use of TimeValid() (see following Examples).

Examples
LOCAL cBegin, GetList := {}

// Using the VALID clause with RTrim(), all valid times are
// accepted, even if no seconds or minutes are specified:

cBegin := Space( 11 )
@ 5, 10 SAY "Please input time for beginning work:";
   GET cBegin VALID TimeValid( RTrim( cBegin ) )
READ

// Using a VALID clause without TRIM, hours and minutes must be
// specified, so that TimeValid() can confirm a valid time:

cBegin := Space( 5 )
@ 5, 10 SAY "Please input time for beginning work:" ;
   GET cBegin VALID TimeValid( cBegin )
READ
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 date and time functions
See also

WaitPeriod()Source code  |  | Improve this doc

Pauses a specified time in increments of 1/100 seconds
Syntax
WaitPeriod( [<nDelay>] ) → lNotElapsed
Arguments
nDelay Designates the waiting period at initialization in 1/100ths of seconds. Values from 1 to 8, 640, 000 (one day) are possible.
Returns
WaitPeriod() returns .T., if the time span designated at initialization has not elapsed.
Description

This function sets a time span for a DO WHILE loop to run. The function must initialize prior to the loop, since you must specify the nDelay parameter in 1/100th seconds. Subsequently, the function can be implemented without a parameter for additional loop conditions. It returns .T., as long as the designated time span has not yet run out.

Note:

The function notes the status of the internal timer at initialization. From that point on, the initialization should always precede the respective DO WHILE; otherwise, the time delay is incorrect. The passing of midnight (the time resets to the 0 value) is taken into account.

Examples
// Run a loop for 5 seconds:

WaitPeriod( 500 )             // Initialization, 5 seconds
DO WHILE <cond1> .AND. <cond2> .AND. WaitPeriod()
   // ...
ENDDO
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 date and time functions

Week()Source code  |  | Improve this doc

Returns the calendar week a number
Syntax
Week( [<dDate>][, <lSWN>] ) → nWeek
Description

Returns the calendar week a number. If no date is specified, the system date is used. An empty date via hb_SToD() returns 0.

If lSWN is .T., Week() will calculate the "simple week number", defined by

- week #1 starts on January, 1st - week #(n+1) starts seven days after start of week #n

If lSWN is .F. (default), the ISO 8601 week number, defined by

- weeks start on Mondays - week #1 is the one that includes January, 4

will be calculated

TODO: add further documentation

Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 date and time functions

CSetArgErr()Source code  |  | Improve this doc

Sets argument error behaviour
Syntax
CSetArgErr( [<nNewMode>] ) → nOldMode
Arguments
[nNewMode] New argument error throwing mode
Returns
nOldMode The current or old argument error throwing mode.
Description

All CT3 functions are very compliant in their reaction to wrong parameters. By using the CSetArgErr() function, you can make the library throw an error with the severity nNewMode. It is then up to the error handler to substitute the return value. nNewMode can be one of the severity modes defined in ct.ch:

 CT_ARGERR_WHOCARES      corresponds to ES_WHOCARES
 CT_ARGERR_WARNING       corresponds to ES_WARNING
 CT_ARGERR_ERROR         corresponds to ES_ERROR
 CT_ARGERR_CATASTROPHIC  corresponds to ES_CATASTROPHIC
 CT_ARGERR_IGNORE

The last is the default behaviour and switches any argument error throwing off.

Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 general functions

Acos()Source code  |  | Improve this doc

Arcus cosine of the argument
Syntax
Acos( nCosine ) → nRadiant
Arguments
nCosine the cosine of an angle
Returns
nRadiant the angle whose cosine is nCosine
Description
The function Acos() is the inverse function of Cos(). It takes a cosine value and returns the smallest(!) angle whose cosine equals to the argument. The return value is given in radiants (full angle equals 2 * Pi() - see DToR() if you need to convert it into degrees). Note, that nCosine must be between -1 and 1 and that nRadiant is always between 0 and Pi().
Examples
? Acos( 0.0 )  // --> Pi() / 2
? Acos( 0.5 )  // --> 1.04719...
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 math functions
See also

Asin()Source code  |  | Improve this doc

Arcus sine of the argument
Syntax
Asin( nSine ) → nRadiant
Arguments
nSine the sine of an angle
Returns
nRadiant the angle whose sine is nSine
Description
The function Asin() is the inverse function of Sin(). It takes a sine value and returns the smallest(!) angle whose sine equals to the argument. The return value is given in radiants (full angle equals 2 * Pi() - see DToR() if you need to convert it into degrees). Note, that nSine must be between -1 and 1 and that nRadiant is always between -Pi() / 2 and Pi() / 2.
Examples
? Asin( 0.0 )  // --> 0.0
? Asin( 0.5 )  // --> 0.5235...
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 math functions
See also

Atan()Source code  |  | Improve this doc

Arcus tangent of the argument
Syntax
Acos( nTangent ) → nRadiant
Arguments
nTangent the tangent of an angle
Returns
nRadiant the angle whose tangent is nTangent
Description
The function Atan() is the inverse function of Tan(). It takes a tangent value and returns the smallest(!) angle whose tangent equals to the argument. The return value is given in radiants between -Pi() / 2 and Pi() / 2 (full angle equals 2 * Pi() - see DToR() if you need to convert it into degrees).
Examples
? Atan( 0.0 )  // --> 0.0
? Atan( 0.5 )  // --> 0.4636...
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 math functions
See also

Atn2()Source code  |  | Improve this doc

Arcus tangent a sine and a cosine argument
Syntax
Atn2( nSine, nCosine ) → nRadiant
Arguments
nSine the sine of an angle nCosine the cosine of an angle
Returns
nRadiant the angle whose tangent is nSine/nCosine
Description
The function Atn2() is an alternate function for calculating the arcus tangent, Atn2( x, y ) = Atan( x / y). It takes two arguments, the sine and the cosine of the angle that should be calculated. Thus, in contrast to the Atan() function, Atn2() can distinguish whether the sine or the cosine has a negative sign (or both being positive or negative), so that the return value can be between -Pi() and Pi() and covers the full angle. The return value is given in radiants (full angle equals 2 * Pi() - see DToR() if you need to convert it into degrees).
Examples
? Atn2( 0.0, 1.0 )  // --> 0.0
? Atn2( Sqrt( 1 / 2 ), Sqrt( 1 / 2 ) )  // --> Pi() / 4
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 math functions
See also

Ceiling()Source code  |  | Improve this doc

Rounds up a number to the next integer
Syntax
Ceiling( <nNumber> ) → nUpRoundedNumber
Arguments
nNumber number to round up
Returns
nUpRoundedNumber the rounded number
Description
The function Ceiling() determines the smallest integer that is bigger than nNumber.
Examples
? Ceiling( 1.1 )   // --> 2.0
? Ceiling( -1.1 )  // --> -1.0
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 math functions
See also

Cos()Source code  |  | Improve this doc

Cosine of the argument
Syntax
Cos( nRadiant ) → nCosine
Arguments
nRadiant an angle size given in radiants
Returns
nCosine the cosine of nRadiant
Description
The function Cos() calculates the cosine of an angle whose size is given in radiants (full angle equals 2 * Pi() - see DToR() for angle size given in degrees). A common geometric interpretation of the Cos() function is the ankathede-hypotenuse-ratio of a right-angled triangle.
Examples
? Cos( 0.0 )  // --> 1.0
? Cos( 1.0 )  // --> 0.5403...
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 math functions
See also

Cosh()Source code  |  | Improve this doc

Hyperbolic Cosine of the argument
Syntax
Cosh( nArea ) → nHyperbolicCosine
Arguments
nArea the size of the area (see below)
Returns
nHyperbolicCosine the hyperbolic cosine of nArea
Description
The function Cosh() calculates the hyperbolic cosine of the argument. In analytical mathematics it is defined as 1 / 2 * ( Exp( nArea ) + Exp( -nArea ) ). A common geometric interpretation of the Cosh() function is the maximum x value of the points in the area with the given size nArea, that is bound by the x axis, a straight line through the point of origin (this one is fixed by the area) and the hyperbola x ^ 2 - y ^ 2 = 1.
Examples
? Cosh( 0.0 )  // --> 1.0
? Cosh( 1.0 )  // --> 1.5430...
Status
Ready
Compliance
Harbour specific
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 math functions
See also

Cot()Source code  |  | Improve this doc

Cotangent of the argument
Syntax
Cot( nRadiant ) → nCotangent
Arguments
nRadiant an angle size given in radiants
Returns
nCotangent the cotangent of nRadiant
Description
The function Cot() calculates the cotangent of an angle whose size is given in radiants (full angle equals 2 * Pi() - see DToR() for angle size given in degrees). A common geometric interpretation of the Cot() function is the ankathede-counterkathede-ratio of a right-angled triangle, or, Cot( x ) = Cos( x ) / Sin( x ) = 1 / Tan( x ).
Examples
? Cot( 1.0 )  // --> 0.6420...
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 math functions
See also

DToR()Source code  |  | Improve this doc

Convert degree to radiant
Syntax
DToR( nDegree ) → nRadiant
Arguments
nDegree the size of that angle in degree
Returns
nRadiant the size of an angle in radiant
Description
The function DToR() can be used to convert sizes of angles given in degrees to radiant (as expected by sin, cos or tan functions).
Examples
? DToR( 180 )  // --> Pi()
? DToR( 60 )   // --> Pi() / 3
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 math functions
See also

Fact()Source code  |  | Improve this doc

Calculates faculty
Syntax
Fact( <nNumber> ) → nFaculty
Arguments
nNumber number between 0 and 21
Returns
nFaculty the faculty of nNumber
Description
The function Fact() calculates the faculty to the integer given in nNumber. The faculty is defined as n! = 1*2*...*n and is often used in statistics. Note, that faculties above 21 are too big so that the function must return a -1.
Examples
? Fact( 0 )  // --> 1
? Fact( 1 )  // --> 1
? Fact( 4 )  // --> 24
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 math functions

Floor()Source code  |  | Improve this doc

Rounds down a number to the next integer
Syntax
Floor( <nNumber> ) → nDownRoundedNumber
Arguments
nNumber number to round down
Returns
nDownRoundedNumber the rounded number
Description
The function Floor() determines the biggest integer that is smaller than nNumber.
Examples
? Floor( 1.1 )   // --> 1.0
? Floor( -1.1 )  // --> -2.0
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 math functions
See also

FV()Source code  |  | Improve this doc

Future value of a capital
Syntax
FV( nDeposit, nInterest, nPeriods ) → nFutureValue
Arguments
nDeposit amount of money invested per period nInterest rate of interest per period, 1 == 100% nPeriods period count
Returns
nFutureValue Total value of the capital after nPeriods of
paying nDeposit and nInterest interest being paid every period and added to the capital (resulting in compound interest)
Description

FV() calculates the value of a capital after nPeriods periods. Starting with a value of 0, every period, nDeposit (Dollars, Euros, Yens, ...) and an interest of nInterest for the current capital are added for the capital (nInterest=Percent/100). Thus, one gets the non-linear effects of compound interests: value in period 0 = 0 value in period 1 = ((value in period 0)*(1+nInterest/100)) + nDeposit value in period 2 = ((value in period 1)*(1+nInterest/100)) + nDeposit

etc....

value in period nPeriod = ((value in period nPeriod-1)*(1+nInterest/100))< + nDeposit

= nDeposit * sum from i=0 to nPeriod-1 over (1+nInterest/100)^i = nDeposit * ((1+nInterest/100)^n-1) / (nInterest/100)

Examples
// Payment of 1000 per year for 10 years at a interest rate
// of 5 per cent per year

? FV( 1000, 0.05, 10 )  // --> 12577.893
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 math functions
See also

GetPrec()Source code  |  | Improve this doc

Get precision of math functions
Syntax
GetPrec() → nDigits
Returns
nDigits digit count between 1 and 16
Description
Be aware that calls to this functions do NOT affect the calculation precision of the math functions at the moment.
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 math functions

Log10()Source code  |  | Improve this doc

Decadic logarithm of a number
Syntax
Log10( <nNumber> ) → nLogarithm
Arguments
nNumber number to logarithm
Returns
nLogarithm decadic logarithm of nNumber
Description
The function Log10() calculates the decadic logarithm of nNumber, i.e. 10^nLogarithm == nNumber.
Examples
? Log10( 10.0 )          // --> 1.0
? Log10( Sqrt( 10.0 ) )  // --> 0.5
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 math functions

Payment()Source code  |  | Improve this doc

Payments for a loan
Syntax
Payment( nLoan, nInterest, nPeriods ) → nPayment
Arguments
nLoan amount of money you get from the bank nInterest rate of interest per period, 1 == 100% nPeriods period count
Returns
nPayment Periodical payment one has to make to pay the
loan nLoan back
Description

Payment() calculates the payment one has to make periodically to pay back a loan nLoan within nPeriods periods and for a rate of interest nInterest per period. debt in period 0 = nLoan debt in period 1 = ((debt in period 0)-nPayment)*(1+nInterest/100) debt in period 2 = ((debt in period 1)-nPayment)*(1+nInterest/100)

etc...

debt in period nPeriod = ((debt in period nPeriod-1)-nPayment)*(1+nInterest/100)

-> has to be 0, so

nPayment = nLoan*(nInterest/100)/(1-(1+nInterest/100)^(-n))

Examples
// You get a loan of 5172.56 at a interest rate of 0.5% per
// month (6% per year).
// For 5 years, you have to pay back every month

? Payment( 5172.56, 0.005, 60 ) // --> 100.00
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 math functions
See also

Periods()Source code  |  | Improve this doc

Number of periods for a loan
Syntax
Periods( nLoan, nPayment, nInterest ) → nPeriods
Arguments
nLoan amount of money you get from the bank nPayment amount of money you pay back per period nInterest rate of interest per period, 1 == 100%
Returns
nPeriods number of periods you need to pay the loan back
Description

Periods() calculates the number of periods one needs to pay back a loan of nLoan with periodical payments of nPayment and for a rate of interest nInterest per period. debt in period 0 = nLoan debt in period 1 = ((debt in period 0)-nPayment)*(1+nInterest/100) debt in period 2 = ((debt in period 1)-nPayment)*(1+nInterest/100)

etc...

debt in period nPeriod = ((debt in period nPeriod-1)-nPayment)*(1+nInterest/100)

-> has to be 0, so

nPeriods = -Log(1-nLoan*(nInterest/100)/nPayment)/Log(1+nInterest/100))

Note, however that in the case of nPayment <= nLoan * ( nInterest / 100 ), one would need infinite time to pay the loan back. The functions does then return -1.

Examples
// You get a loan of 5172.56 at a interest rate of 0.5% per
// month (6% per year).
// You can afford to pay 100 back every month, so you need

? Periods( 5172.56, 100, 0.005 ) // --> 60.0

// months to cancel the loan.
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 math functions
See also

Pi()Source code  |  | Improve this doc

Returns Pi, the perimeter-to-diameter-ratio of a circle
Syntax
Pi() → nPi
Returns
nPi the math constant Pi with maximum precision available
Description
The function Pi() can be used if the constant Pi is needed with maximum precision. One of the most known interpretations of this number is the constant perimeter-to-diameter-ratio of circles.
Examples
// the diameter of a circle-like swimming pool is 3.4 meters, how
// long is the perimeter?

? Str( Pi() * 3.4, 5, 3 ) + " meters"  // --> "10.681 meters"
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 math functions
See also

PV()Source code  |  | Improve this doc

Present value of a loan
Syntax
PV( nPayment, nInterest, nPeriods ) → nPresentValue
Arguments
nPayment amount of money paid back per period nInterest rate of interest per period, 1 == 100% nPeriods period count
Returns
nPresentValue Present value of a loan when one is paying back
nDeposit per period at a rate of interest of nInterest per period
Description

PV() calculates the present value of a loan that is paid back in nPeriods payments of nPayment (Dollars, Euros, Yens,...) while the rate of interest is nInterest per period: debt in period 0 = nPresentValue debt in period 1 = ((debt in period 0)-nPayment)*(1+nInterest/100) debt in period 2 = ((debt in period 1)-nPayment)*(1+nInterest/100)

etc...

debt in period nPeriod = ((debt in period nPeriod-1)-nPayment)*(1+nInterest/100)

-> has to be 0, so

nPresentValue = nPayment*(1-(1+nInterest/100)^(-n))/(nInterest/100)

Examples
// You can afford to pay back 100 Dollars per month for 5 years
// at a interest rate of 0.5% per month (6% per year), so instead
// of 6000 Dollars (the amount you will pay back) the bank will pay
// you

? PV( 100, 0.005, 60 ) // --> 5172.56
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 math functions
See also

Rate()Source code  |  | Improve this doc

Estimate rate of interest for a loan
Syntax
Rate( nLoan, nPayment, nPeriods ) → nRate
Arguments
nLoan amount of money you get from the bank nPayment amount of money you pay back per period nPeriods number of periods you pay the loan back
Returns
nInterest estimated rate of interest per period, 1 == 100%
Description

Rate() calculates the rate of interest per period for the given loan, payment per periods and number of periods. This is done with the same equation used in the Payment() or Periods() function:

nPayment = nLoan*(nInterest/100)/(1-(1+nInterest/100)^(-nPeriods))

However, this equation cannot be solved for nInterest in a "closed" manner, i.e. nInterest = ..., so that the result can only be estimated.

Examples
// You get a loan of 5172.56, pay 100 back every month for
// 5 years (60 months). The effective interest rate per
// period (=month) is

? Rate( 5172.56, 100, 60 ) // --> 0.005
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 math functions
See also

RToD()Source code  |  | Improve this doc

Convert radiant to degree
Syntax
RToD( nRadiant ) → nDegree
Arguments
nRadiant the size of an angle in radiant
Returns
nDegree the size of that angle in degree
Description
The function RToD() can be used to convert sizes of angles given in radiant (like those returned by the Asin(), Acos() or Atan() functions) to degrees that are commonly used geometry and mechanics.
Examples
? RToD( Pi() )      // --> 180
? Tanh( Pi() / 3 )  // --> 60
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 math functions
See also

SetPrec()Source code  |  | Improve this doc

Set precision of math functions
Syntax
SetPrec( <nPrecision> ) → cEmptyString
Arguments
nPrecision digit count between 1 and 16, defaults to 16
Returns
cEmptyString this function always returns an empty string
Description
Be aware that calls to this functions do not affect the calculation precision of the math functions at the moment.
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 math functions

Sign()Source code  |  | Improve this doc

Sign of a number
Syntax
Sign( <nNumber> ) → nSign
Arguments
nNumber a number
Returns
nSign sign of nNumber
Description
The function Sign() determines the sign of nNumber. If nNumber is > 0, then Sign(nNumber) returns 1 If nNumber is < 0, then Sign(nNumber) returns -1 If nNumber is == 0, then Sign(nNumber) returns 0
Examples
? Sign( 1.1 )   // --> 1
? Sign( -1.1 )  // --> -1
? Sign( 0.0 )   // --> 0
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 math functions

Sin()Source code  |  | Improve this doc

Sine of the argument
Syntax
Sin( nRadiant ) → nSine
Arguments
nRadiant an angle size given in radiants
Returns
nSine the sine of nRadiant
Description
The function Sin() calculates the sine of an angle whose size is given in radiants (full angle equals 2 * Pi() - see DToR() for angle size given in degrees). A common geometric interpretation of the Sin() function is the counterkathede-hypotenuse-ratio of a right-angled triangle.
Examples
? Sin( 0.0 )  // --> 0.0
? Sin( 1.0 )  // --> 0.8414...
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 math functions
See also

Sinh()Source code  |  | Improve this doc

Hyperbolic Sine of the argument
Syntax
Sinh( nArea ) → nHyperbolicSine
Arguments
nArea the size of the area (see below)
Returns
nHyperbolicSine the hyperbolic sine of nArea
Description
The function Sinh() calculates the hyperbolic sine of the argument. In analytical mathematics it is defined as 1 / 2 * ( Exp( nArea ) - Exp( -nArea ) ). A common geometric interpretation of the Sinh() function is the maximum y value of the points in the area with the given size nArea, that is bound by the x axis, a straight line through the point of origin (this one is fixed by the area) and the hyperbola x ^ 2 - y ^ 2 = 1.
Examples
? Sinh( 0.0 )  // --> 0.0
? Sinh( 1.0 )  // --> 1.1752...
Status
Ready
Compliance
Harbour specific
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 math functions
See also

Tan()Source code  |  | Improve this doc

Tangent of the argument
Syntax
Tan( nRadiant ) → nTangent
Arguments
nRadiant an angle size given in radiants
Returns
nTangent the tangent of nRadiant
Description
The function Tan() calculates the tangent of an angle whose size is given in radiants (full angle equals 2 * Pi() - see DToR() for angle size given in degrees). A common geometric interpretation of the Tan() function is the counterkathede-ankathede-ratio of a right-angled triangle, or, Tan( x ) = Sin( x ) / Cos( x ).
Examples
? Tan( 0.0 )  // --> 0.0
? Tan( 1.0 )  // --> 1.5574...
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 math functions
See also

Tanh()Source code  |  | Improve this doc

Hyperbolic Tangent of the argument
Syntax
Tanh( nArea ) → nHyperbolicTangent
Arguments
nArea the size of the area (see below)
Returns
nHyperbolicTangent the hyperbolic tangent of nArea
Description
The function Tanh() calculates the hyperbolic tangent of the argument. In analytical mathematics it is defined as Sinh( x ) / Cosh( x ).
Examples
? Tanh( 0.0 )  // --> 0.0
? Tanh( 1.0 )  // --> 0.7615...
Status
Ready
Compliance
Harbour specific
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 math functions
See also

XToC()Source code  |  | Improve this doc

Syntax
XToC( <expValue> ) → cValue
Arguments
expValue Designate an expression of some of the following data type: NUMBER, CHARACTER, DATE, LOGICAL.
Returns
XToC() return a string with the representation of data type of expValue.
Description

Each data type always returns a string with a particular fixed length:

 Data Type    Result Length      Similar function
 Numeric      sizeof( DOUBLE )   FToC()
 Logical      1
 Date         8                  DToS()
 String       Unchanged

TODO: add documentation

Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 miscellaneous functions
See also

BitToC()Source code  |  | Improve this doc

Syntax
BitToC( <nInteger>, <cBitPattern>[, <lMode>] ) → cBitString
Description
TODO: add documentation
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 number and bit manipulation functions
See also

CToBit()Source code  |  | Improve this doc

Syntax
CToBit( <cBitString>, <cBitPattern> ) → nWord
Description
TODO: add documentation
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 number and bit manipulation functions
See also

CToF()Source code  |  | Improve this doc

Syntax
CToF( <cFloatingPointNumber> ) → nFloatingPointNumber
Arguments
cFloatingPointNumber Designate a string that contains a Harbour number in floating point format. ATTENTION: different implementations or platforms of Harbour, they could produce different format in the string returned by FToC().
Returns
CToF() return the floating point number that corresponds to the string passed.
Description

Character strings created with FToC() or XToC() are convert into Harbour floating point number

TODO: add documentation

Status
Ready
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 number and bit manipulation functions
See also

CToN()Source code  |  | Improve this doc

Syntax
CToN( <xNumber>[, <nBase>][, <lMode>] ) → nNumber
Description
TODO: add documentation
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 number and bit manipulation functions
See also

Exponent()Source code  |  | Improve this doc

Evaluate the exponent of a floating point number
Syntax
Exponent( <nFloatingPointNumber> ) → nExponent
Arguments
nFloatingPointNumber Designate any Harbour number.
Returns
Exponent() returns the exponent of the nFloatingPointNumber number in base 2.
Description

This function supplements Mantissa() to return the exponent of the nFloatingPointNumber number.

Values > 1 or values < -1 return a positive number 0 to 1023.

Values < 1 or values > -1 return a negative number -1 to -1023.

The Exponent( 0 ), return 0.

The following calculation reproduces the original value:

? 2 ^ Exponent( <nFloatingPointNumber> ) * Mantissa( <nFloatingPointNumber> )  // -> <nFloatingPointNumber>

TODO: add documentation

Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 number and bit manipulation functions
See also

FToC()Source code  |  | Improve this doc

Syntax
FToC( <nFloatingPointNumber> ) → cFloatingPointNumber
Arguments
nFloatingPointNumber Designate any Harbour number.
Returns
FToC() return a string with the size of DOUBLE. ATTENTION: different implementations or platforms of Harbour, they could produce different format in the string returned by FToC().
Description

Harbour internal numbers in Floating Point are stored in data type DOUBLE. FToC() returns these bits as an string. In this way, numbers con be saved more compactly.

TODO: add documentation

Status
Ready
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 number and bit manipulation functions
See also

Mantissa()Source code  |  | Improve this doc

Evaluate the mantissa of a floating point number
Syntax
Mantissa( <nFloatingPointNumber> ) → nMantissa
Arguments
nFloatingPointNumber Designate any Harbour number.
Returns
Mantissa() returns the mantissa of the nFloatingPointNumber number.
Description

This function supplements Exponent() to return the mantissa of the nFloatingPointNumber number.

Note: The mantissa value can be 0 or in the range of 1 to 2.

The following calculation reproduces the original value:

? Mantissa( <nFloatingPointNumber> ) * 2 ^ Exponent( <nFloatingPointNumber> )  // -> <nFloatingPointNumber>

TODO: add documentation

Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 number and bit manipulation functions
See also

NToC()Source code  |  | Improve this doc

Syntax
NToC( <xNumber>[, <nBase>][, <nLength>][, <cPadChar>] ) → cNumber
Description
TODO: add documentation
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 number and bit manipulation functions
See also

Celsius()Source code  |  | Improve this doc

Temperature conversion Fahrenheit to Celsius
Syntax
Celsius( nDegreeFahrenheit ) → nDegreeCelsius
Arguments
nDegreeFahrenheit temperature in degree Fahrenheit
Returns
nDegreeCelsius temperate in degree Celsius
Description
Celsius() converts temperature values measured in the Fahrenheit scale to the Celsius scale.
Examples
// melting point of water in standard conditions
? Celsius( 32.0 )      // --> 0.0
// boiling point of water in standard conditions
? Celsius( 212.0 )     // --> 100.0
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 numeric functions
See also

Fahrenheit()Source code  |  | Improve this doc

Temperature conversion Celsius to Fahrenheit
Syntax
Fahrenheit( nDegreeCelsius ) → nDegreeFahrenheit
Arguments
nDegreeCelsius temperate in degree Celsius
Returns
nDegreeFahrenheit temperature in degree Fahrenheit
Description
Fahrenheit() converts temperature values measured in the Celsius scale to the Fahrenheit scale.
Examples
// melting point of water in standard conditions
? Fahrenheit( 0.0 )    // --> 32.0
// boiling point of water in standard conditions
? Fahrenheit( 100.0 )  // --> 212.0
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 numeric functions
See also

Infinity()Source code  |  | Improve this doc

Returns the largest floating point number available in the system
Syntax
Infinity( [<lPlatformIndependant>] ) → nLargestNumber
Arguments
[lPlatformIndependant] .T., if the function should return
the maximum floating point value available (DBL_MAX) .F., function should try to return the same value as the original CT3 lib did Default: .F.
Returns
nLargestNumber the largest floating point number available in the system
Description
Infinity() returns the largest floating point number available in the system. For platform independence, this is set to DBL_MAX.
Status
Ready
Compliance
Infinity() must not necessarily return the same number as CT3's Infinity().
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 numeric functions

PrintReady()Source code  |  | Improve this doc

Syntax
PrintReady( [<nPrinter>] ) → lPrinterReady
Description
TODO: add documentation
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on MS-DOS
File
Library is hbct.
Tag
CT3 printer functions

PrintStat()Source code  |  | Improve this doc

Syntax
PrintStat( [<nPrinter>] ) → nState
Description
TODO: add documentation
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on MS-DOS
File
Library is hbct.
Tag
CT3 printer functions

AddAscii()Source code  |  | Improve this doc

Add an integer value to an ASCII value of a string
Syntax
AddAscii( <[@]cString>, <nValue>, [<nPosition>], [<lCarryOver>] ) → cString
Arguments
[@]cString is the string that should be edited nValue is a integer value that should be added to the
ASCII value of the character at the nPositionth position
[nPosition] is the position of the character that should be edited.
If not supplied, the last character of [@]cString is edited.
[lCarryOver] NEW: is set to .T. if the substring from position 1 to
position nPosition should be treated as an integer written to the base 256. Thus, the addition of nValue can affect to whole substring (see EXAMPLES). Default is .F., the original behaviour of this function.
Returns
The edited string is returned. The return value can be suppressed by using the CSetRef() function. The string must then be passed by reference [@].
Description
AddAscii() can be used to add or subtract integer values from ASCII values in a string. The new lCarryOver parameter allows to treat a string as an integer written to the base 256. Since nValue is limited to a signed long, only substrings 4 characters long can be affected by one AddAscii() call. If the length of [@]cString is smaller than nPosition, the string remains unchanged. The same happens, if uninterpretable parameters are passed to this function.
Examples
// Add 32 to the ASCII value of the character at the last position
// in the string

? AddAscii( "SmitH", 32 )  // --> "Smith"
Status
Ready
Compliance
AddAscii() is compatible with CT3's AddAscii(). A new, 4th, parameter has been added who defaults to the original behaviour if omitted.
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

AfterAtNum()Source code  |  | Improve this doc

Returns string portion after nth occurrence of substring
Syntax
AfterAtNum( <cStringToMatch>, <cString>, [<nCounter>],
            [<nIgnore>] ) → cRestString
Arguments
cStringToMatch is the substring scanned for cString is the scanned string [nCounter] determines how many occurrences are of
cStringToMatch in cString are searched Default: search last occurrence
[nIgnore] determines how many character from the start
should be ignored in the search Default: 0
Returns
cRestString the portion of cString after the nCounterth
occurrence of cStringToMatch in cString If such a rest does not exist, an empty string is returned.
Description
This function scans cString for cStringToMatch. After the nCounterth match (or the last one, depending on the value of nCounter) has been found, the portion of cString after that match will be returned. If there aren't enough matches or the last match is identical to the end of cString, an empty string will be returned. After a match has been found, the function continues to scan after that match if the CSetAtMupa() switch is turned off, with the second character of the matched substring otherwise. The function will also consider the settings of SetAtLike().
Examples
? AfterAtNum( "!", "What is the answer ? 4 ! 5 !" )  // -> ""
? AfterAtNum( "!", "What is the answer ? 4 ! 5 ?" )  // -> " 5 ?"
// TODO: add some examples here with CSetAtMupa() and SetAtLike()
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

AsciiSum()Source code  |  | Improve this doc

calculate the sum of the ASCII values of the characters in a string
Syntax
AsciiSum( <cString> ) → nAsciiSum
Arguments
cString the string to be processed
Returns
nAsciiSum sum of the ASCII values in cString
Description
The AsciiSum() function sums up the ASCII values of the characters in cString. Be aware that the function is not position sensitive, i.e. a change of position of a certain character in the string does not change the ASCII sum.
Examples
? AsciiSum( "ABC" )  // -->  197
? AsciiSum( "ACB" )  // -->  197
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

AscPos()Source code  |  | Improve this doc

ASCII value of a character at a certain position
Syntax
AscPos( <cString>, [<nPosition>] ) → nAsciiValue
Arguments
cString is the processed string [nPosition] is an optional position within cString
Default: last position in cString
Returns
nAsciiValue the ASCII value of the character at the specified
position
Description
The AscPos() function returns the ASCII value of the character that can be found at the position nPosition in cString. If nPosition is larger than the length of cString, 0 is returned.
Examples
? AscPos( "0123456789" )     // --> 57
? AscPos( "0123456789", 1 )  // --> 48
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

AtAdjust()Source code  |  | Improve this doc

Adjusts a sequence within a string to a specified position
Syntax
AtAdjust( <cStringToMatch>, <cString>, <nAdjustPosition>,
          [<nCounter>], [<nIgnore>],
          [<nFillChar|cFillChar>] ) → cString
Arguments
cStringToMatch is the sequence to be adjusted within cString cString is the string that contains cStringToMatch nAdjustPosition specifies the position to that cStringToMatch
will be adjusted
[nCounter] specifies which occurrence of cStringToMatch
in cString is to be adjusted Default: last occurrence
[nIgnore] specifies how many characters should be omitted
in the scan
[nFillChar|cFillChar] specifies the character that is used for the
adjustment
Returns
cString the changed string
Description
TODO: add a description, some examples and tests here
Status
Ready
Compliance
AtAdjust() works like CT3's AtAdjust()
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

AtNum()Source code  |  | Improve this doc

Returns the start position of the nth occurrence of a substring in a string
Syntax
AtNum( <cStringToMatch>, <cString>, [<nCounter>],
       [<nIgnore>] ) → nPosition
Arguments
cStringToMatch is the substring scanned for cString is the scanned string [nCounter] determines how many occurrences are of
cStringToMatch in cString are searched Default: search last occurrence
[nIgnore] determines how many character from the start
should be ignored in the search Default: 0
Returns
nPosition the position of the nCounterth
occurrence of cStringToMatch in cString. If such an occurrence does not exist, 0 is returned.
Description
This function scans cString for cStringToMatch. After the nCounterth match (or the last one, depending on the value of nCounter) has been found, the position of that match will be returned. If there aren't enough matches or there is no last match, 0 will be returned. After a match has been found, the function continues to scan after that match if the CSetAtMupa() switch is turned off, with the second character of the matched substring otherwise. The function will also consider the settings of SetAtLike().
Examples
? AtNum( "!", "What is the answer ? 4 ! 5 !" ) // -> 28
? AtNum( "!", "What is the answer ? 4 ! 5 ?" ) // -> 24
<TODO: add some examples here with CSetAtMupa() and SetAtLike()>
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

AtRepl()Source code  |  | Improve this doc

Search and replace sequences in a string
Syntax
AtRepl( <cStringToMatch>, <cString>, <cReplacement>, [<nCounter>],
        [<lMode>], [<nIgnore>] ) → cString
Arguments
cStringToMatch is the substring searched for in cString cString is the processed string cReplacement is the replacement for sequences found [nCounter] specifies the number of replacements
Default: last occurrence
[lMode] if set to .T., only the nCounterth sequence
of cStringToMatch will be replaced, else all sequences will be replaced. Default: .F.
[nIgnore]) specifies how many characters in cString from
the beginning should be ignored by the function Default: 0
Returns
cString
Description
The AtRepl() function searches and replaces sequences in a string. First, the function ignores the first nIgnore characters of cString. Then, if lMode is set to .T., it searches for the nCounterth occurrence of cStringToMatch in cString. If successful, the sequence will be replaced with cReplacement. If lMode is set to .F., the same search is performed, but EVERY occurrence of cStringToMatch till the nCounterth (inclusive) will be replaced with cReplacement. Note that, in this case, the replacements are performed even if the nCounterth occurrence does not exist. By using the CSetAtMupa() switch you can decide whether the function restarts searching after a found sequence of after the first character of that sequence. The function allows the use of wildcards in cStringToMatch and looks for the settings of SetAtLike().
Examples
? AtRepl( "ABC", "ABCDABCDABC", "xx" )          // --> "xxDxxDxx"
? AtRepl( "ABC", "ABCDABC", "ZYXW" )            // --> "ZYXWDZYXW"
? AtRepl( "ABC", "ABCDABCDABC", "xx", 2 )       // --> "xxDxxDABC"
? AtRepl( "ABC", "ABCDABCDABC", "xx", 2, .T. )  // --> "ABCDxxDABC"
Status
Ready
Compliance
AtRepl() is compatible with CT3's AtRepl(). Note the new, 6th parameter !
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

AtToken()Source code  |  | Improve this doc

Position of a token in a string
Syntax
AtToken( <cString>, [<cTokenizer>],
         [<nTokenCount>], [<nSkipWidth>] ) → nPosition
Arguments
cString is the processed string [cTokenizer] is a list of characters separating the tokens
in cString Default: Chr( 0 ) + Chr( 9 ) + Chr( 10 ) + Chr( 13 ) + Chr( 26 ) + hb_BChar( 138 ) + hb_BChar( 141 ) + Chr( 32 ) + ",.;:!\?/\\<>()#&%+-*"
[nTokenCount] specifies the count of the token whose
position should be calculated Default: last token
[nSkipWidth] specifies the maximum number of successive
tokenizing characters that are combined as one token stop, e.g. specifying 1 can yield to empty tokens Default: 0, any number of successive tokenizing characters are combined as one token stop
Returns
nPosition The start position of the specified token or
0 if such a token does not exist in cString.
Description
The AtToken() function calculates the start position of the nTokenCountth token in cString. By setting the new nSkipWidth parameter to a value different than 0, you can specify how many tokenizing characters are combined at most to one token stop. Be aware that this can result to empty tokens there the start position is not defined clearly. Then, AtToken() returns the position there the token would start if its length is larger than 0. To check for empty tokens, simply look if the character at the returned position is within the tokenizer list.
Examples
AtToken( "Hello, World!" )  // --> 8 (empty strings after tokenizer are not a token !)
Status
Ready
Compliance
AtToken() is compatible with CT3's AtToken(), but has an additional 4th parameter to let you specify a skip width equal to that in the Token() function.
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

BeforAtNum()Source code  |  | Improve this doc

Returns string portion before nth occurrence of substring
Syntax
BeforAtNum( <cStringToMatch>, <cString>, [<nCounter>],
            [<nIgnore>] ) → cRestString
Arguments
cStringToMatch is the substring scanned for cString is the scanned string [nCounter] determines how many occurrences are of
cStringToMatch in cString are searched Default: search last occurrence
[nIgnore] determines how many character from the start
should be ignored in the search Default: 0
Returns
cRestString the portion of cString before the nCounterth
occurrence of cStringToMatch in cString If such a string does not exist, an empty string is returned.
Description
This function scans cString for cStringToMatch. After the nCounterth match (or the last one, depending on the value of nCounter) has been found, the portion of cString before that match will be returned. If there aren't enough matches or the last match is identical to the start of cString (i.e. the last match is the first match), an empty string will be returned. After a match has been found, the function continues to scan after that match if the CSetAtMupa() switch is turned off, with the second character of the matched substring otherwise. The function will also consider the settings of SetAtLike().
Examples
? BeforAtNum( "!", "What is the answer ? 4 ! 5 !" ) // -> "What is the answer ? 4 ! 5 "
? BeforAtNum( "!", "What is the answer ? 4 ! 5 ?" ) // -> "What is the answer ? 4 "
<TODO: add some examples here with CSetAtMupa() and SetAtLike()>
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

CharAdd()Source code  |  | Improve this doc

Adds corresponding ASCII value of two strings
Syntax
CharAdd( <[@]cString1>, <cString2> ) → cAddString
Arguments
[@]cString1 first string cString2 second string
Returns
cAddString string with added ASCII values
Description
The CharAdd() function constructs a new string from the two strings passed as parameters. To do this, it adds the ASCII values of the corresponding characters of both strings and places a character in the resulting string whose ASCII value equals to that sum (modulo 256). If the first string is passed by reference, the resulting string is stored in cString1, too. By setting the CSetRef()-switch to .T., the return value can be omitted. If cString2 is shorter than cString1 and the last character of cString2 has been processed, the function restarts with the first character of cString2.
Examples
? CharAdd( "012345678", hb_BChar( 1 ) )    // --> "123456789"
? CharAdd( "123456789", hb_BChar( 255 ) )  // --> "012345678"
? CharAdd( "0000", hb_BChar( 0 ) + hb_BChar( 1 ) + hb_BChar( 2 ) + hb_BChar( 3 ) )  // --> "0123"
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

CharAnd()Source code  |  | Improve this doc

Combine corresponding ASCII value of two strings with bitwise AND
Syntax
CharAnd( <[@]cString1>, <cString2> ) → cAndString
Arguments
[@]cString1 first string cString2 second string
Returns
cAndString string with bitwise AND combined ASCII values
Description
The CharAnd() function constructs a new string from the two strings passed as parameters. To do this, it combines the ASCII values of the corresponding characters of both strings with a bitwise AND-operation and places a character in the resulting string whose ASCII value equals to the result of that operation. If the first string is passed by reference, the resulting string is stored in cString1, too. By setting the CSetRef()-switch to .T., the return value can be omitted. If cString2 is shorter than cString1 and the last character of cString2 has been processed, the function restarts with the first character of cString2.
Examples
// clear the LSB
? CharAnd( "012345678", hb_BChar( 254 ) ) // --> "002244668"
? CharAnd( "012345678", hb_BChar( 254 ) + hb_BChar( 252 ) ) // --> "002044648"
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

CharEven()Source code  |  | Improve this doc

Returns the characters on the even positions in a string
Syntax
CharEven( <cString> ) → cEvenString
Arguments
cString processed string
Returns
cEvenString a string containing all character from even positions
in cString
Description
The CharEven() function looks for the characters on the even positions in a given string, collects them and returns them as a string.
Examples
? CharEven( " H E L L O !" )  // -> "HELLO!"
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

CharHist()Source code  |  | Improve this doc

Generates a character histogram of a string
Syntax
CharHist( [<cString>] ) → aCharacterCount
Arguments
[cString] is the string for whom the function generates a
character histogram Default: "" (empty string)
Returns
aCharacterCount an array with 256 elements where the nth element
contains the count of character #(n-1) in cString
Description
The CharHist() function generates a character histogram of those characters that are contained in cString. This histogram is stored in an 256-element array where the nth element contains the count of ASCII character #(n-1) in cString.
Examples
? CharHist( "Hello World !" )[ 109 ] // --> 3  // Chr( 108 ) == "l"
Status
Ready
Compliance
CharHist() is only available in Harbour's CT3 library.
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

CharList()Source code  |  | Improve this doc

Generates a list of all characters in a string
Syntax
CharList( [<cString>] ) → cCharacterList
Arguments
[cString] is the string for whom the function generates a list
of all characters Default: "" (empty string)
Returns
cCharacterList a list of the characters in cString
Description
The CharList() function generates a list of those characters that are contained in cString. This list can contain each character only once, so that its maximum length is 256. The list lists those characters first that are occurring in cString first.
Examples
? CharList( "Hello World !" )  // --> "Helo Wrd!"
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

CharMirr()Source code  |  | Improve this doc

Mirror a string
Syntax
CharMirr( <[@]cString>, [<lDontMirrorSpaces>] ) → cMirroredString
Arguments
[@]cString is the string that should be mirrored [lDontMirrorSpaces] if set to .T., spaces at the end of
cString will not be mirrored but kept at the end Default: .F., mirror the whole string
Returns
cMirroredString the mirrored string
Description
The CharMirr() function mirrors a string, i.e. the first character will be put at the end, the second at the last but one position etc.. One can use this function for index searches, but then, the spaces at the end of the string should not be mirrored. One can omit the return value of the function by setting the CSetRef() switch to .T., but cString must then be passed by reference to get a result.
Examples
? CharMirr( "racecar" )         // "racecar"
? CharMirr( "racecar  ", .T. )  // "racecar  "
? CharMirr( "racecar  ", .F. )  // "  racecar"
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

CharMix()Source code  |  | Improve this doc

Mix two strings
Syntax
CharMix( <cString1>[, <cString2>] ) → cMixedString
Arguments
cString1 String that will be mixed with the characters from cString2 [cString2] String whose characters will be mixed with the one from
cString1. Default: " " (string with one space char)
Returns
cMixedString Mixed string
Description
The CharMix() function mixes the strings cString1 and cString2. To do this it takes one character after the other alternatively from cString1 and cString2 and puts them in the output string. This procedure is stopped when the end of cString1 is reached. If cString2 is shorter than cString1, the function will start at the begin of cString2 again. If on the other hand cString2 is longer than cString1, the surplus characters will be omitted.
Examples
? CharMix( "ABC", "123" )   // "A1B2C3"
? CharMix( "ABCDE", "12" )  // "A1B2C1D2E1"
? CharMix( "AB", "12345" )  // "A1B2"
? CharMix( "HELLO", " " )   // "H E L L O "
? CharMix( "HELLO", "" )    // "HELLO"
Status
Ready
Compliance
CharMix() is compatible with CT3's CharMix(). NOTE: CA-Tools version of CharMix() will hang
if the second parameter is an empty string, this version will not.
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

CharNoList()Source code  |  | Improve this doc

Generates a list of all characters not contained in a string
Syntax
CharNoList( [<cString>] ) → cCharacterList
Arguments
[cString] is the string for whom the function generates a list
of all characters not contained in that string Default: "" (empty string)
Returns
cCharacterList a list of the characters that are not contained in cString
Description
The CharNoList() function generates a list of those characters that are not contained in cString. This list can contain each character only once, so that its maximum length is 256. The list is alphabetically sorted.
Examples
? CharNoList( CharNoList( "Hello World !" ) ) // --> " !HWdelor"
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

CharNot()Source code  |  | Improve this doc

Process each character in a string with bitwise NOT operation
Syntax
CharNot( <[@]cString> ) → cNotString
Arguments
[@]cString string to be processed
Returns
cNotString string with bitwise negated characters
Description
The CharNot() function constructs a new string from the string passed as parameter. To do this, it performs a bitwise NOT operation to the characters of the string and places a character in the resulting string whose ASCII value equals to the result of that operation. It can be easily seen that the resulting ASCII-value equals 255 minus input ASCII value. If the string is passed by reference, the resulting string is stored in cString, too. By setting the CSetRef()-switch to .T., the return value can be omitted.
Examples
? CharNot( hb_BChar(  85 ) + hb_BChar( 128 ) + hb_BChar( 170 ) + hb_BChar(   1 ) )
// -->     hb_BChar( 170 ) + hb_BChar( 127 ) + hb_BChar(  85 ) + hb_BChar( 254 )
? CharNot( CharNot( "This is a test!" ) ) // --> "This is a test!"
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

CharOdd()Source code  |  | Improve this doc

Returns the characters on the odd positions in a string
Syntax
CharOdd( <cString> ) → cOddString
Arguments
cString processed string
Returns
cOddString a string containing all character from odd positions
in cString
Description
The CharOdd() function looks for the characters on the odd positions in a given string, collects them and returns them as a string.
Examples
? CharOdd( "H E L L O ! " ) // -> "HELLO!"
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

CharOne()Source code  |  | Improve this doc

Reduce multiple occurrences of a character to one
Syntax
CharOne( [<cCharactersToReduce>,] <cString> ) → cReducedString
Arguments
[cCharactersToReduce] specifies the characters the multiple
occurrences of which should be reduced to one Default: All characters.
cString specifies the processed string
Returns
cReducedString the string with the reduced occurrences
Description
The CharOne() function reduces multiple occurrences of characters in cString to a single one. It is important to note that the multiple occurrences must occur directly one behind the other. This behaviour is is in contrast to the CharList() function.
Examples
? CharOne( "122333a123" )       // "123a123"
? CharOne( "A  B  CCCD" )       // "A B CD"
? CharOne( " ", "A  B  A  B" )  // "A B A B"
? CharOne( "o", "122oooB12o" )  // "122oB12o"
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

CharOnly()Source code  |  | Improve this doc

Intersectional set of two strings based on characters
Syntax
CharOnly( <cThisCharactersOnly>, <cString> ) → cReducedString
Arguments
cThisCharactersOnly specifies the characters that must not be
deleted in cString.
cString is the string that should be processed
Returns
cReducedString A string with all characters deleted but those
specified in cThisCharactersOnly.
Description
The CharOnly() function calculates the intersectional set of two strings. To do this, it deletes all characters from cString that do not appear in cThisCharacterOnly.
Examples
? CharOnly( "0123456789", "0211 - 38 99 77" )  // "0211389977"
? CharOnly( "0123456789", "0211/ 389 977" )    // "0211389977"
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

CharOr()Source code  |  | Improve this doc

Combine corresponding ASCII value of two strings with bitwise OR
Syntax
CharOr( <[@]cString1>, <cString2> ) → cOrString
Arguments
[@]cString1 first string cString2 second string
Returns
cOrString string with bitwise OR combined ASCII values
Description
The CharOr() function constructs a new string from the two strings passed as parameters. To do this, it combines the ASCII values of the corresponding characters of both strings with a bitwise OR-operation and places a character in the resulting string whose ASCII value equals to the result of that operation. If the first string is passed by reference, the resulting string is stored in cString1, too. By setting the CSetRef()-switch to .T., the return value can be omitted. If cString2 is shorter than cString1 and the last character of cString2 has been processed, the function restarts with the first character of cString2.
Examples
// set the LSB
? CharOr( "012345678", hb_BChar( 1 ) ) // --> "113355779"
? CharOr( "012345678", hb_BChar( 1 ) + hb_BChar( 3 ) ) // --> "133357779"
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

CharRelA()Source code  |  | Improve this doc

Character relation of two strings
Syntax
CharRelA( <cStringToMatch1>, <cString1>,
          <cStringToMatch2>, <cString2> ) → nPosition
Description
TODO: add documentation
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

CharRelRep()Source code  |  | Improve this doc

Relation dependent character replacement
Syntax
CharRelRep( <cStringToMatch1>, <cString1>,
            <cStringToMatch2>, <[@]cString2>,
            <cReplacement> ) → cString
Description
TODO: add documentation
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

CharRem()Source code  |  | Improve this doc

Removes characters from a string
Syntax
CharRem( <cDeleteThisCharacters>, <cString> ) → cReducedString
Arguments
cDeleteThisCharacters specifies the characters that should
be deleted in cString
cString) is the string that should be processed
Returns
cReducedString is a string where the characters specified
in cDeleteThisCharacters are deleted
Description
The CharRem() function deletes the characters specified in cDeleteThisCharacters from cString.
Examples
? CharRem( " ", " 1  2  " )   // "12"
? CharRem( "3y", "xyz123" )   // "xz12"
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

CharRepl()Source code  |  | Improve this doc

Replacement of characters
Syntax
CharRepl( <cSearchString>, <[@]cString>,
          <cReplaceString>, [<lMode>] ) → cString
Arguments
cSearchString is a string of characters that should be replaced [@]cString is the processed string cReplaceString is a string of characters that replace the one
of cSearchString
[lMode] sets the replacement method (see description)
Default: .F.
Returns
cString the processed string
Description
The CharRepl() function replaces certain characters in cString with others depending on the setting of lMode. If lMode is set to .F., the function takes the characters of cSearchString one after the other, searches for them in cString and, if successful, replaces them with the corresponding character of cReplaceString. Be aware that if the same characters occur in both cSearchString and cReplaceString, the character on a certain position in cString can be replaced multiple times. if lMode is set to .T., the function takes the characters in cString one after the other, searches for them in cSearchString and, if successful, replaces them with the corresponding character of cReplaceString. Note that no multiple replacements are possible in this mode. If cReplaceString is shorter than cSearchString, the last character of cReplaceString is used as corresponding character for the the "rest" of cSearchString. One can omit the return value by setting the CSetRef() switch to .T., but then one must pass cString by reference to get the result.
Examples
? CharRepl( "1234", "1x2y3z", "abcd" )             // "axbycz"
? CharRepl( "abcdefghij", "jhfdb", "1234567890" )  // "08642"
? CharRepl( "abcdefghij", "jhfdb", "12345" )       // "55542"
? CharRepl( "1234", "1234", "234A" )               // "AAAA"
? CharRepl( "1234", "1234", "234A", .T. )          // "234A"
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

CharRll()Source code  |  | Improve this doc

Process each character in a string with bitwise ROLL LEFT operation
Syntax
CharRll( <[@]cString>, <nBitsToRLL> ) → cRLLString
Arguments
[@]cString string to be processed nBitsToRLL number of bit positions to be rolled to the left
Returns
cRLLString string with bitwise rolled left characters
Description
The CharRll() function constructs a new string from the string passed as parameter. To do this, it performs a bitwise ROLL LEFT (RLL) operation to the characters of the string and places a character in the resulting string whose ASCII value equals to the result of that operation. Be aware that, in contrast to CharShl(), bits rolled out on the left are put in again on the right. If the string is passed by reference, the resulting string is stored in cString, too. By setting the CSetRef()-switch to .T., the return value can be omitted.
Examples
? CharRll( hb_BChar(   1 ) + hb_BChar(  2 ) + hb_BChar(  4 ) + hb_BChar(   8 ) + ;
           hb_BChar(  16 ) + hb_BChar( 32 ) + hb_BChar( 64 ) + hb_BChar( 128 ), 3 )
// -->     hb_BChar(   8 ) + hb_BChar( 16 ) + hb_BChar( 32 ) + hb_BChar(  64 ) + ;
//         hb_BChar( 128 ) + hb_BChar(  1 ) + hb_BChar(  2 ) + hb_BChar(   4 )
Status
Ready
Compliance
CharRll() is a new function that is only available in Harbour's CT3 lib.
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

CharRlr()Source code  |  | Improve this doc

Process each character in a string with bitwise ROLL RIGHT operation
Syntax
CharRlr( <[@]cString>, <nBitsToRLR> ) → cRLRString
Arguments
[@]cString string to be processed nBitsToRLR number of bit positions to be rolled to the right
Returns
cRLRString string with bitwise rolled right characters
Description
The CharRlr() function constructs a new string from the string passed as parameter. To do this, it performs a bitwise ROLL RIGHT (RLR) operation to the characters of the string and places a character in the resulting string whose ASCII value equals to the result of that operation. Be aware that, in contrast to CharShr(), bits rolled out on the right are put in again on the left. If the string is passed by reference, the resulting string is stored in cString, too. By setting the CSetRef()-switch to .T., the return value can be omitted.
Examples
? CharRlr( hb_BChar(  1 ) + hb_BChar(  2 ) + hb_BChar(   4 ) + hb_BChar(   8 ) + ;
           hb_BChar( 16 ) + hb_BChar( 32 ) + hb_BChar(  64 ) + hb_BChar( 128 ), 3 )
// -->     hb_BChar( 32 ) + hb_BChar( 64 ) + hb_BChar( 128 ) + hb_BChar(   1 ) + ;
//         hb_BChar(  2 ) + hb_BChar(  4 ) + hb_BChar(   8 ) + hb_BChar(  16 )
Status
Ready
Compliance
CharRlr() is a new function that is only available in Harbour's CT3 lib.
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

CharShl()Source code  |  | Improve this doc

Process each character in a string with bitwise SHIFT LEFT operation
Syntax
CharShl( <[@]cString>, <nBitsToSHL> ) → cSHLString
Arguments
[@]cString string to be processed nBitsToSHL number of bit positions to be shifted to the left
Returns
cSHLString string with bitwise shifted left characters
Description
The CharShl() function constructs a new string from the string passed as parameter. To do this, it performs a bitwise SHIFT LEFT (SHL) operation to the characters of the string and places a character in the resulting string whose ASCII value equals to the result of that operation. Be aware that bits shifted out of the byte are lost. If you need a bit rotation, use the CharRll() function instead. If the string is passed by reference, the resulting string is stored in cString, too. By setting the CSetRef()-switch to .T., the return value can be omitted.
Examples
? CharShl( hb_BChar(   1 ) + hb_BChar(  2 ) + hb_BChar(  4 ) + hb_BChar(   8 ) + ;
           hb_BChar(  16 ) + hb_BChar( 32 ) + hb_BChar( 64 ) + hb_BChar( 128 ), 3 )
// -->     hb_BChar(   8 ) + hb_BChar( 16 ) + hb_BChar( 32 ) + hb_BChar(  64 ) + ;
//         hb_BChar( 128 ) + hb_BChar(  0 ) + hb_BChar(  0 ) + hb_BChar(   0 )
Status
Ready
Compliance
CharShl() is a new function that is only available in Harbour's CT3 lib.
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

CharShr()Source code  |  | Improve this doc

Process each character in a string with bitwise SHIFT RIGHT operation
Syntax
CharShr( <[@]cString>, <nBitsToSHR> ) → cSHRString
Arguments
[@]cString string to be processed nBitsToSHR number of bit positions to be shifted to the right
Returns
cSHRString string with bitwise shifted right characters
Description
The CharShr() function constructs a new string from the string passed as parameter. To do this, it performs a bitwise SHIFT RIGHT (SHR) operation to the characters of the string and places a character in the resulting string whose ASCII value equals to the result of that operation. Be aware that bits shifted out of the byte are lost. If you need a bit rotation, use the CharRlr() function instead. If the string is passed by reference, the resulting string is stored in cString, too. By setting the CSetRef()-switch to .T., the return value can be omitted.
Examples
? CharShr( hb_BChar(  1 ) + hb_BChar(  2 ) + hb_BChar(  4 ) + hb_BChar(   8 ) + ;
           hb_BChar( 16 ) + hb_BChar( 32 ) + hb_BChar( 64 ) + hb_BChar( 128 ), 3 )
// -->     hb_BChar(  0 ) + hb_BChar(  0 ) + hb_BChar(  0 ) + hb_BChar(   1 ) + ;
//         hb_BChar(  2 ) + hb_BChar(  4 ) + hb_BChar(  8 ) + hb_BChar(  16 )
Status
Ready
Compliance
CharShr() is a new function that is only available in Harbour's CT3 lib.
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

CharSList()Source code  |  | Improve this doc

Generates a sorted list of all characters in a string
Syntax
CharSList( [<cString>] ) → cSortedCharacterList
Arguments
[cString] is the string for whom the function generates a
sorted list of all characters Default: "" (empty string)
Returns
cSortedCharacterList a sorted list of the characters in cString
Description
The CharList() function generates a sorted list of those characters that are contained in cString. This list can contain each character only once, so that its maximum length is 256. The function gives the same result as CharSort( CharList( cString ) )
Examples
? CharSList( "Hello World !" )  // --> " !HWdelor"
Status
Ready
Compliance
CharSList() is only available in Harbour's CT3 library.
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

CharSort()Source code  |  | Improve this doc

Sort sequences within a string.
Syntax
CharSort( <[@]cString>, [<nElementLength>], [<nCompareLength>],
          [<nIgnoreCharacters>], [<nElemenOffset>], [<nSortLength>],
          [<lDescending>] ) → cSortedString
Arguments
[@]cString is the string that should be processed [nElementLength] specifies the length of the elements that
should be sorted Default: 1
[nCompareLength] specifies how many characters within one
element should be used for comparison Default: nElementLength
[nIgnoreCharacters] specifies the number of characters at the
beginning of cString that should be ignored in the sort process Default: 0
[nElementOffset] specifies the offset of the comparison string
within a element Default: 0
[nSortLength] specifies how many characters in cString,
starting from the nIgnoreCharacters position, should be sorted Default: hb_BLen( cString ) - nIgnoreCharacters
[lDescending]) specifies whether the process should
sort descending or not
Returns
cSortedString the string resulting from the sort process
Description
The CharSort() function sorts the characters within a string cString. With the parameters nIgnoreCharacters and nSortLength, you can determine that only the substring from position nIgnoreCharacters+1 to position nIgnoreCharacters+nSortLength within cString should be sorted. The sorting algorithm is determined with the other parameters. nElementLength specifies the length of one element, i.e. there are nSortLength/nElementLength elements that are sorted. Note that surplus characters are not sorted but stay at their position. To do the sorting, the function uses the Quicksort algorithm implemented in the C-lib qsort() function. This algorithm needs to know how to compare and order two elements. This is done by comparing the ASCII values of a substring within each element. This substring is determined by the parameters nElementOffset and nCompareLength and the order by lDescending. By setting the CSetRef() switch to .T., one can omit the return value of the function, but one must then pass cString by reference.
Examples
? CharSort( "qwert" )                     // "eqrtw"
? CharSort( "qwert", 2 )                  // "erqwt"
? CharSort( "b1a4a3a2a1", 2, 1 )          // "a2a1a3a4b1"
? CharSort( "XXXqwert", 1, 1, 3 )         // "XXXeqrtw"
? CharSort( "b1a4a3a2a1", 2, 1, 0, 1 )    // "a1b1a2a3a4"
? CharSort( "384172852", 1, 1, 0, 0, 4 )  // "134872852"
? CharSort( "qwert", .T. )                // "wtrqe"
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

CharSub()Source code  |  | Improve this doc

Subtracts corresponding ASCII value of two strings
Syntax
CharSub( <[@]cString1>, <cString2>) → cSubString
Arguments
[@]cString1 first string cString2 second string
Returns
cSubString string with subtracted ASCII values
Description
The CharSub() function constructs a new string from the two strings passed as parameters. To do this, it subtracts the ASCII values of the corresponding characters of both strings and places a character in the resulting string whose ASCII value equals to that difference (modulo 256). If the first string is passed by reference, the resulting string is stored in cString1, too. By setting the CSetRef()-switch to .T., the return value can be omitted. If cString2 is shorter than cString1 and the last character of cString2 has been processed, the function restarts with the first character of cString2.
Examples
? CharSub( "012345678", hb_BChar( 1 ) )    // --> "/01234567"
? CharSub( "123456789", hb_BChar( 255 ) )  // --> "23456789:"
? CharSub( "9999", hb_BChar( 0 ) + hb_BChar( 1 ) + hb_BChar( 2 ) + hb_BChar( 3 ) )  // --> "9876"
Status
Ready
Compliance
Harbour specific
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

CharSwap()Source code  |  | Improve this doc

Swap neighbouring characters in a string
Syntax
CharSwap( <[@]cString> ) → cSwappedString
Arguments
[@]cString is the string that should be processed
Returns
cSwappedString a string where neighbour characters are swapped
Description
The CharSwap() function loops through cString in steps of two characters and exchanges the characters from the odd and the even positions. By setting the CSetRef() switch to .T., one can omit the return value of this function, but one must then pass cString by reference.
Examples
? CharSwap( "0123456789" )   // "1032547698"
? CharSwap( "ABCDEFGHIJK" )  // "BADCFEHGJIK"
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

CharXor()Source code  |  | Improve this doc

Combine corresponding ASCII value of two strings with bitwise XOR
Syntax
CharXor( <[@]cString1>, <cString2> ) → cXOrString
Arguments
[@]cString1 first string cString2 second string
Returns
cXOrString string with bitwise XOR combined ASCII values
Description
The CharXor() function constructs a new string from the two strings passed as parameters. To do this, it combines the ASCII values of the corresponding characters of both strings with a bitwise XOR-operation and places a character in the resulting string whose ASCII value equals to the result of that operation. If the first string is passed by reference, the resulting string is stored in cString1, too. By setting the CSetRef()-switch to .T., the return value can be omitted. If cString2 is shorter than cString1 and the last character of cString2 has been processed, the function restarts with the first character of cString2.
Examples
// easy encryption
? CharXor( "This is top secret !", "My Password" ) // --> <encrypted sentence>
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

CountLeft()Source code  |  | Improve this doc

Count a certain character at the beginning of a string
Syntax
CountLeft( <cString>, [<cSearch|nSearch>] ) → nCount
Description
TODO: add documentation
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

CountRight()Source code  |  | Improve this doc

Count a certain character at the end of a string
Syntax
CountRight( <cString>, [<cSearch|nSearch>] ) → nCount
Description
TODO: add documentation
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

CSetAtMupa()Source code  |  | Improve this doc

Determine "multi-pass" behaviour in some string functions
Syntax
CSetAtMupa( [<lNewSwitch>] ) → lOldSwitch
Arguments
[lNewSwitch] .T. - turn "multi-pass" on
.F. - turn "multi-pass" off
Returns
lOldSwitch old (if lNewSwitch is a logical value) or
current state of the switch
Description

CSetAtMupa() determines how the following CT3 string functions

AtNum() AfterAtNum() BeforAtNum() AtRepl() NumAt() AtAdjust() WordToChar() WordRepl()

perform their work. See the respective function documentation for a further description how the switch influences these functions.

Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

CSetRef()Source code  |  | Improve this doc

Determine return value of reference sensitive CT3 string functions
Syntax
CSetRef( [<lNewSwitch>] ) → lOldSwitch
Arguments
[lNewSwitch] .T. - suppress return value
.F. - do not suppress return value
Returns
lOldSwitch old (if lNewSwitch is a logical value) or
current state of the switch
Description

Within the CT3 functions, the following functions do not change the length of a string passed as parameter while transforming this string:

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

Thus, these functions allow to pass the string by reference @ to the function so that it may not be necessary to return the transformed string. By calling CSetRef( .T. ), the above mentioned functions return the value .F. instead of the transformed string if the string is passed by reference to the function. The switch is turned off (.F.) by default.

Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

JustLeft()Source code  |  | Improve this doc

Move characters from the beginning to the end of a string
Syntax
JustLeft( <[@]cString>, [<cChar>|<nChar>] ) → cJustifiedString
Description
TODO: add documentation
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

JustRight()Source code  |  | Improve this doc

Move characters from the end to the beginning of a string
Syntax
JustRight( <[@]cString>, [<cChar>|<nChar>] ) → cJustifiedString
Description
TODO: add documentation
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

NumAt()Source code  |  | Improve this doc

Number of occurrences of a sequence in a string
Syntax
NumAt( <cStringToMatch>, <cString>, [<nIgnore>] ) → nCount
Description
TODO: add documentation
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

NumToken()Source code  |  | Improve this doc

Retrieves the number of tokens in a string
Syntax
NumToken( <cString>, [<cTokenizer>], [<nSkipWidth>] ) → nTokenCount
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

PadLeft()Source code  |  | Improve this doc

Fills string to a certain length on the left
Syntax
PadLeft( <cString>, <nLength>, [<cChar|nChar>] ) → cString
Description
TODO: add documentation
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

PadRight()Source code  |  | Improve this doc

Fills string to a certain length on the right
Syntax
PadRight( <cString>, <nLength>, [<cChar|nChar>] ) → cString
Description
TODO: add documentation
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

PosAlpha()Source code  |  | Improve this doc

Left-most position of a letter in a string
Syntax
PosAlpha( <cString>, [<lMode>], [<nIgnore>] ) → nPosition
Description
TODO: add documentation
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

PosChar()Source code  |  | Improve this doc

Replace character at a certain position within a string
Syntax
PosChar( <[@]cString>, <cCharacter|nCharacter>, [<nPosition>] ) → cString
Description
TODO: add documentation
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

PosDel()Source code  |  | Improve this doc

Delete characters at a certain position within a string
Syntax
PosDel( <cString>, [<nStartPosition>], <nLength> ) → cString
Description
TODO: add documentation
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

PosDiff()Source code  |  | Improve this doc

The left-most position there two string differ
Syntax
PosDiff( <cString1>, <cString2>, [<nIgnore>] ) → nPosition
Description
TODO: add documentation
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

PosEqual()Source code  |  | Improve this doc

The left-most position there two string begin to be equal
Syntax
PosEqual( <cString1>, <cString2>, [<nCompare>], [<nIgnore>] ) → nPosition
Description
TODO: add documentation
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

PosIns()Source code  |  | Improve this doc

Insert characters at a certain position within a string
Syntax
PosIns( <cString>, <cInsert>, [<nPosition>] ) → cString
Description
TODO: add documentation
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

PosLower()Source code  |  | Improve this doc

Left-most position of a lowercase letter in a string
Syntax
PosLower( <cString>, [<lMode>], [<nIgnore>] ) → nPosition
Description
TODO: add documentation
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

PosRange()Source code  |  | Improve this doc

Left-most position of a character from a set in a string
Syntax
PosRange( <cChar1>, <cChar2>, <cString>, [<lMode>],
          [<nIgnore>] ) → nPosition
Description
TODO: add documentation
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

PosRepl()Source code  |  | Improve this doc

Replace characters at a certain position within a string
Syntax
PosRepl( <[@]cString>, <cReplacement>, [<nStartPosition>] ) → cString
Description
TODO: add documentation
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

PosUpper()Source code  |  | Improve this doc

Left-most position of an uppercase letter in a string
Syntax
PosUpper( <cString>, [<lMode>], [<nIgnore>] ) → nPosition
Description
TODO: add documentation
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

RangeRem()Source code  |  | Improve this doc

Remove characters within a certain ASCII range from a string
Syntax
RangeRem( <cChar1|nChar1>, <cChar2|nChar2>, <cString> ) → cString
Description
TODO: add documentation
Examples
? RangeRem( "0", "9", "year2002.dbf" )  // "year.dbf", remove all digits
? RangeRem( "9", "0", "year2002.dbf" )  // "22", testing removal from "9" to hb_BChar( 255 )
                                        // and from hb_BChar( 0 ) to "0"
? RangeRem( "0", "9", "yearcurr.dbf" )  // "yearcurr.dbf", test leaving string untouched
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

RANGEREPL |  | Improve this doc

Replace characters within a certain ASCII range from a string
Syntax
RangeRepl( <cChar1|nChar1>, <cChar2|nChar2>,
           <[@]cString>, <cReplacementChar|nReplacementChar> ) → cString
Description
TODO: add documentation
Examples
? RangeRepl( "0", "9", "year2002.dbf", "?" )  // "year????.dbf", replace all digits
? RangeRepl( "9", "0", "year2002.dbf", "?" )  // "????2??2????", testing replacement from "9" to hb_BChar( 255 )
                                              // and from hb_BChar( 0 ) to "0"
? RangeRepl( "0", "9", "yearcurr.dbf", "?" )  // "yearcurr.dbf", test leaving string untouched
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

RemAll()Source code  |  | Improve this doc

Remove certain characters at the left and right of a string
Syntax
RemAll( <cString>, [<cSearch|nSearch>] ) → cString
Description
TODO: add documentation
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

RemLeft()Source code  |  | Improve this doc

Remove certain characters at the left of a string
Syntax
RemLeft( <cString>, [<cSearch|nSearch>] ) → cString
Description
TODO: add documentation
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

RemRight()Source code  |  | Improve this doc

Remove certain characters at the right of a string
Syntax
RemRight( <cString>, [<cSearch|nSearch>] ) → cString
Description
TODO: add documentation
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

ReplAll()Source code  |  | Improve this doc

Replace certain characters at the left and right of a string
Syntax
ReplAll( <cString>, <cReplace|nReplace>, [<cSearch|nSearch>] ) → cString
Description
TODO: add documentation
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

ReplLeft()Source code  |  | Improve this doc

Replace certain characters at the left of a string
Syntax
ReplLeft( <cString>, <cReplace|nReplace>, [<cSearch|nSearch>] ) → cString
Description
TODO: add documentation
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

ReplRight()Source code  |  | Improve this doc

Replace certain characters at the right of a string
Syntax
ReplRight( <cString>, <cReplace|nReplace>, [<cSearch|nSearch>] ) → cString
Description
TODO: add documentation
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

RestToken()Source code  |  | Improve this doc

Restore global token environment
Syntax
RestToken( <cStaticTokenEnvironment> ) → cOldStaticEnvironment
Arguments
cStaticTokenEnvironment a binary string encoding a TE
Returns
cOldStaticEnvironment a string encoding the old global TE
Description
The RestToken() function restores the global TE to the one encoded in cStaticTokenEnvironment. This can either be the return value of SaveToken() or the value stored in the 4th parameter in a TokenInit() call.
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

SaveToken()Source code  |  | Improve this doc

Save the global token environment
Syntax
SaveToken() → cStaticTokenEnvironment
Returns
cStaticTokenEnvironment a binary string encoding the global TE
Description
The SaveToken() function can be used to store the global TE for future use or when two or more incremental tokenizers must the nested. Note however that the latter can now be solved with locally stored token environments.
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

SetAtLike()Source code  |  | Improve this doc

Determine scan behaviour in some string functions
Syntax
SetAtLike( [<nMode>] [, <[@]cWildcard>] ) → nOldMode
Arguments
[nMode] CT_SETATLIKE_EXACT - characters are compared exactly
CT_SETATLIKE_WILDCARD - characters are compared using
a wildcard character
The default value is CT_SETATLIKE_EXACT.
[[@]cWildcard] determines the character that is subsequently used
as a wildcard character for substring scanning. The default value is "?". NEW: If this parameter is passed by reference @, the current wildcard character is stored in cWildcard.
Returns
nOldMode old (if nMode is a numeric value) or
current state of the switch
Description

In the following CT3 functions, strings are compared on a character base:

AtAdjust() AtNum() AfterAtNum() BeforAtNum() AtRepl() NumAt() StrDiff()

With the SetAtLike() function, one can determine when characters are considered to match within these functions. If CT_SETATLIKE_WILDCARD is set (e.g. "?"), then "?" matches every other character.

nMode can be one of the following values that are defined in ct.ch:

CT_SETATLIKE_EXACT CT_SETATLIKE_WILDCARD

Status
Ready
Compliance
This function is fully CT3 compatible, but allows to pass the second parameter by reference so that the current wildcard character can be determined.
Platforms
Available on all platforms
File
Header is ct.ch, library is hbct.
Tag
CT3 string functions

StrDiff()Source code  |  | Improve this doc

Evaluate the "Edit (Levensthein) Distance" of two strings
Syntax
StrDiff( <cString1>, <cString2>, [<nReplacementPenalty>], [<nDeletionPenalty>],
         [<nInsertionPenalty>] ) → nDistance
Arguments
cString1 string at the "starting point" of the transformation process, default is "" cString2 string at the "end point" of the transformation process, default is "" nReplacementPenalty penalty points for a replacement of one character, default is 3 nDeletionPenalty penalty points for a deletion of one character, default is 6 nInsertionPenalty penalty points for an insertion of one character, default is 1
Returns
nDistance penalty point sum of all operations needed to transform cString1 to cString2
Description

The StrDiff() functions calculates the so called "Edit" or "Levensthein" distance of two strings. This distance is a measure for the number of single character replace/insert/delete operations (so called "point mutations") required to transform cString1 into cString2 and its value will be the smallest sum of the penalty points of the required operations.

Be aware that this function is both quite time - O( hb_BLen( cString1 ) * hb_BLen( cString2 ) ) - and memory consuming - O( ( hb_BLen( cString1 ) + 1 ) * ( hb_BLen( cString2 ) + 1 ) * sizeof( int ) ) - so keep the strings as short as possible. E.g., on common 32-bit systems ( sizeof( int ) == 4 ), calling StrDiff() with two strings of 1024 bytes in length will consume 4 MiB of memory. To not impose unneeded restrictions, the function will only check if ( hb_BLen( cString1 ) + 1 ) * ( hb_BLen( cString2 ) + 1 ) * sizeof( int ) <= UINT_MAX, although allocating UINT_MAX bytes will not work on most systems. If this simple check fails, -1 is returned.

Also, be aware that there can be an overflow when the penalty points are summed up: Assuming that the number of transformation operations is in the order of Max( hb_BLen( cString1 ), hb_BLen( cString2 ) ), the penalty point sum, that is internally stored in an "int" variable, is in the order of ( Max( hb_BLen( cString1 ), hb_BLen( cString2 ) ) * Max( nReplacementPenalty, nDeletionPenalty, nInsertionPentaly ). The StrDiff() does not do an overflow check due to time performance reasons. Future versions of StrDiff() could use a type different to "int" to store the penalty point sum to save memory or to avoid overflows.

The function is aware of the settings done by SetAtLike(), that means that the wildcard character is considered equal to ALL characters.

Examples
? StrDiff( "ABC", "ADC" )   // 3, one character replaced
? StrDiff( "ABC", "AEC" )   // 3, ditto
? StrDiff( "CBA", "ABC" )   // 6, two characters replaced
? StrDiff( "ABC", "AXBC" )  // 1, one character inserted
? StrDiff( "AXBC", "ABC" )  // 6, one character removed
? StrDiff( "AXBC", "ADC" )  // 9, one character removed and one replaced
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

StrSwap()Source code  |  | Improve this doc

Swap the contents of two strings
Syntax
StrSwap( <[@]cString1>, <[@]cString2> ) → cString
Description
TODO: add documentation
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions

TabExpand()Source code  |  | Improve this doc

Replace tabulator control characters with fill characters
Syntax
TabExpand( <cString>, [<nTabWidth>], [<cFillChar|nFillChar>],
           [<cNewLineCharacters>], [<cTabChar|nTabChar>],
           [<lIgnore141>] ) → cExpandedString
Arguments
cString nTabWidth cFillChar|nFillChar cNewLineCharacters string indicating new line,
default is the string returned by hb_eol()
cTabChar|nTabChar character indicating a tab stop,
default is Chr( 9 )
lIgnore141 .T., if the soft-CR used by MemoEdit()
should be ignored as a newline indicator, default is .F. (functions uses hb_BChar( 141 ))
Description
TODO: add documentation
Status
Ready
Compliance
TabExpand() is compatible with CT3's TabExpand(), but there are three new parameters for a better fine control of the function's behaviour.
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

TabPack()Source code  |  | Improve this doc

Pack fill characters to appropriate tab characters
Syntax
TabPack( <cString>, [<nTabWidth>], [<cFillChar|nFillChar>],
         [<cNewLineCharacters>], [<cTabChar|nTabChar>],
         [<lIgnore141>] ) → cPackedString
Arguments
cString nTabWidth cFillChar|nFillChar cNewLineCharacters string indicating new line,
default is the string returned by hb_eol()
cTabChar|nTabChar character indicating a tab stop,
default is Chr( 9 )
lIgnore141 .T., if the soft-CR used by MemoEdit()
should be ignored as a newline indicator, default is .F. (functions uses hb_BChar( 141 ))
Description
TODO: add documentation
Status
Ready
Compliance
TabPack() is compatible with CT3's TabPack(), but there are three new parameters for a better fine control of the function's behaviour.
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

Token()Source code  |  | Improve this doc

Tokens of a string
Syntax
Token( <cString>, [<cTokenizer>],
       [<nTokenCount], [<nSkipWidth>],
       [<@cPreTokenSep>], [<@cPostTokenSep>] ) → cToken
Arguments
cString is the processed string [cTokenizer] is a list of characters separating the tokens
in cString Default: Chr( 0 ) + Chr( 9 ) + Chr( 10 ) + Chr( 13 ) + Chr( 26 ) + hb_BChar( 138 ) + hb_BChar( 141 ) + Chr( 32 ) + ",.;:!\?/\\<>()#&%+-*"
[nTokenCount] specifies the count of the token that
should be extracted Default: last token
[nSkipWidth] specifies the maximum number of successive
tokenizing characters that are combined as one token stop, e.g. specifying 1 can yield to empty token Default: 0, any number of successive tokenizing characters are combined as one token stop
[@cPreTokenSep] If given by reference, the tokenizer before
the actual token will be stored
[@cPostTokenSep] If given by reference, the tokenizer after
the actual token will be stored
Returns
cToken the token specified by the parameters given above
Description
The Token() function extracts the nTokenCountth token from the string cString. In the course of this, the tokens in the string are separated by the character(s) specified in cTokenizer. The function may also extract empty tokens, if you specify a skip width other than zero. Be aware of the new 5th and 6th parameter there the Token() function stores the tokenizing character before and after the extracted token. Therefore, additional calls to the TokenSep() function are not necessary.
Examples
? Token( "Hello, World!" )             // "World"
? Token( "Hello, World!",, 2, 1 )      // ""
? Token( "Hello, World!", ",", 2, 1 )  // " World!"
? Token( "Hello, World!", " ", 2, 1 )  // "World!"
Status
Ready
Compliance
Token() is compatible with CT3's Token(), but two additional parameters have been added there the Token() function can store the tokenizers before and after the current token.
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

TokenAt()Source code  |  | Improve this doc

Get start and end positions of tokens in a token environment
Syntax
TokenAt( [<lSeparatorPositionBehindToken>], [<nToken>],
         [<@cTokenEnvironment>] ) → nPosition
Arguments
lSeparatorPositionBehindToken .T., if TokenAt() should return
the position of the separator character BEHIND the token. Default: .F., return start position of a token.
nToken a token number @cTokenEnvironment a token environment
Returns
nPosition
Description

The TokenAt() function is used to retrieve the start and end position of the tokens in a token environment. Note however that the position of last character of a token is given by TokenAt( .T. ) - 1 !!

If the 2nd parameter, nToken is given, TokenAt() returns the positions of the nTokenth token. Otherwise the token pointed to by the TE counter, i.e. the token that will be retrieved by TokenNext() NEXT is used.

If the parameter @cTokenEnvironment is supplied (must be by reference), the information from this token environment is used, otherwise the global TE is used.

Examples
LOCAL cString := "The quick brown fox jumps over the lazy dog"
TokenInit( cString ) // initialize a TE
DO WHILE ! TokenEnd()
   ? "From", TokenAt(), "to", TokenAt( .T. ) - 1
   ? TokenNext( cString )  // get all tokens successively
ENDDO
? TokenNext( cString, 3 )  // get the 3rd token, counter will remain the same
TokenExit()                // free the memory used for the global TE
Status
Ready
Compliance
TokenAt() is compatible with CT3's TokenAt(), but there are two additional parameters featuring local token environments and optional access to tokens.
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

TokenEnd()Source code  |  | Improve this doc

Check whether additional tokens are available with TokenNext()
Syntax
TokenEnd( [<@cTokenEnvironment>] ) → lTokenEnd
Arguments
@cTokenEnvironment a token environment
Returns
lTokenEnd .T., if additional tokens are available
Description
The TokenEnd() function can be used to check whether the next call to TokenNext() would return a new token. This cannot be decided with TokenNext() alone, since an empty token cannot be distinguished from a "no more" tokens. If the parameter @cTokenEnvironment is supplied (must be by reference), the information from this token environment is used, otherwise the global TE is used. With a combination of TokenEnd() and TokenNext(), all tokens from a string can be retrieved successively (see example).
Examples
TokenInit( "a.b.c.d", ".", 1 )  // initialize global TE
DO WHILE ! TokenEnd()
   ? TokenNext( "a.b.c.d" )     // get all tokens successively
ENDDO
Status
Ready
Compliance
TokenEnd() is compatible with CT3's TokenEnd(), but there are is an additional parameter featuring local token environments.
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

TokenExit()Source code  |  | Improve this doc

Release global token environment
Syntax
TokenExit() → lStaticEnvironmentReleased
Returns
lStaticEnvironmentReleased .T., if global token environment is successfully released
Description
The TokenExit() function releases the memory associated with the global token environment. One should use it for every TokenInit() using the global TE. Additionally, TokenExit() is implicitly called when the thread or application ends.
Examples
LOCAL cString := "The quick brown fox jumps over the lazy dog"
TokenInit( cString ) // initialize a TE
DO WHILE ! TokenEnd()
   ? TokenNext( cString )  // get all tokens successively
ENDDO
? TokenNext( cString, 3 )  // get the 3rd token, counter will remain the same
TokenExit()                // free the memory used for the global TE
Status
Ready
Compliance
TokenExit() is a new function in Harbour's CT3 library.
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

TokenInit()Source code  |  | Improve this doc

Initializes a token environment
Syntax
TokenInit( <[@]cString>], [<cTokenizer>], [<nSkipWidth>],
           [<@cTokenEnvironment>] ) → lState
Arguments
[@]cString is the processed string cTokenizer is a list of characters separating the tokens
in cString Default: Chr( 0 ) + Chr( 9 ) + Chr( 10 ) + Chr( 13 ) + Chr( 26 ) + hb_BChar( 138 ) + hb_BChar( 141 ) + Chr( 32 ) + ",.;:!\?/\\<>()#&%+-*"
nSkipWidth specifies the maximum number of successive
tokenizing characters that are combined as one token stop, e.g. specifying 1 can yield to empty token Default: 0, any number of successive tokenizing characters are combined as one token stop
@cTokenEnvironment is a token environment stored in a binary
encoded string
Returns
lState success of the initialization
Description

The TokenInit() function initializes a token environment. A token environment is the information about how a string is to be tokenized. This information is created in the process of tokenization of the string cString - equal to the one used in the Token() function with the help of the cTokenizer and nSkipWidth parameters.

This token environment can be very useful when large strings have to be tokenized since the tokenization has to take place only once whereas the Token() function must always start the tokenizing process from scratch.

Unlike CT3, this function provides two mechanisms of storing the resulting token environment. If a variable is passed by reference as 4th parameter, the token environment is stored in this variable, otherwise the global token environment is used. Do not modify the token environment string directly !

Additionally, a counter is stored in the token environment, so that the tokens can successively be obtained. This counter is first set to 1. When the TokenInit() function is called without a string a tokenize, the counter of either the global environment or the environment given by reference in the 4th parameter is rewind to 1.

Additionally, unlike CT3, TokenInit() does not need the string cString to be passed by reference, since one must provide the string in calls to TokenNext() again.

Examples
TokenInit( cString )             // tokenize the string <cString> with default
                                 // rules and store the token environment globally
                                 // and eventually delete an old global TE
TokenInit( @cString )            // no difference in result, but eventually faster,
                                 // since the string must not be copied
TokenInit()                      // rewind counter of global TE to 1
TokenInit( "1,2,3", "," , 1 )    // tokenize constant string, store in global TE
TokenInit( cString, , 1, @cTE1 ) // tokenize cString and store TE in
                                 // cTE1 only without overriding global TE
TokenInit( cString, , 1, cTE1 )  // tokenize cString and store TE in
                                 // GLOBAL TE since 4th parameter is
                                 // not given by reference !!!
TokenInit( ,,, @cTE1 )           // set counter in TE stored in cTE1 to 1
Status
Ready
Compliance
TokenInit() is compatible with CT3's TokenInit(), but there is an additional parameter featuring local token environments.
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

TokenLower()Source code  |  | Improve this doc

Change the first letter of tokens to lower case
Syntax
TokenLower( <[@]cString>, [<cTokenizer>], [<nTokenCount>],
            [<nSkipWidth>] ) → cString
Arguments
[@]cString is the processed string [cTokenizer] is a list of characters separating the tokens
in cString Default: Chr( 0 ) + Chr( 9 ) + Chr( 10 ) + Chr( 13 ) + Chr( 26 ) + hb_BChar( 138 ) + hb_BChar( 141 ) + Chr( 32 ) + ",.;:!\?/\\<>()#&%+-*"
[nTokenCount] specifies the number of tokens that
should be processed Default: all tokens
[nSkipWidth] specifies the maximum number of successive
tokenizing characters that are combined as one token stop, e.g. specifying 1 can yield to empty token Default: 0, any number of successive tokenizing characters are combined as one token stop
Returns
cString the string with the lowercased tokens
Description
The TokenLower() function changes the first letter of tokens in cString to lower case. To do this, it uses the same tokenizing mechanism as the Token() function. If TokenLower() extracts a token that starts with a letter, this letter will be changed to lower case. You can omit the return value of this function by setting the CSetRef() switch to .T., but you must then pass cString by reference to get the result.
Examples
? TokenLower( "Hello, World, here I am!" )          // "hello, world, here i am!"
? TokenLower( "Hello, World, here I am!",, 3 )      // "hello, world, here I am!"
? TokenLower( "Hello, World, here I am!", ",", 3 )  // "hello, World, here I am!"
? TokenLower( "Hello, World, here I am!", " W" )    // "hello, World, here i am!"
Status
Ready
Compliance
TokenLower() is compatible with CT3's TokenLower(), but a new 4th parameter, nSkipWidth has been added for synchronization with the the other token functions.
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

TokenNext()Source code  |  | Improve this doc

Successively obtains tokens from a string
Syntax
TokenNext( <[@]cString>, [<nToken>],
           [<@cTokenEnvironment>] ) → cToken
Arguments
[@]cString the processed string nToken a token number @cTokenEnvironment a token environment
Returns
cToken a token from cString
Description

With TokenNext(), the tokens determined with the TokenInit() functions can be retrieved. To do this, TokenNext() uses the information stored in either the global token environment or the local one supplied by cTokenEnvironment. Note that, is supplied, this 3rd parameter has always to be passed by reference.

If the 2nd parameter, nToken is given, TokenNext() simply returns the nTokenth token without manipulating the TE counter. Otherwise the token pointed to by the TE counter is returned and the counter is incremented by one. Like this, a simple loop with TokenEnd() can be used to retrieve all tokens of a string successively.

Note that cString does not have to be the same used in TokenInit(), so that one can do a "correlational tokenization", i.e. tokenize a string as if it was another! E.G. using TokenInit() with the string "AA, BBB" but calling TokenNext() with "CCCEE" would give first "CC" and then "EE" (because "CCCEE" is not long enough).

Examples
LOCAL cString := "The quick brown fox jumps over the lazy dog"
// default behaviour
TokenInit( cString )  // initialize a TE
DO WHILE ! TokenEnd()
   ? TokenNext( cString )  // get all tokens successively
ENDDO
? TokenNext( cString, 3 )  // get the 3rd token, counter will remain the same
TokenExit()                // free the memory used for the global TE
Status
Ready
Compliance
TokenNext() is compatible with CT3's TokenNext(), but there are two additional parameters featuring local token environments and optional access to tokens.
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

TokenNum()Source code  |  | Improve this doc

Get the total number of tokens in a token environment
Syntax
TokenNum( [<@cTokenEnvironment>] ) → nNumberofTokens
Arguments
@cTokenEnvironment a token environment
Returns
nNumberofTokens number of tokens in the token environment
Description
The TokenNum() function can be used to retrieve the total number of tokens in a token environment. If the parameter @cTokenEnvironment is supplied (must be by reference), the information from this token environment is used, otherwise the global TE is used.
Examples
TokenInit( "a.b.c.d", ".", 1 )  // initialize global TE
? TokenNum()  // --> 4
Status
Ready
Compliance
TokenNum() is a new function in Harbour's CT3 library.
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

TokenSep()Source code  |  | Improve this doc

Retrieves the token separators of the last Token() call
Syntax
TokenSep( [<lMode>] ) → cSeparator
Arguments
[lMode] if set to .T., the token separator BEHIND the token
retrieved from the Token() call will be returned. Default: .F., returns the separator BEFORE the token
Returns
Depending on the setting of lMode, the separating character of the the token retrieved from the last Token() call will be returned. These separating characters can now also be retrieved with the Token() function.
Description
When one does extract tokens from a string with the Token() function, one might be interested in the separator characters that have been used to extract a specific token. To get this information you can either use the TokenSep() function after each Token() call, or use the new 5th and 6th parameter of the Token() function.
Examples
see Token() function
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

TokenUpper()Source code  |  | Improve this doc

Change the first letter of tokens to upper case
Syntax
TokenUpper( <[@]cString>, [<cTokenizer>], [<nTokenCount>],
            [<nSkipWidth>] ) → cString
Arguments
[@]cString is the processed string [cTokenizer] is a list of characters separating the tokens
in cString Default: Chr( 0 ) + Chr( 9 ) + Chr( 10 ) + Chr( 13 ) + Chr( 26 ) + hb_BChar( 138 ) + hb_BChar( 141 ) + Chr( 32 ) + ",.;:!\?/\\<>()#&%+-*"
[nTokenCount] specifies the number of tokens that
should be processed Default: all tokens
[nSkipWidth] specifies the maximum number of successive
tokenizing characters that are combined as one token stop, e.g. specifying 1 can yield to empty token Default: 0, any number of successive tokenizing characters are combined as one token stop
Returns
cString the string with the uppercased tokens
Description
The TokenUpper() function changes the first letter of tokens in cString to upper case. To do this, it uses the same tokenizing mechanism as the Token() function. If TokenUpper() extracts a token that starts with a letter, this letter will be changed to upper case. You can omit the return value of this function by setting the CSetRef() switch to .T., but you must then pass cString by reference to get the result.
Examples
? TokenUpper( "Hello, world, here I am!" )          // "Hello, World, Here I Am!"
? TokenUpper( "Hello, world, here I am!",, 3 )      // "Hello, World, Here I am!"
? TokenUpper( "Hello, world, here I am!", ",", 3 )  // "Hello, world, here I am!"
? TokenUpper( "Hello, world, here I am!", " w" )    // "Hello, wOrld, Here I Am!"
Status
Ready
Compliance
TokenUpper() is compatible with CT3's TokenUpper(), but a new 4th parameter, nSkipWidth has been added for synchronization with the the other token functions.
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

ValPos()Source code  |  | Improve this doc

Numerical value of a character at a certain position
Syntax
ValPos( <cString>, [<nPosition>] ) → nDigitValue
Arguments
cString is the processed string [nPosition] is an optional position within cString
Default: last position in cString
Returns
nDigitValue the numerical value of the character at the specified
position
Description
The ValPos() function returns the numerical value of the character that can be found at the position nPosition in cString. If no digit can be found at this position or if nPosition is larger than the length of cString, 0 is returned.
Examples
? ValPos( "1234x56789" ) // --> 9
? ValPos( "1234x56789", 1 ) // --> 1
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

WordOne()Source code  |  | Improve this doc

Reduce multiple occurrences of a double character to one
Syntax
WordOne( [<cDoubleCharactersToReduce>,] <cString> ) → cReducedString
Arguments
[cDoubleCharactersToReduce] specifies the double characters the multiple
occurrences of which should be reduced to one Default: All characters.
cString specifies the processed string
Returns
cReducedString the string with the reduced occurrences
Description
The WordOne() function reduces multiple occurrences of double characters in cString to a single one. It is important to note that the multiple occurrences must occur directly one behind the other.
Examples
? WordOne( "12ABAB12" )       // "12AB12"
? WordOne( "1AAAA2" )         // "1AAAA2"
? WordOne( "12", "1212ABAB" ) // "12ABAB"
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

WordOnly()Source code  |  | Improve this doc

Intersectional set of two strings based on double characters
Syntax
WordOnly( <cThisDoubleCharactersOnly>, <cString> ) → cReducedString
Arguments
cThisDoubleCharactersOnly specifies the double characters that must
not be deleted in cString.
cString is the string that should be processed
Returns
cReducedString A string with all double characters deleted
but those specified in cThisCharactersOnly.
Description
The WordOnly() function calculates the intersectional set of two strings based on double characters. To do this, it deletes all double characters from cString that do not appear in cThisDoubleCharacterOnly.
Examples
? WordOnly( "AABBCCDD", "XXAAYYBBZZ" )  // "AABB"
? WordOnly( "AABBCCDD", "XAAYYYBBZZ" )  // "BB"
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

WordRem()Source code  |  | Improve this doc

Removes characters from a string
Syntax
WordRem( <cDeleteThisDoubleCharacters>, <cString> ) → cReducedString
Arguments
cDeleteThisDoubleCharacters specifies the double characters that
should be deleted in cString
cString) is the string that should be processed
Returns
cReducedString is a string where the double characters
specified in cDeleteThisDoubleCharacters are deleted
Description
The WordRem() function deletes the double characters specified in cDeleteThisDoubleCharacters from cString.
Examples
? WordRem( "abcd", "0ab1cd" )   // "0ab1"
? WordRem( "abcd", "ab0cd1" )   // "0cd1"
Status
Ready
Compliance
WordRem() is a new function available only in Harbour's CT3.
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

WordRepl()Source code  |  | Improve this doc

Replacement of double characters
Syntax
WordRepl( <cDoubleCharacterSearchString>, <[@]cString>,
          <cDoubleCharacterReplaceString>, [<lMode>] ) → cString
Arguments
cDoubleCharacterSearchString is a string of double characters
that should be replaced
[@]cString is the processed string cDoubleCharacterReplaceString is a string of double characters that
replace the one of cSearchString
[lMode] sets the replacement method (see description)
Default: .F.
Returns
cString the processed string
Description
The WordRepl() takes the double characters of cDoubleCharacterSearchString one after the other and searches for them in cString. For lMode set to .F., this search is successful, if the double character sequence in cString starts at an odd position or at any position, if lMode is set to .T. If this happens, the double character sequence will be replaced with the corresponding double character sequence of cDoubleCharacterReplaceString. If cDoubleCharacterReplaceString is shorter than cDoubleCharacterSearchString the last double sequence of cDoubleCharacterReplaceString is used for the "rest" of cDoubleCharacterSearchString. Note that the last double character sequence in "AABBC" is "BB" in this context !! After the replacement the function restarts the search in cString BEHIND the replacement if the CSetAtMupa() switch is turned off, or BEHIND the first character of the replacement if the switch is turned on. (see examples for this !) One can omit the return value of this function by setting the CSetRef() to .T., but one must then pass cString by reference to get a result.
Examples
? WordRepl( "CC", "AABBCCDDEE", "XX" )  // "AABBXXDDEE"
? WordRepl( "aa", "1aaaa", "ba" )       // "1abaa"
? WordRepl( "aa", "1aaaa", "ba", .T. )  // "1baba"
CSetAtMupa( .T. )
? WordRepl( "aa", "1aaaa", "ba" )       // "1abaa"
? WordRepl( "aa", "1aaaa", "ba", .T. )  // "1bbba"
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

WordSwap()Source code  |  | Improve this doc

Swap neighbouring double characters in a string
Syntax
WordSwap( <[@]cString> [, <lSwapCharacters>] ) → cSwappedString
Arguments
[@]cString is the string that should be processed [lSwapCharacters] specifies whether an additional swap should be
done within the double characters Default: .F., no additional swap
Returns
cSwappedString a string where neighbouring double characters are
swapped
Description
The WordSwap() function loops through cString in steps of four characters and exchanges the double characters from the first and second position with the one from the third and forth position. Additionally the function can perform a swap of the both char of each double character. By setting the CSetRef() switch to .T., one can omit the return value of this function, but one must then pass cString by reference.
Examples
? WordSwap( "1234567890" )       // "3412785690"
? WordSwap( "1234567890", .T. )  // "4321876590"
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

WordToChar()Source code  |  | Improve this doc

Replace double with single characters
Syntax
WordToChar( <cDoubleCharacterSearchString>, <cString>,
            <cSingleCharacterReplaceString> ) → cString
Description
TODO: add documentation
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 string functions
See also

KSetCaps()Source code  |  | Improve this doc

Syntax
KSetCaps( [<lNewSwitch>] ) → lOldSwitch
Description
TODO: add documentation
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on MS-DOS
File
Library is hbct.
Tag
CT3 switch and state functions

KSetIns()Source code  |  | Improve this doc

Syntax
KSetIns( [<lNewSwitch>] ) → lOldSwitch
Description
TODO: add documentation
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on MS-DOS
File
Library is hbct.
Tag
CT3 switch and state functions

KSetNum()Source code  |  | Improve this doc

Syntax
KSetNum( [<lNewSwitch>] ) → lOldSwitch
Description
TODO: add documentation
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on MS-DOS
File
Library is hbct.
Tag
CT3 switch and state functions

KSetScroll()Source code  |  | Improve this doc

Syntax
KSetScroll( [<lNewSwitch>] ) → lOldSwitch
Description
TODO: add documentation
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on MS-DOS
File
Library is hbct.
Tag
CT3 switch and state functions

CharPix()Source code  |  | Improve this doc

Gets the number of scan lines per character.
Syntax
CharPix() → nHeight
Returns
Returns the number of scan lines per character.
Description
Returns the number of scan lines per character.
Status
Started
Platforms
DJGPP
File
Library is hbct.
Tag
CT3 video functions

CharWin()Source code  |  | Improve this doc

Syntax
CharWin( <nTop>, <nLeft>, <nBottom>, <nRight>, [<cNewChar|nNewChar>],
         [<cOldChar|nOldChar>] ) → cEmptyString
Arguments
nTop - top row number, default 0 nLeft - left column number, default 0 nBottom - top row number, default MaxRow() nRight - right column number, default MaxCol() cNewChar|nNewChar - new character for the screen area,
as a numeric value in the range of 0 to 255 or as a character string, default value is the CLEARB.
cOldChar|nOldChar - character to exchange. Specify the parameter
as a numeric in the range of 0 to 255 or as a character string. The default is to exchange all characters.
Returns
Returns an empty string.
Description
Exchanges particular characters in a screen area. TODO: add documentation
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 video functions

ColorRepl()Source code  |  | Improve this doc

Syntax
ColorRepl( [<cNewAttr|nNewAttr>], [<cOldAttr|nOldAttr>] ) → cNull
Arguments
cNewAttr|nNewAttr Designates the new attribute. The default is
CLEARA.
cOldAttr|InOldAttr Designates the old attribute to exchange. The
default is all existing attributes.
Returns
Returns an empty string.
Description
Exchanges particular screen attributes TODO: add documentation
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 video functions

ColorToN()Source code  |  | Improve this doc

Syntax
ColorToN( <cAttr> ) → nAttr
Arguments
cAttr Designates the alphanumeric color attribute that is
converted in NN/NN or CC/CC form.
Returns
ColorToN() returns a number that corresponds to the combined numeric color attribute.
Description

COLOR TO (N)umeric The function changes an alphanumeric color attribute from NN/NN or CC/CC into a combined numeric attribute. These combined attribute values are useful with the CA-Cl*pper Tools functions StrScreen(), ScreenMix(), ScreenAttr(), and the CA-Cl*pper commands SAVE/RESTORE SCREEN.

TODO: add documentation

Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 video functions

ColorWin()Source code  |  | Improve this doc

Syntax
ColorWin( [<nTopLine>], [<nLeftCol>], [<nBottomLine>], [<nRightCol>],
          [<cNewAttr|nNewAttr>], [<cOldAttr|nOldAttr>] ) → cNull
Arguments
nTopLine Designates the topmost line to begin processing. The
default is the cursor line.
nLeftCol Designates the leftmost column to begin processing. The
default is the cursor column.
nBottomLine Designates the bottommost line that is processed.
The default is the last screen line or window line.
nRightCol Designates the rightmost column to clear. The default
is the right screen border or window border.
cNewAttr|nNewAttr Designates the new attribute to replace the old
one. The default is the standard attribute CLEARA.
cOldAttr|nOldAttr Designates the old character to exchange. The
default is "exchange all attributes".
Returns
Returns an empty string.
Description
Exchanges particular attributes in a screen area TODO: add documentation
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 video functions

Enhanced()Source code  |  | Improve this doc

Select the "ENHANCED" color value for output
Syntax
Enhanced() → cEmptyString
Description
TODO: add documentation
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 video functions
See also

InvertAttr()Source code  |  | Improve this doc

Description
TODO: add documentation
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 video functions

InvertWin()Source code  |  | Improve this doc

Description
TODO: add documentation
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 video functions

NToColor()Source code  |  | Improve this doc

Syntax
NToColor( <nAttr>, [<lColorCode>] ) → cAttr
Arguments
nAttr Designates the value for the combined numeric color
attributes.
lColorCode If designated as .F. or if the parameter is omitted,
NToColor() returns a string with a numeric color code. When designated as .T., NToColor() returns a string with the CA-Cl*pper alpha color coding.
Returns
NToColor() returns the designated color attribute in the NN/NN or CC/CC form.
Description

NToColor() converts a color attribute returned from another function in numeric form, into the alphanumeric data format. Use this attribute in conjunction with the CA-Cl*pper SET COLOR TO command.

TODO: add documentation

Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 video functions

SayScreen()Source code  |  | Improve this doc

Syntax
SayScreen( <cString>, [<nRow>], [<nCol>] ) → cEmptyString
Arguments
cString - the string to output. Although undocumented, can be NIL. nRow - row number, defaults to cursor row. nCol - column number, defaults to cursor column.
Returns
Returns an empty string.
Description
Outputs a string at specified coordinates without changing character attributes.
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 video functions
See also

ScreenAttr()Source code  |  | Improve this doc

Syntax
ScreenAttr( [<nRow>], [<nColumn>] ) → nAttr
Arguments
nRow Designates the line from which to determine the attribute.
The default is the cursor line.
nColumn Designates the column from which to determine the
attribute. The default is the cursor column.
Returns
ScreenAttr() returns the attribute at the designated position.
Description

ScreenAttr() returns the current screen attribute at nRow and nColumn. You can query targeted attributes this way and save them to use later, or process them later with InvertAttr().

TODO: add documentation

Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 video functions

ScreenMix()Source code  |  | Improve this doc

Syntax
ScreenMix( <cCharString>, <cAttributeString>, [<nRow>], [<nCol>] ) → cEmptyString
Description
TODO: add documentation
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 video functions

SetFont()Source code  |  | Improve this doc

Loads font from a string.
Syntax
SetFont( <cFontString>, [<nFontArea>], [<nOffset>], [<nCounter>] ) → nError
    or:
SetFont( <cFontString>, [<nFontArea>], [<lCompute>] ) → nError
Arguments
cFontString Binary string containing a valid font definition. nFontArea Number of a font area where the font must be loaded. nOffset First character code to be loaded. nCounter Number of characters to load. lCompute When .T., the function computes font height automatically.
Description
TODO: Finish documentation
Status
Started
Platforms
DJGPP
File
Library is hbct.
Tag
CT3 video functions

Standard()Source code  |  | Improve this doc

Select the "STANDARD" color value for output
Syntax
Standard() → cEmptyString
Description
TODO: add documentation
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 video functions
See also

Unselected()Source code  |  | Improve this doc

Select the "UNSELECTED" color value for output
Syntax
Unselected() → cEmptyString
Description
TODO: add documentation
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 video functions
See also

UnTextWin()Source code  |  | Improve this doc

Syntax
UnTextWin( <nTopLine>, <nLeftColumn>, <nBottomLine>, <nRightColumn>,
           <cReplacementCharacter|nReplacementCharacter>,
           [<cInitialCharacter|nInitialCharacter>],
           [<cEndCharacter|nEndCharacter>] ) → cNull
Arguments
nTopLine Designates the line for the upper-left corner of the
area.
nLeftColumn Designates the column for the upper-left corner of
the area.
nBottomLine Designates the line for the bottom-right corner of
the area.
nRightColumn Designates the line for the bottom-right column of
the area.
cReplacementCharacter|nReplacementCharacter Replaces each
character within the window, with the exception of those within the range of cInitialCharacter|nInitialCharacter and
cEndCharacter|nEndCharacter. cInitialCharacter|nInitialCharacter Designates the beginning of
the bracketed area. The character can be number in the range of 0 to 255, or the character string type. The default value is 176.
cEndCharacter|nEndCharacter Designates the end of the bracketed
area. The character can be number in the range of 0 to 255 or the character string type. The default value is 223.
Returns
Returns a null string.
Description
Replaces an area of characters from a region of the screen TODO: add documentation
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 video functions

VGAPalette()Source code  |  | Improve this doc

Changes VGA palette colors
Syntax
VGAPalette( [<cColor|nColor>, [<nRedValue>, <nGreenValue>,
                               <nBlueValue]] ) → lValid
Arguments
cColor|nColor - the color to change in CA-Cl*pper color notation or
as a number from 0 to 15.
nRedValue, nGreenValue, and nBlueValue specify the palette
settings for the respective portions in the range from 0 to 63. If no RGB value is specified, the palette register is reset to its default value (currently unsupported).
If the function is called without parameters, the palette registers for all colors are reset to their default values (currently unsupported).
Returns
Returns .T. on success.
Status
Started
Platforms
DJGPP
File
Library is hbct.
Tag
CT3 video functions
See also

VideoType()Source code  |  | Improve this doc

Detects supported video adapter modes
Syntax
VideoType() → nMask
Description
TODO: Finish documentation
Status
Started
Platforms
DJGPP
File
Library is hbct.
Tag
CT3 video functions
See also

ScreenText()Source code  |  | Improve this doc

Syntax
ScreenText( <nTop>, <nLeft>, <nBottom>, <nRight> )
Arguments
nTop - top row number, default 0 nLeft - left column number, default 0 nBottom - top row number, default MaxRow() nRight - right column number, default MaxCol()
Returns
Returns string with characters taken from given screen region.
Description
Returns string with characters taken from given screen region. TODO: add documentation
Status
Ready
Compliance
CA-Cl*pper v5.x compatible
Platforms
Available on all platforms
File
Library is hbct.
Tag
CT3 video functions (Harbour extension)