StringBuilder SQL Server Reference Documentation

StringBuilder

Current Version: 11.6.0

Chilkat.StringBuilder

Build, transform, search, encode, decode, hash, and save mutable text.

Chilkat.StringBuilder is a flexible mutable text container for constructing and transforming strings. It supports appending text, integers, random values, UUIDs, encoded bytes, and BinData; searching, comparing, extracting, replacing, masking, regex processing, line-ending normalization, encoding, decoding, hashing, Markdown conversion, file I/O, and secure clearing of sensitive text.

Build text incrementally

Append strings, characters, integers, random values, UUIDs, encoded data, and other Chilkat objects without repeatedly recreating strings.

Search and extract

Find substrings, compare content, extract ranges, split or inspect text, and work with selected portions of the buffer.

Replace and transform

Replace text, mask sensitive values, normalize line endings, trim or edit content, and apply regex-based processing when needed.

Encoding and decoding

Encode or decode text and binary data using formats such as Base64, hex, URL encoding, quoted-printable, and other supported encodings.

Hashing and conversion

Compute hashes of the current text, convert Markdown to HTML, and move content between StringBuilder, BinData, files, and plain strings.

File I/O and secure clearing

Load text from files, save text with explicit character encodings, and securely clear the buffer when it contains sensitive data.

Common pattern: Use StringBuilder when text will be assembled or modified in multiple steps. Append or load the starting content, perform searches, replacements, encoding, decoding, hashing, or line-ending normalization, then retrieve the result as a string, save it to a file, or pass the object directly to another Chilkat method.

For an extended overview, see StringBuilder Class Overview.

Object Creation

DECLARE @hr int
DECLARE @stringBuilder int
EXEC @hr = sp_OACreate 'Chilkat.StringBuilder', @stringBuilder OUT
IF @hr <> 0
BEGIN
    PRINT 'Failed to create ActiveX component'
    RETURN
END

-- ... use @stringBuilder ...

EXEC @hr = sp_OADestroy @stringBuilder

T-SQL uses the Chilkat ActiveX through the OLE Automation stored procedures. They must be enabled once on the server (EXEC sp_configure 'Ole Automation Procedures', 1; RECONFIGURE;), and the Chilkat ActiveX registered must match the bitness of the SQL Server instance (64-bit for a 64-bit SQL Server). To bind to a specific major version of Chilkat, append the major version number to the ProgID, such as sp_OACreate 'Chilkat.StringBuilder.11' for Chilkat v11.*.*.

sp_OACreate returns an object token (an int) that is passed as the first argument of every sp_OAMethod, sp_OAGetProperty and sp_OASetProperty call, and released with sp_OADestroy. Objects returned by methods (such as an HttpResponse or JsonObject) are also tokens received through an int OUT parameter; they must likewise be destroyed, and the OUT parameter is NULL when the method fails to return an object. Objects passed as arguments are passed by their token. When an OLE Automation procedure itself fails (non-zero @hr), sp_OAGetErrorInfo describes the error.

Data types: strings are nvarchar(4000); integers, booleans (1 or 0) and object tokens are int; dates are datetime. In the signatures on this page, @success, @iResult, @sResult and the like are the OUT variables receiving a method's return value, @iValue / @sValue receive or supply a property value, and the remaining @ variables are the method's arguments in order.

A string returned through an OUT parameter is limited to 4000 characters. For longer values, retrieve the result as a result set into a table variable instead of an OUT parameter, for example DECLARE @tmp TABLE (outputLine ntext) followed by INSERT INTO @tmp EXEC sp_OAGetProperty @stringBuilder, 'LastErrorText'. See string length limitations for strings returned by sp_OAMethod calls.

Methods that pass or return raw byte arrays are not shown on this page, because varbinary(max) values cannot be exchanged through sp_OAMethod (see varbinary(max) limitation). Use the BinData-based alternatives (methods ending in Bd) or the base64 / hex string-encoded variants instead. Binary properties (such as LastBinaryResult) can be retrieved as a result set into a table variable, as shown in their signatures. Asynchronous (*Async) methods and event callbacks are not available from SQL Server.

Properties

DebugLogFilePath
EXEC sp_OAGetProperty @stringBuilder, 'DebugLogFilePath', @sValue OUT
EXEC sp_OASetProperty @stringBuilder, 'DebugLogFilePath', @sValue

If set to a file path, this property logs the LastErrorText of each Chilkat method or property call to the specified file. This logging helps identify the context and history of Chilkat calls leading up to any crash or hang, aiding in debugging.

Enabling the VerboseLogging property provides more detailed information. This property is mainly used for debugging rare instances where a Chilkat method call causes a hang or crash, which should generally not happen.

Possible causes of hangs include:

  • A timeout property set to 0, indicating an infinite timeout.
  • A hang occurring within an event callback in the application code.
  • An internal bug in the Chilkat code causing the hang.

More Information and Examples
Example showing how to use DebugLogFilePath.
top
HasEmojis
EXEC sp_OAGetProperty @stringBuilder, 'HasEmojis', @iValue OUT
Introduced in version 11.1.0

Returns 1 if the content contains one or more emoji characters.

top
IntValue
EXEC sp_OAGetProperty @stringBuilder, 'IntValue', @iValue OUT
EXEC sp_OASetProperty @stringBuilder, 'IntValue', @iValue
Introduced in version 9.5.0.58

Returns the content of the string converted to an integer.

top
IsBase64
EXEC sp_OAGetProperty @stringBuilder, 'IsBase64', @iValue OUT
Introduced in version 9.5.0.76

Returns 1 if the content contains only those characters allowed in the base64 encoding. A base64 string is composed of characters 'A'..'Z', 'a'..'z', '0'..'9', '+', '/' and it is often padded at the end with up to two '=', to make the length a multiple of 4. Whitespace is ignored.

top
LastBinaryResult
INSERT INTO @tmp EXEC sp_OAGetProperty @stringBuilder, 'LastBinaryResult'

This property is mainly used in SQL Server stored procedures to retrieve binary data from the last method call that returned binary data. It is only accessible if Chilkat.Global.KeepBinaryResult is set to 1. This feature allows for the retrieval of large varbinary results in an SQL Server environment, which has restrictions on returning large data via method calls, though temp tables can handle binary properties.

top
LastErrorHtml
EXEC sp_OAGetProperty @stringBuilder, 'LastErrorHtml', @sValue OUT

Provides HTML-formatted information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.

top
LastErrorText
EXEC sp_OAGetProperty @stringBuilder, 'LastErrorText', @sValue OUT

Provides plain text information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.

More Information and Examples
Concept of LastErrorTextLastErrorText Standard Information
top
LastErrorXml
EXEC sp_OAGetProperty @stringBuilder, 'LastErrorXml', @sValue OUT

Provides XML-formatted information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.

top
LastMethodSuccess
EXEC sp_OAGetProperty @stringBuilder, 'LastMethodSuccess', @iValue OUT
EXEC sp_OASetProperty @stringBuilder, 'LastMethodSuccess', @iValue

Indicates the success or failure of the most recent method call: 1 means success, 0 means failure. This property remains unchanged by property setters or getters. This method is present to address challenges in checking for null or Nothing returns in certain programming languages. Note: This property does not apply to methods that return integer values or to boolean-returning methods where the boolean does not indicate success or failure.

top
LastStringResult
EXEC sp_OAGetProperty @stringBuilder, 'LastStringResult', @sValue OUT

In SQL Server stored procedures, this property holds the string return value of the most recent method call that returns a string. It is accessible only when Chilkat.Global.KeepStringResult is set to TRUE. SQL Server has limitations on string lengths returned from methods and properties, but temp tables can be used to access large strings.

More Information and Examples
Long Strings Returned by ActiveX Methods in SQL Server
top
LastStringResultLen
EXEC sp_OAGetProperty @stringBuilder, 'LastStringResultLen', @iValue OUT

The length, in characters, of the string contained in the LastStringResult property.

top
Length
EXEC sp_OAGetProperty @stringBuilder, 'Length', @iValue OUT
Introduced in version 9.5.0.58

The number of characters of the string contained within this instance.

top
VerboseLogging
EXEC sp_OAGetProperty @stringBuilder, 'VerboseLogging', @iValue OUT
EXEC sp_OASetProperty @stringBuilder, 'VerboseLogging', @iValue

If set to 1, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. The default value is 0. Verbose logging should only be used for debugging. The potentially large quantity of logged information may adversely affect peformance.

top
Version
EXEC sp_OAGetProperty @stringBuilder, 'Version', @sValue OUT

Version of the component/library, such as "10.1.0"

More Information and Examples
How to get the Chilkat version at runtime.
top

Methods

Append
EXEC sp_OAMethod @stringBuilder, 'Append', @success OUT, @value
Introduced in version 9.5.0.58

Appends a copy of the specified string to this instance.

Returns 1 for success, 0 for failure.

top
AppendBd
EXEC sp_OAMethod @stringBuilder, 'AppendBd', @success OUT, @binData, @charset, @offset, @numBytes
Introduced in version 9.5.0.64

Appends the contents of binData. The charset specifies the character encoding of the bytes contained in binData. The charset can be any of the supported encodings listed at Chilkat Supported Character Encodings. To append the entire contents of binData, set offset and numBytes equal to zero. To append a range of binData, set the offset and numBytes to specify the range.

Returns 1 for success, 0 for failure.

top
AppendInt
EXEC sp_OAMethod @stringBuilder, 'AppendInt', @success OUT, @value
Introduced in version 9.5.0.58

Appends the string representation of a specified 32-bit signed integer to this instance.

Returns 1 for success, 0 for failure.

top
AppendLine
EXEC sp_OAMethod @stringBuilder, 'AppendLine', @success OUT, @str, @crlf
Introduced in version 9.5.0.65

Appends the str followed by a CRLF or LF to the end of the curent StringBuilder object. If crlf is 1, then a CRLF line ending is used. Otherwise a LF line ending is used.

Returns 1 for success, 0 for failure.

top
AppendLn
EXEC sp_OAMethod @stringBuilder, 'AppendLn', @success OUT, @str
Introduced in version 11.5.0

Appends the str followed by a CRLF to the end of this object. This method is the same as AppendLine , except the line-ending is always CRLF.

Returns 1 for success, 0 for failure.

top
AppendRandom
EXEC sp_OAMethod @stringBuilder, 'AppendRandom', @success OUT, @numBytes, @encoding
Introduced in version 9.5.0.96

Append numBytes random bytes encoded according to encoding. encoding can be hex, hex_lower, base64, base64url, or any other encoding supported by Chilkat.

Returns 1 for success, 0 for failure.

top
AppendSb
EXEC sp_OAMethod @stringBuilder, 'AppendSb', @success OUT, @sb
Introduced in version 9.5.0.62

Appends the contents of another StringBuilder to this instance.

Returns 1 for success, 0 for failure.

top
AppendUuid
EXEC sp_OAMethod @stringBuilder, 'AppendUuid', @success OUT, @lowerCase
Introduced in version 9.5.0.93

Generates and appends a random GUID/UUID such as 63c35f38-2b5f-4600-b3da-3ddee86d62b3. If lowerCase is 1, then the hex values use lowercase (a - f). If lowerCase is 0 then uppercase is used (A - F).

Note: This generates a version 4 UUID.

Returns 1 for success, 0 for failure.

More Information and Examples
Generate UUID
top
AppendUuid7
EXEC sp_OAMethod @stringBuilder, 'AppendUuid7', @success OUT, @lowerCase
Introduced in version 10.1.0

Generates and appends a random version 7 UUID. If lowerCase is 1, then the hex values use lowercase (a - f). If lowerCase is 0 then uppercase is used (A - F).

Returns 1 for success, 0 for failure.

top
Clear
EXEC sp_OAMethod @stringBuilder, 'Clear', NULL
Introduced in version 9.5.0.58

Removes all characters from the current StringBuilder instance.

top
Contains
EXEC sp_OAMethod @stringBuilder, 'Contains', @success OUT, @str, @caseSensitive
Introduced in version 9.5.0.58

Returns 1 if the str is contained within this object. For case sensitive matching, set caseSensitive equal to 1. For case-insensitive, set caseSensitive equal to 0.

top
ContainsWord
EXEC sp_OAMethod @stringBuilder, 'ContainsWord', @success OUT, @word, @caseSensitive
Introduced in version 9.5.0.69

Returns 1 if the word is contained within this object, but only if it is a whole word. This method is limited to finding whole words in strings that only contains characters in the Latin1 charset (i.e. iso-8859-1 or Windows-1252). A whole word can only contain alphanumeric chars where the alpha chars are restricted to those of the Latin1 alpha chars. (The underscore character is also considered part of a word.)

For case sensitive matching, set caseSensitive equal to 1. For case-insensitive, set caseSensitive equal to 0.

top
ContentsEqual
EXEC sp_OAMethod @stringBuilder, 'ContentsEqual', @success OUT, @str, @caseSensitive
Introduced in version 9.5.0.62

Returns 1 if the contents of this object equals the str. Returns 0 if unequal. For case insensitive equality, set caseSensitive equal to 0.

top
ContentsEqualSb
EXEC sp_OAMethod @stringBuilder, 'ContentsEqualSb', @success OUT, @sb, @caseSensitive
Introduced in version 9.5.0.62

Returns 1 if the contents of this object equals the sb. Returns 0 if unequal. For case insensitive equality, set caseSensitive equal to 0.

top
Decode
EXEC sp_OAMethod @stringBuilder, 'Decode', @success OUT, @encoding, @charset
Introduced in version 9.5.0.62

Decodes and replaces the contents with the decoded string. The encoding can be set to any of the following strings: base64, hex, quoted-printable (or qp), url, base32, Q, B, url_rc1738, url_rfc2396, url_rfc3986, url_oauth, uu, modBase64, or html (for HTML entity encoding). The full up-to-date list of supported binary encodings is available at the link entitled Supported Binary Encodings below.

Note: This method can only be called if the encoded content decodes to a string. The charset indicates the charset to be used in intepreting the decoded bytes. For example, the charset can be utf-8, utf-16, iso-8859-1, shift_JIS, etc.

Returns 1 for success, 0 for failure.

More Information and Examples
JSON Escape and Unescape a StringUnicode Escape and Unescape Text in StringBuilderHTML Entity Encode and Decode in StringBuilderMIME Header Q and B Encoding and Decoding
top
DecodeAndAppend
EXEC sp_OAMethod @stringBuilder, 'DecodeAndAppend', @success OUT, @value, @encoding, @charset
Introduced in version 9.5.0.87

Decodes a binary encoded string, where the binary encoding (such as url, hex, base64, etc.) is specified by encoding, and the underlying charset encoding (such as utf-8, windows-1252, etc.) is specified by charset. The decoded string is appended to this object.

Returns 1 for success, 0 for failure.

More Information and Examples
Decode from Binary Encoding and Append StringBase62 Encoding and Decoding
top
Encode
EXEC sp_OAMethod @stringBuilder, 'Encode', @success OUT, @encoding, @charset
Introduced in version 9.5.0.62

Encodes to base64, hex, quoted-printable, URL encoding, etc. The encoding can be set to any of the following strings: base64, hex, quoted-printable (or qp), url, base32, Q, B, url_rc1738, url_rfc2396, url_rfc3986, url_oauth, uu, modBase64, or html (for HTML entity encoding). The full up-to-date list of supported binary encodings is available at the link entitled Supported Binary Encodings below.

Returns 1 for success, 0 for failure.

More Information and Examples
Supported Binary EncodingsStringBuilder EncodeUnicode Escape and Unescape Text in StringBuilderHTML Entity Encode and Decode in StringBuilderUN/EDIFACT Syntax Level A Encoding/DecodingJSON Escape and Unescape a StringURL Encoding and DecodingUnicode Escape
top
EndsWith
EXEC sp_OAMethod @stringBuilder, 'EndsWith', @success OUT, @substr, @caseSensitive
Introduced in version 9.5.0.62

Returns 1 if the string ends with substr. Otherwise returns 0. The comparison is case sensitive if caseSensitive is 1, and case insensitive if caseSensitive is 0.

top
EntityDecode
EXEC sp_OAMethod @stringBuilder, 'EntityDecode', @success OUT
Introduced in version 9.5.0.62

Decodes HTML entities. See HTML entities for more information about HTML entities.

Returns 1 for success, 0 for failure.

More Information and Examples
StringBuilder EntityDecode
top
GetAfterBetween
EXEC sp_OAMethod @stringBuilder, 'GetAfterBetween', @sResult OUT, @searchAfter, @beginMark, @endMark
Introduced in version 9.5.0.62

Begin searching after the 1st occurrence of searchAfter is found, and then return the substring found between the next occurrence of beginMark and the next occurrence of endMark.

Returns NULL on failure

More Information and Examples
StringBuilder GetAfterBetweenImplement Preprocessor #include with StringBuilder
top
GetAfterFinal
EXEC sp_OAMethod @stringBuilder, 'GetAfterFinal', @sResult OUT, @marker, @removeFlag
Introduced in version 9.5.0.77

Returns the substring found after the final occurrence of marker. If removeFlag is 1, the marker and the content that follows is removed from this content.

If the marker is not present, then the entire string is returned. In this case, if removeFlag is 1, this object is also cleared.

Returns NULL on failure

More Information and Examples
StringBuilder GetAfterFinal
top
GetAsString
EXEC sp_OAMethod @stringBuilder, 'GetAsString', @sResult OUT
Introduced in version 9.5.0.58

Returns the contents as a string.

Returns NULL on failure

top
GetBefore
EXEC sp_OAMethod @stringBuilder, 'GetBefore', @sResult OUT, @marker, @removeFlag
Introduced in version 9.5.0.77

Returns the substring found before the 1st occurrence of marker. If removeFlag is 1, the content up to and including the marker is removed from this object's contents.

If the marker is not present, then the entire string is returned. In this case, if removeFlag is 1, this object is also cleared.

Returns NULL on failure

More Information and Examples
StringBuilder GetBefore
top
GetBetween
EXEC sp_OAMethod @stringBuilder, 'GetBetween', @sResult OUT, @beginMark, @endMark
Introduced in version 9.5.0.62

Returns the substring found between the 1st occurrence of beginMark and the next occurrence of endMark.

Returns NULL on failure

More Information and Examples
StringBuilder GetBetween
top
GetEncoded
EXEC sp_OAMethod @stringBuilder, 'GetEncoded', @sResult OUT, @encoding, @charset
Introduced in version 9.5.0.62

Returns the string contents encoded in an encoding such as base64, hex, quoted-printable, or URL-encoding. The encoding can be set to any of the following strings: base64, hex, quoted-printable (or qp), url, base32, Q, B, url_rc1738, url_rfc2396, url_rfc3986, url_oauth, uu, modBase64, or html (for HTML entity encoding). The full up-to-date list of supported binary encodings is available at the link entitled Supported Binary Encodings below.

Note: The Encode method modifies the content of this object. The GetEncoded method leaves this object's content unmodified.

Returns NULL on failure

More Information and Examples
Supported Binary EncodingsStringBuilder GetEncodedStringBuilder Encode Charset
top
GetHash
EXEC sp_OAMethod @stringBuilder, 'GetHash', @sResult OUT, @algorithm, @encoding, @charset
Introduced in version 9.5.0.91

Returns the hash of the contents of this object. The algorithm is the hash algorithm, and can be sha1, sha256, sha384, sha512, sha3-224, sha3-256, sha3-384, sha3-512, md2, md5, ripemd128, ripemd160,ripemd256, or ripemd320. The encoding can be base64, modBase64, base64Url, base32, base58, qp (for quoted-printable), url (for url-encoding), hex, hexLower, or any of the encodings found at Chilkat Binary Encodings List.

The charset is the character encoding byte representation to hash. It is typically utf-8. It can be any of the chacter encodings listed at Chilkat Character Encodings List.

Returns NULL on failure

More Information and Examples
Hash (Digest) a String
top
GetNth
EXEC sp_OAMethod @stringBuilder, 'GetNth', @sResult OUT, @index, @delimiterChar, @exceptDoubleQuoted, @exceptEscaped
Introduced in version 9.5.0.62

Returns the Nth substring in string that is a list delimted by delimiterChar. The first substring is at index 0. If exceptDoubleQuoted is 1, then the delimiter char found between double quotes is not treated as a delimiter. If exceptEscaped is 1, then an escaped (with a backslash) delimiter char is not treated as a delimiter.

Returns NULL on failure

More Information and Examples
StringBuilder GetNth
top
GetRange
EXEC sp_OAMethod @stringBuilder, 'GetRange', @sResult OUT, @startIndex, @numChars, @removeFlag
Introduced in version 9.5.0.87

Returns a string containing the specified range of characters from this instance. If removeFlag is 1, then the range of chars is removed from this instance.

Note: It was discovered that the range of chars was always removed regardless of the value of removeFlag. This is fixed in v9.5.0.89.

Returns NULL on failure

More Information and Examples
Get a Substring by Char Index and Length
top
GetRangeSb
EXEC sp_OAMethod @stringBuilder, 'GetRangeSb', @success OUT, @startIndex, @numChars, @removeFlag, @sb
Introduced in version 11.3.0

Appends to startIndex the specified range of characters from this instance. If removeFlag is 1, then the range of chars is removed from this instance.

Returns 1 for success, 0 for failure.

top
IsWellFormed
EXEC sp_OAMethod @stringBuilder, 'IsWellFormed', @success OUT, @format
Introduced in version 11.6.0

Returns 1 if the contents of this object are well-formed JSON or XML. format selects which check to apply and must be json or xml (case insensitive). Returns 0 if the contents do not conform, or if format is anything else.

Chilkat's JSON and XML parsers are deliberately tolerant. Given text that is not well-formed they can still report success, leaving an empty or partially populated document. This method answers the question those parsers do not, and it does so without loading the text into a JsonObject or Xml object first. The checks applied here are the same ones those classes apply when their Strict property is set.

For xml this is a well-formedness check: element nesting and tag matching, attribute syntax and duplicate attributes, entity and character references, comments, processing instructions, CDATA sections, the XML declaration, the DOCTYPE declaration, and that the bytes are valid UTF-8 containing only characters XML permits. It is not a validating parse: no DTD or schema is read.

For json the full RFC 8259 grammar is checked.

Empty contents are not well-formed in either format, so 0 is returned.

Note: The contents of this object are never modified by this method.

top
LastNLines
EXEC sp_OAMethod @stringBuilder, 'LastNLines', @sResult OUT, @numLines, @bCrlf
Introduced in version 9.5.0.62

Returns the last N lines of the text. If fewer than numLines lines exists, then all of the text is returned. If bCrlf is 1, then the line endings of the returned string are converted to CRLF, otherwise the line endings are converted to LF-only.

Returns NULL on failure

More Information and Examples
Get the Last N Lines of a StringBuilder
top
LoadFile
EXEC sp_OAMethod @stringBuilder, 'LoadFile', @success OUT, @path, @charset
Introduced in version 9.5.0.62

Loads the contents of a file.

Returns 1 for success, 0 for failure.

More Information and Examples
Load utf-8 Text File into a StringBuilderConvert a Text File from utf-8 to Windows-1252
top
MarkdownToHtml
EXEC sp_OAMethod @stringBuilder, 'MarkdownToHtml', @success OUT, @options, @sbHtml
Introduced in version 11.2.0

This method converts the Markdown content of this object to HTML, storing the result in sbHtml. It supports both streaming and full document conversion. options specifies conversion options, including a key streaming option. In streaming mode, generated HTML is appended to sbHtml. In non-streaming mode, sbHtml is fully replaced by the generated HTML. For further details, see the examples linked below.

In streaming mode, only complete markdown lines are converted to HTML and removed from this object, leaving just the final partial line, if present. If this object contains only a partial markdown line, no HTML is emitted.

Starting in v11.3.0 ...

  • "emitJavascript": true can be included in options to emit Javascript function calls instead of HTML. This is used to update the response in an embedded browser in real-time. See Real-Time Streaming AI Responses to Embedded Browsers in Desktop Apps
  • "streamingShell": true is used to convert an empty string to an HTML shell to be used as the starting point before applying Javascript function calls. See Preparing the HTML Shell
  • "theme": "html_theme_name" can be included when creating the HTML shell to select a predefined theme or when converting Markdown to HTML in non-streaming mode. The available themes are:
    • ChatGPT - A style that is similar to the ChatGPT application.
    • cleanWin - A clean style for Windows applications.
    • cleanMac - A clean style for MacOS applications.
    • raw - No HTML styles, header, or body begin/end elements are emitted. Only the Markdown to HTML generated elements are emitted.

    If no theme is is included, then default HTML docType/root/body/header elements are emitted unless various parts are overridden by docType, rootElement, head, bodyStart, bodyEnd, and bodyExtra.

  • "usesPrism": true can be included when creating the HTML shell (or when converting Markdown to HTML in non-streaming mode) to include PRISM code highlighting.
  • "prism": { "theme": "prism_theme_name" } Is optional and can be used to specify the prism theme when usesPrism is true. Possible values are:
    • tomorrow
    • default
    • coy
    • dark
    • funky
    • okaidia
    • solarizedlight
    • twilight
  • "prism": { "version": "version_number" } Is optional can can be used to specify the prism version, such as "1.29.0" when usesPrism is true. If not specified, then "1.29.0" is used.
  • If no theme is specified, then any or all of the following HTML document parts can be explicitly specified:
    • "docType": "doctype_element" The DOCTYPE element. The default is "<!DOCTYPE html>"
    • "rootElement": "root_element" The html element. The default is "<html>"
    • "head": "head_section" The HTML fragment for the HTML head section. The default is "<head><meta charset="utf-8" /></head>".
      Note: If usesPrism is true, then prism related links will be inserted just before the </head>.
    • "bodyStart": "html_fragment" The HTML fragment to begin the body section. The default is "<body><div id="content">"
    • "bodyEnd": "html_fragment" The HTML fragment to end the body section. The default is "</div><!-- end-of-content-div --></body>"
    • "noContentDiv": true If set, the default bodyStart and bodyEnd do not include the "<div id="content">" and "</div><!-- end-of-content-div -->"
  • "copyButton": true In non-streaming mode, can optionally be set to include HTML for adding a copy button. THe copy button is added by default in streaming mode.
  • "ChatGPT": { "max-width": "css_length"; } Is optional can can be used to specify the max width of the body text if the theme is ChatGPT. The css_length is a length using CSS length units, such as "72ch", "40em", "800px", etc.

Returns 1 for success, 0 for failure.

More Information and Examples
Markdown to HTML - Streaming ModeMarkdown to HTML - Full Document, Custom Theme with Code Syntax HighlightingMarkdown to HTML - Full Document, ChatGPT Theme with Code Syntax HighlightingMarkdown to HTML - Full Document, ChatGPT ThemeMarkdown to HTML - Full Document, DefaultMarkdown to HTML - Full Document, Raw
top
MaskQuotedStrings
EXEC sp_OAMethod @stringBuilder, 'MaskQuotedStrings', @success OUT, @maskChar, @quoteType, @maskedStrings
Introduced in version 11.2.0

This function masks the content inside single and/or double-quoted strings by replacing it with a specified mask character (maskChar). The content of each masked quoted string is saved to maskedStrings. The contents can be restored by calling RestoreMaskedStrings.

quoteType determines which types of quoted strings are masked:

  1. Both single and double quoted.
  2. Only single quoted strings.
  3. Only double quoted strings.

Returns 1 for success, 0 for failure.

More Information and Examples
Mask Quoted Strings and then Restore Masked Strings
top
Obfuscate
EXEC sp_OAMethod @stringBuilder, 'Obfuscate', NULL
Introduced in version 9.5.0.80

Obfuscates the string. (The Unobfuscate method can be called to reverse the obfuscation to restore the original string.)

The Chilkat string obfuscation algorithm works by taking the utf-8 bytes of the string, base64 encoding it, and then scrambling the letters of the base64 encoded string. It is deterministic in that the same string will always obfuscate to the same result. It is NOT a secure way of encrypting a string. It is only meant to be a simple means of transforming a string into something unintelligible.

More Information and Examples
Obfuscate String
top
Prepend
EXEC sp_OAMethod @stringBuilder, 'Prepend', @success OUT, @value
Introduced in version 9.5.0.61

Prepends a copy of the specified string to this instance.

Returns 1 for success, 0 for failure.

top
PunyDecode
EXEC sp_OAMethod @stringBuilder, 'PunyDecode', @success OUT
Introduced in version 9.5.0.71

In-place decodes the string from punycode.

Returns 1 for success, 0 for failure.

More Information and Examples
Punycode Encoding / Decoding
top
PunyEncode
EXEC sp_OAMethod @stringBuilder, 'PunyEncode', @success OUT
Introduced in version 9.5.0.71

In-place encodes the string to punycode.

Returns 1 for success, 0 for failure.

More Information and Examples
Punycode Encoding / Decoding
top
RegexMatch
EXEC sp_OAMethod @stringBuilder, 'RegexMatch', @iResult OUT, @pattern, @json, @timeoutMs
Introduced in version 11.1.0

Searches the content of this object for substrings that match a regular expression pattern and returns the matches in json. Returns the number of matches or -1 for failure. timeoutMs is the maximum number of milliseconds of processing allowed before giving up. Pass 0 for an infinite amount of time. Failure information is also returned in json.

More Information and Examples
Regular Expression with Capture GroupsRegular Expression with Multiple Matches and Capture GroupsRegular Expression with Named Capture GroupsRegular Expression with Multiple Matches and Named Capture GroupsRegular Expression Catastrophic BacktrackChilkat Uses PCRE2 (Perl Compatible Regular Expressions, version 2)Chilkat PCRE2 Performance
top
RegexReplace
EXEC sp_OAMethod @stringBuilder, 'RegexReplace', @success OUT, @json
Introduced in version 11.1.0

Replaces the substrings of capture groups found in a previous call to RegexMatch.

More Information and Examples
Regular Expression Replace Capture GroupsRegular Expression Replace Full MatchesChilkat Uses PCRE2 (Perl Compatible Regular Expressions, version 2)Chilkat PCRE2 Performance
top
RemoveAccents
EXEC sp_OAMethod @stringBuilder, 'RemoveAccents', @success OUT
Introduced in version 9.5.0.91

Removes the accents (diacritics) from European accented characters. This applies only to the accented characters found in the Windows-1252 (Latin alphabet) and Windows-1250 (Central European) charsets. Accent marks for characters in other languages will not be removed.

Returns 1 for success, 0 for failure.

More Information and Examples
Remove Accent Marks from Chars in String
top
RemoveAfterFinal
EXEC sp_OAMethod @stringBuilder, 'RemoveAfterFinal', @success OUT, @marker
Introduced in version 9.5.0.77

Removes the substring found after the final occurrence of the marker. Also removes the marker. Returns 1 if the marker was found and content was removed. Otherwise returns 0.

Returns 1 for success, 0 for failure.

More Information and Examples
StringBuilder RemoveAfterFinal
top
RemoveBefore
EXEC sp_OAMethod @stringBuilder, 'RemoveBefore', @success OUT, @marker
Introduced in version 9.5.0.77

Removes the substring found before the 1st occurrence of the marker. Also removes the marker. Returns 1 if the marker was found and content was removed. Otherwise returns 0.

Returns 1 for success, 0 for failure.

More Information and Examples
StringBuilder RemoveBefore
top
RemoveCharsAt
EXEC sp_OAMethod @stringBuilder, 'RemoveCharsAt', @success OUT, @startIndex, @numChars
Introduced in version 9.5.0.87

Removes the specified range of characters from this instance.

Returns 1 for success, 0 for failure.

More Information and Examples
Remove a Range of Chars from a StringBuilder
top
RemoveEmojis
EXEC sp_OAMethod @stringBuilder, 'RemoveEmojis', NULL
Introduced in version 11.1.0

Removes all emoji characters from the string.

top
Replace
EXEC sp_OAMethod @stringBuilder, 'Replace', @iResult OUT, @value, @replacement
Introduced in version 9.5.0.58

Replaces all occurrences of a specified string in this instance with another specified string. Returns the number of replacements.

top
ReplaceAfterFinal
EXEC sp_OAMethod @stringBuilder, 'ReplaceAfterFinal', @success OUT, @marker, @replacement
Introduced in version 9.5.0.73

Replaces the content found after the final occurrence of marker with replacement.

Returns 1 for success, 0 for failure.

top
ReplaceAllBetween
EXEC sp_OAMethod @stringBuilder, 'ReplaceAllBetween', @success OUT, @beginMark, @endMark, @replacement, @replaceMarks
Introduced in version 9.5.0.64

Replaces the first occurrence of ALL the content found between beginMark and endMark with replacement. The beginMark and endMark are included in what is replaced if replaceMarks is 1.

Returns 1 for success, 0 for failure.

More Information and Examples
Implement Preprocessor #include with StringBuilder
top
ReplaceBetween
EXEC sp_OAMethod @stringBuilder, 'ReplaceBetween', @iResult OUT, @beginMark, @endMark, @value, @replacement
Introduced in version 9.5.0.62

Replaces all occurrences of value with replacement, but only where value is found between beginMark and endMark. Returns the number of replacements made.

More Information and Examples
StringBuilder ReplaceBetween
top
ReplaceFirst
EXEC sp_OAMethod @stringBuilder, 'ReplaceFirst', @success OUT, @value, @replacement
Introduced in version 9.5.0.77

Replaces the first occurrence of a specified string in this instance with another string. Returns 1 if the value was found and replaced. Otherwise returns 0.

Returns 1 for success, 0 for failure.

More Information and Examples
StringBuilder RemoveAfterFinal
top
ReplaceI
EXEC sp_OAMethod @stringBuilder, 'ReplaceI', @iResult OUT, @value, @replacement
Introduced in version 9.5.0.67

Replaces all occurrences of value with the decimal integer replacement. Returns the number of replacements.

top
ReplaceNoCase
EXEC sp_OAMethod @stringBuilder, 'ReplaceNoCase', @iResult OUT, @value, @replacement
Introduced in version 9.5.0.82

Replaces all occurrences of value with replacement (case insensitive). Returns the number of replacements.

top
ReplaceWord
EXEC sp_OAMethod @stringBuilder, 'ReplaceWord', @iResult OUT, @value, @replacement
Introduced in version 9.5.0.62

Replaces all word occurrences of a specified string in this instance with another specified string. Returns the number of replacements made.

Important: This method is limited to replacing whole words in strings that only contains characters in the Latin1 charset (i.e. iso-8859-1 or Windows-1252). A whole word can only contain alphanumeric chars where the alpha chars are restricted to those of the Latin1 alpha chars. (The underscore character is also considered part of a word.)

More Information and Examples
StringBuilder ReplaceWord
top
RestoreMaskedStrings
EXEC sp_OAMethod @stringBuilder, 'RestoreMaskedStrings', @success OUT, @quoteType, @maskedStrings
Introduced in version 11.2.0

Restores single and/or double-quoted strings previously masked by MaskQuotedStrings.

quoteType determines which types of quoted strings are masked:

  1. Both single and double quoted.
  2. Only single quoted strings.
  3. Only double quoted strings.

Returns 1 for success, 0 for failure.

More Information and Examples
Mask Quoted Strings and then Restore Masked Strings
top
SecureClear
EXEC sp_OAMethod @stringBuilder, 'SecureClear', NULL
Introduced in version 9.5.0.67

Removes all characters from the current StringBuilder instance, and write zero bytes to the allocated memory before deallocating.

top
SetNth
EXEC sp_OAMethod @stringBuilder, 'SetNth', @success OUT, @index, @value, @delimiterChar, @exceptDoubleQuoted, @exceptEscaped
Introduced in version 9.5.0.62

Sets the Nth substring in string in a list delimted by delimiterChar. The first substring is at index 0. If exceptDoubleQuoted is 1, then the delimiter char found between double quotes is not treated as a delimiter. If exceptEscaped is 1, then an escaped (with a backslash) delimiter char is not treated as a delimiter.

Returns 1 for success, 0 for failure.

More Information and Examples
StringBuilder SetNth
top
SetString
EXEC sp_OAMethod @stringBuilder, 'SetString', @success OUT, @value
Introduced in version 9.5.0.61

Sets this instance to a copy of the specified string.

Returns 1 for success, 0 for failure.

top
Shorten
EXEC sp_OAMethod @stringBuilder, 'Shorten', @success OUT, @numChars
Introduced in version 9.5.0.87

Shortens the string by removing the last numChars chars.

Returns 1 for success, 0 for failure.

More Information and Examples
Shorten a String in StringBuilder by N Chars
top
StartsWith
EXEC sp_OAMethod @stringBuilder, 'StartsWith', @success OUT, @substr, @caseSensitive
Introduced in version 9.5.0.62

Returns 1 if the string starts with substr. Otherwise returns 0. The comparison is case sensitive if caseSensitive is 1, and case insensitive if caseSensitive is 0.

top
ToCRLF
EXEC sp_OAMethod @stringBuilder, 'ToCRLF', @success OUT
Introduced in version 9.5.0.62

Converts line endings to CRLF (Windows) format.

Returns 1 for success, 0 for failure.

top
ToLF
EXEC sp_OAMethod @stringBuilder, 'ToLF', @success OUT
Introduced in version 9.5.0.62

Converts line endings to LF-only (UNIX) format.

Returns 1 for success, 0 for failure.

top
ToLowercase
EXEC sp_OAMethod @stringBuilder, 'ToLowercase', @success OUT
Introduced in version 9.5.0.62

Converts the contents to lowercase.

Returns 1 for success, 0 for failure.

top
ToUppercase
EXEC sp_OAMethod @stringBuilder, 'ToUppercase', @success OUT
Introduced in version 9.5.0.62

Converts the contents to uppercase.

Returns 1 for success, 0 for failure.

top
Trim
EXEC sp_OAMethod @stringBuilder, 'Trim', @success OUT
Introduced in version 9.5.0.62

Trims whitespace from both ends of the string.

Returns 1 for success, 0 for failure.

top
TrimInsideSpaces
EXEC sp_OAMethod @stringBuilder, 'TrimInsideSpaces', @success OUT
Introduced in version 9.5.0.62

Replaces all tabs, CR's, and LF's, with SPACE chars, and removes extra SPACE's so there are no occurances of more than one SPACE char in a row.

Returns 1 for success, 0 for failure.

top
Unobfuscate
EXEC sp_OAMethod @stringBuilder, 'Unobfuscate', NULL
Introduced in version 9.5.0.80

Unobfuscates the string.

The Chilkat string obfuscation algorithm works by taking the utf-8 bytes of the string, base64 encoding it, and then scrambling the letters of the base64 encoded string. It is deterministic in that the same string will always obfuscate to the same result. It is not a secure way of encrypting a string. It is only meant to be a simple means of transforming a string into something unintelligible.

More Information and Examples
Obfuscate String
top
WriteFile
EXEC sp_OAMethod @stringBuilder, 'WriteFile', @success OUT, @path, @charset, @emitBom
Introduced in version 9.5.0.62

Writes the contents to a file. If emitBom is 1, then the BOM (also known as a preamble), is emitted for charsets that define a BOM (such as utf-8, utf-16, utf-32, etc.)

Returns 1 for success, 0 for failure.

top
WriteFileIfModified
EXEC sp_OAMethod @stringBuilder, 'WriteFileIfModified', @success OUT, @path, @charset, @emitBom
Introduced in version 9.5.0.73

Writes the contents to a file, but only if it is a new file or if the contents are different than the existing file. If emitBom is 1, then the BOM (also known as a preamble), is emitted for charsets that define a BOM (such as utf-8, utf-16, utf-32, etc.)

Returns 1 for success, 0 for failure.

top