docs

Home

All functions

Legacy functions

Categories

TokenMergeInString()

Clarion prototype

Prototype: TokenMergeInString(*CSTRING InSourceText, *CSTRING OutTargetText, LONG InOutTargetTextLen, *CSTRING InToken, *CSTRING InReplacement, LONG InFlags), SIGNED, PROC, PASCAL, RAW, NAME(‘TokenMergeInString’)

Purpose

Replaces token text inside a source string and writes the merged result to a caller-owned output buffer.

Parameters

| Parameter | Type | Description | |—|—|—| | InSourceText | *CSTRING | Source text to inspect. | | OutTargetText | *CSTRING | Target buffer receiving the merged result. | | InOutTargetTextLen | LONG | Size of OutTargetText in bytes. | | InToken | *CSTRING | Full token text to replace, such as [[FirstName]]. | | InReplacement | *CSTRING | Replacement value to insert. | | InFlags | LONG | Merge option flags. 0=Replace all, case-sensitive, 1=First only, 2=Ignore case, 3=First only and ignore case. |

Return value / error codes

• Positive value: number of replacements performed.
• 0: No matching token was found.
• -1: Token text is blank.
• -2: Output buffer pointer or length is invalid.
• -4: Runtime failure.

Example (Clarion)

rc          LONG
srcText     CSTRING(1024)
outText     CSTRING(1024)
tokenText   CSTRING(80)
valueText   CSTRING(256)
flags       LONG

srcText   = 'Hello [[FirstName]], your code is [[Code]].'
outText   = ''
tokenText = '[[FirstName]]'
valueText = 'Charles'
flags     = 0

rc = TokenMergeInString(srcText, outText, SIZE(outText), tokenText, valueText, flags)
MESSAGE('TokenMergeInString rc=' & rc & ' text=' & outText)

Notes

• The function does not force a token format, but [[TokenName]] is strongly recommended.
• By default, the function replaces all matching tokens.
• Set flag bit 1 to replace only the first match.
• Set flag bit 2 to ignore case while matching the full token text.
• InSourceText and OutTargetText may point to the same CSTRING buffer for in-place replacement.
• The target buffer must be large enough to hold the merged result.
• If the target buffer is too small, the merged text will be truncated.

Home

All functions

Legacy functions

Categories