StringBuilder Chilkat2 PHP Reference Documentation

StringBuilder

Current Version: 11.7.0

Markdown version of this page for AI tools (v 11.7.0) · all AI docs

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

use Chilkat2\StringBuilder;

try {
    $sb = new StringBuilder();
    // ... use $sb ...
} catch (\Chilkat2\Exception $e) {
    echo $e->getClass(), '::', $e->getMethod(), " failed\n";
    echo $e->getMessage(), "\n";              // the LastErrorText of the failed call
}
public function __construct(array $properties = [])

Creates the object. The optional array sets properties in order, as if assigned one by one (new StringBuilder(['VerboseLogging' => true, 'RaiseError' => false])); an unknown or read-only name throws Error. The class is defined by the chilkat2 extension (extension=chilkat2 in php.ini): there is no PHP file to include.

There is no close(): PHP frees the object when its last reference goes (unset($sb), $sb = null, or the end of the function or request). Objects returned by methods are independent and freed the same way. The class may be extended (class MyStringBuilder extends \Chilkat2\StringBuilder); objects cannot be cloned or serialized.

public bool $RaiseError;

When true (the default), a method that fails throws Chilkat2\Exception. When false, it returns false (or null) instead, and the reason is in LastErrorText. Objects returned by a method inherit the value of the object that returned them.

Errors

Chilkat2\Exception extends RuntimeException: getMessage() is the failed call's full LastErrorText, getClass() its class ('Chilkat2\StringBuilder') and getMethod() the method name. The object remains usable. Methods that look something up and find nothing return null without throwing (each such method says so), methods that answer a question (HasMember, IsUnlocked, ...) return a plain bool, and property reads and writes do not throw for Chilkat reasons.

Misuse always throws, whatever RaiseError is: a wrong argument type is a TypeError (exact types under declare(strict_types=1)), a missing or extra argument an ArgumentCountError, a string containing a NUL byte or an out-of-range integer a ValueError, and an unknown property (properties are case-sensitive) or a write to a read-only one an Error. Named arguments work with the parameter names shown.

Strings are passed and returned as UTF-8; binary data is a PHP string of bytes. Unlocking: call (new \Chilkat2\GlobalSettings())->UnlockBundle('...') once at startup.

Properties

DebugLogFilePath
public string $DebugLogFilePath;

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
public readonly bool $HasEmojis;
Introduced in version 11.1.0

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

top
IntValue
public int $IntValue;
Introduced in version 9.5.0.58

Returns the content of the string converted to an integer.

top
IsBase64
public readonly bool $IsBase64;
Introduced in version 9.5.0.76

Returns true 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
LastErrorHtml
public readonly string $LastErrorHtml;

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
public readonly string $LastErrorText;

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
public readonly string $LastErrorXml;

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
public bool $LastMethodSuccess;

Indicates the success or failure of the most recent method call: true means success, false 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
Length
public readonly int $Length;
Introduced in version 9.5.0.58

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

top
VerboseLogging
public bool $VerboseLogging;

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

top
Version
public readonly string $Version;

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
public function Append(string $value): bool
Introduced in version 9.5.0.58

Appends a copy of the specified string to this instance.

Returns true on success. On failure it throws Chilkat2\Exception (or, with RaiseError set to false, returns false). $e->getMessage() (or the object's LastErrorText) explains why, and the object remains usable.

top
AppendBd
public function AppendBd(BinData $binData, string $charset, int $offset, int $numBytes): bool
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 true on success. On failure it throws Chilkat2\Exception (or, with RaiseError set to false, returns false). $e->getMessage() (or the object's LastErrorText) explains why, and the object remains usable.

top
AppendInt
public function AppendInt(int $value): bool
Introduced in version 9.5.0.58

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

Returns true on success. On failure it throws Chilkat2\Exception (or, with RaiseError set to false, returns false). $e->getMessage() (or the object's LastErrorText) explains why, and the object remains usable.

top
AppendInt64
public function AppendInt64(int $value): bool
Introduced in version 9.5.0.58

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

Returns true on success. On failure it throws Chilkat2\Exception (or, with RaiseError set to false, returns false). $e->getMessage() (or the object's LastErrorText) explains why, and the object remains usable.

top
AppendLine
public function AppendLine(string $str, bool $crlf): bool
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 true, then a CRLF line ending is used. Otherwise a LF line ending is used.

Returns true on success. On failure it throws Chilkat2\Exception (or, with RaiseError set to false, returns false). $e->getMessage() (or the object's LastErrorText) explains why, and the object remains usable.

top
AppendLn
public function AppendLn(string $str): bool
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 true on success. On failure it throws Chilkat2\Exception (or, with RaiseError set to false, returns false). $e->getMessage() (or the object's LastErrorText) explains why, and the object remains usable.

top
AppendRandom
public function AppendRandom(int $numBytes, string $encoding): bool
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 true on success. On failure it throws Chilkat2\Exception (or, with RaiseError set to false, returns false). $e->getMessage() (or the object's LastErrorText) explains why, and the object remains usable.

top
AppendSb
public function AppendSb(StringBuilder $sb): bool
Introduced in version 9.5.0.62

Appends the contents of another StringBuilder to this instance.

Returns true on success. On failure it throws Chilkat2\Exception (or, with RaiseError set to false, returns false). $e->getMessage() (or the object's LastErrorText) explains why, and the object remains usable.

top
AppendUuid
public function AppendUuid(bool $lowerCase): bool
Introduced in version 9.5.0.93

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

Note: This generates a version 4 UUID.

Returns true on success. On failure it throws Chilkat2\Exception (or, with RaiseError set to false, returns false). $e->getMessage() (or the object's LastErrorText) explains why, and the object remains usable.

More Information and Examples
Generate UUID
top
AppendUuid7
public function AppendUuid7(bool $lowerCase): bool
Introduced in version 10.1.0

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

Returns true on success. On failure it throws Chilkat2\Exception (or, with RaiseError set to false, returns false). $e->getMessage() (or the object's LastErrorText) explains why, and the object remains usable.

top
Clear
public function Clear(): void
Introduced in version 9.5.0.58

Removes all characters from the current StringBuilder instance.

top
Contains
public function Contains(string $str, bool $caseSensitive): bool
Introduced in version 9.5.0.58

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

Never throws: false is an answer, not a failure.

top
ContainsWord
public function ContainsWord(string $word, bool $caseSensitive): bool
Introduced in version 9.5.0.69

Returns true 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 true. For case-insensitive, set $caseSensitive equal to false.

Never throws: false is an answer, not a failure.

top
ContentsEqual
public function ContentsEqual(string $str, bool $caseSensitive): bool
Introduced in version 9.5.0.62

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

Never throws: false is an answer, not a failure.

top
ContentsEqualSb
public function ContentsEqualSb(StringBuilder $sb, bool $caseSensitive): bool
Introduced in version 9.5.0.62

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

Never throws: false is an answer, not a failure.

top
Decode
public function Decode(string $encoding, string $charset): bool
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 true on success. On failure it throws Chilkat2\Exception (or, with RaiseError set to false, returns false). $e->getMessage() (or the object's LastErrorText) explains why, and the object remains usable.

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 DecodingURL DecodeDecode utf-8 Hex to a String
top
DecodeAndAppend
public function DecodeAndAppend(string $value, string $encoding, string $charset): bool
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 true on success. On failure it throws Chilkat2\Exception (or, with RaiseError set to false, returns false). $e->getMessage() (or the object's LastErrorText) explains why, and the object remains usable.

More Information and Examples
Decode from Binary Encoding and Append StringBase62 Encoding and Decoding
top
Encode
public function Encode(string $encoding, string $charset): bool
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 true on success. On failure it throws Chilkat2\Exception (or, with RaiseError set to false, returns false). $e->getMessage() (or the object's LastErrorText) explains why, and the object remains usable.

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
public function EndsWith(string $substr, bool $caseSensitive): bool
Introduced in version 9.5.0.62

Returns true if the string ends with $substr. Otherwise returns false. The comparison is case sensitive if $caseSensitive is true, and case insensitive if $caseSensitive is false.

Never throws: false is an answer, not a failure.

top
EntityDecode
public function EntityDecode(): bool
Introduced in version 9.5.0.62

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

Returns true on success. On failure it throws Chilkat2\Exception (or, with RaiseError set to false, returns false). $e->getMessage() (or the object's LastErrorText) explains why, and the object remains usable.

More Information and Examples
StringBuilder EntityDecode
top
GetAfterBetween
public function GetAfterBetween(string $searchAfter, string $beginMark, string $endMark): ?string
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.

On failure it throws Chilkat2\Exception (or, with RaiseError set to false, returns null). $e->getMessage() (or the object's LastErrorText) explains why, and the object remains usable.

More Information and Examples
StringBuilder GetAfterBetweenImplement Preprocessor #include with StringBuilder
top
GetAfterFinal
public function GetAfterFinal(string $marker, bool $removeFlag): ?string
Introduced in version 9.5.0.77

Returns the substring found after the final occurrence of $marker. If $removeFlag is true, 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 true, this object is also cleared.

On failure it throws Chilkat2\Exception (or, with RaiseError set to false, returns null). $e->getMessage() (or the object's LastErrorText) explains why, and the object remains usable.

More Information and Examples
StringBuilder GetAfterFinal
top
GetAsString
public function GetAsString(): ?string
Introduced in version 9.5.0.58

Returns the contents as a string.

On failure it throws Chilkat2\Exception (or, with RaiseError set to false, returns null). $e->getMessage() (or the object's LastErrorText) explains why, and the object remains usable.

top
GetBefore
public function GetBefore(string $marker, bool $removeFlag): ?string
Introduced in version 9.5.0.77

Returns the substring found before the 1st occurrence of $marker. If $removeFlag is true, 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 true, this object is also cleared.

On failure it throws Chilkat2\Exception (or, with RaiseError set to false, returns null). $e->getMessage() (or the object's LastErrorText) explains why, and the object remains usable.

More Information and Examples
StringBuilder GetBefore
top
GetBetween
public function GetBetween(string $beginMark, string $endMark): ?string
Introduced in version 9.5.0.62

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

On failure it throws Chilkat2\Exception (or, with RaiseError set to false, returns null). $e->getMessage() (or the object's LastErrorText) explains why, and the object remains usable.

More Information and Examples
StringBuilder GetBetween
top
GetEncoded
public function GetEncoded(string $encoding, string $charset): ?string
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.

On failure it throws Chilkat2\Exception (or, with RaiseError set to false, returns null). $e->getMessage() (or the object's LastErrorText) explains why, and the object remains usable.

More Information and Examples
Supported Binary EncodingsStringBuilder GetEncodedStringBuilder Encode Charset
top
GetHash
public function GetHash(string $algorithm, string $encoding, string $charset): ?string
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.

On failure it throws Chilkat2\Exception (or, with RaiseError set to false, returns null). $e->getMessage() (or the object's LastErrorText) explains why, and the object remains usable.

More Information and Examples
Hash (Digest) a String
top
GetNth
public function GetNth(int $index, string $delimiterChar, bool $exceptDoubleQuoted, bool $exceptEscaped): ?string
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 true, then the delimiter char found between double quotes is not treated as a delimiter. If $exceptEscaped is true, then an escaped (with a backslash) delimiter char is not treated as a delimiter.

On failure it throws Chilkat2\Exception (or, with RaiseError set to false, returns null). $e->getMessage() (or the object's LastErrorText) explains why, and the object remains usable.

More Information and Examples
StringBuilder GetNth
top
GetRange
public function GetRange(int $startIndex, int $numChars, bool $removeFlag): ?string
Introduced in version 9.5.0.87

Returns a string containing the specified range of characters from this instance. If $removeFlag is true, 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.

On failure it throws Chilkat2\Exception (or, with RaiseError set to false, returns null). $e->getMessage() (or the object's LastErrorText) explains why, and the object remains usable.

More Information and Examples
Get a Substring by Char Index and Length
top
GetRangeSb
public function GetRangeSb(int $startIndex, int $numChars, bool $removeFlag, StringBuilder $sb): bool
Introduced in version 11.3.0

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

Returns true on success. On failure it throws Chilkat2\Exception (or, with RaiseError set to false, returns false). $e->getMessage() (or the object's LastErrorText) explains why, and the object remains usable.

top
HtmlToMarkdown
public function HtmlToMarkdown(): bool
Introduced in version 11.7.0

Converts the HTML contained in this object to Markdown, replacing the contents with the Markdown. Returns true on success. If the conversion fails, the contents are left unchanged and the reason is in the LastErrorText.

This is the reverse of MarkdownToHtml. The HTML is parsed with the same parser used by Html.ToXml and Html.ToText, and the resulting document tree produces CommonMark / GitHub-flavored Markdown:

  • h1 through h6 become # .. ###### headings.
  • p, div, section and other block-level elements become paragraphs separated by a blank line. br becomes a hard line break and hr becomes ---.
  • b/strong become **bold**, i/em/cite become *italic*, del/s/strike become ~~struck~~, and code/kbd/samp become a backtick code span.
  • pre becomes a fenced code block. The language is taken from a language-xxx or lang-xxx class on the pre or its code child.
  • a href becomes [text](url "title"), and img becomes ![alt](src "title").
  • ul/ol/li become - and 1. lists, with nested lists indented. A checkbox input inside a list item becomes [ ] or [x].
  • blockquote becomes lines prefixed with >.
  • table becomes a GitHub pipe table. The first row is the header when it contains th cells or is inside a thead; colspan is honored, and align or text-align sets the column alignment. A single-column table becomes plain paragraphs, because such tables are usually for layout.
  • dl/dt/dd become a term line followed by : definition lines.

head, script, style, title, meta, link, noscript, iframe, object, embed, svg, canvas, form controls and comments produce no output. Any other tag is transparent: only its content is emitted.

Markdown-significant punctuation in ordinary text is backslash-escaped so that the text renders literally. Text inside code and pre is never escaped. HTML entities are decoded.

The Markdown uses LF line endings, always ends with a single line ending, and never contains more than one consecutive blank line outside of a code block. Call ToCRLF afterwards for CRLF line endings.

Note: The conversion is in-place. The HTML is not available after a successful call, so load it into a separate StringBuilder first if it is still needed.

Empty contents, or HTML with no visible content, produce empty contents and true is returned.

Returns true on success. On failure it throws Chilkat2\Exception (or, with RaiseError set to false, returns false). $e->getMessage() (or the object's LastErrorText) explains why, and the object remains usable.

top
IsWellFormed
public function IsWellFormed(string $format): bool
Introduced in version 11.6.0

Returns true 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 false 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 false is returned.

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

Never throws: false is an answer, not a failure.

top
LastNLines
public function LastNLines(int $numLines, bool $bCrlf): ?string
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 true, then the line endings of the returned string are converted to CRLF, otherwise the line endings are converted to LF-only.

On failure it throws Chilkat2\Exception (or, with RaiseError set to false, returns null). $e->getMessage() (or the object's LastErrorText) explains why, and the object remains usable.

More Information and Examples
Get the Last N Lines of a StringBuilder
top
LoadFile
public function LoadFile(string $path, string $charset): bool
Introduced in version 9.5.0.62

Loads the contents of a file.

Returns true on success. On failure it throws Chilkat2\Exception (or, with RaiseError set to false, returns false). $e->getMessage() (or the object's LastErrorText) explains why, and the object remains usable.

More Information and Examples
Load utf-8 Text File into a StringBuilderLoad Text File to String using any Code PageConvert a Text File from utf-8 to Windows-1252
top
MarkdownToHtml
public function MarkdownToHtml(JsonObject $options, StringBuilder $sbHtml): bool
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 true on success. On failure it throws Chilkat2\Exception (or, with RaiseError set to false, returns false). $e->getMessage() (or the object's LastErrorText) explains why, and the object remains usable.

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
public function MaskQuotedStrings(string $maskChar, int $quoteType, StringTable $maskedStrings): bool
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 true on success. On failure it throws Chilkat2\Exception (or, with RaiseError set to false, returns false). $e->getMessage() (or the object's LastErrorText) explains why, and the object remains usable.

More Information and Examples
Mask Quoted Strings and then Restore Masked Strings
top
Obfuscate
public function Obfuscate(): void
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
public function Prepend(string $value): bool
Introduced in version 9.5.0.61

Prepends a copy of the specified string to this instance.

Returns true on success. On failure it throws Chilkat2\Exception (or, with RaiseError set to false, returns false). $e->getMessage() (or the object's LastErrorText) explains why, and the object remains usable.

top
PunyDecode
public function PunyDecode(): bool
Introduced in version 9.5.0.71

In-place decodes the string from punycode.

Returns true on success. On failure it throws Chilkat2\Exception (or, with RaiseError set to false, returns false). $e->getMessage() (or the object's LastErrorText) explains why, and the object remains usable.

More Information and Examples
Punycode Encoding / Decoding
top
PunyEncode
public function PunyEncode(): bool
Introduced in version 9.5.0.71

In-place encodes the string to punycode.

Returns true on success. On failure it throws Chilkat2\Exception (or, with RaiseError set to false, returns false). $e->getMessage() (or the object's LastErrorText) explains why, and the object remains usable.

More Information and Examples
Punycode Encoding / Decoding
top
RegexMatch
public function RegexMatch(string $pattern, JsonObject $json, int $timeoutMs): int
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
public function RegexReplace(JsonObject $json): bool
Introduced in version 11.1.0

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

Returns true on success. On failure it throws Chilkat2\Exception (or, with RaiseError set to false, returns false). $e->getMessage() (or the object's LastErrorText) explains why, and the object remains usable.

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
public function RemoveAccents(): bool
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 true on success. On failure it throws Chilkat2\Exception (or, with RaiseError set to false, returns false). $e->getMessage() (or the object's LastErrorText) explains why, and the object remains usable.

More Information and Examples
Remove Accent Marks from Chars in String
top
RemoveAfterFinal
public function RemoveAfterFinal(string $marker): bool
Introduced in version 9.5.0.77

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

Returns true on success. On failure it throws Chilkat2\Exception (or, with RaiseError set to false, returns false). $e->getMessage() (or the object's LastErrorText) explains why, and the object remains usable.

More Information and Examples
StringBuilder RemoveAfterFinal
top
RemoveBefore
public function RemoveBefore(string $marker): bool
Introduced in version 9.5.0.77

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

Returns true on success. On failure it throws Chilkat2\Exception (or, with RaiseError set to false, returns false). $e->getMessage() (or the object's LastErrorText) explains why, and the object remains usable.

More Information and Examples
StringBuilder RemoveBefore
top
RemoveCharsAt
public function RemoveCharsAt(int $startIndex, int $numChars): bool
Introduced in version 9.5.0.87

Removes the specified range of characters from this instance.

Returns true on success. On failure it throws Chilkat2\Exception (or, with RaiseError set to false, returns false). $e->getMessage() (or the object's LastErrorText) explains why, and the object remains usable.

More Information and Examples
Remove a Range of Chars from a StringBuilder
top
RemoveEmojis
public function RemoveEmojis(): void
Introduced in version 11.1.0

Removes all emoji characters from the string.

top
Replace
public function Replace(string $value, string $replacement): int
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
public function ReplaceAfterFinal(string $marker, string $replacement): bool
Introduced in version 9.5.0.73

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

Returns true on success. On failure it throws Chilkat2\Exception (or, with RaiseError set to false, returns false). $e->getMessage() (or the object's LastErrorText) explains why, and the object remains usable.

top
ReplaceAllBetween
public function ReplaceAllBetween(string $beginMark, string $endMark, string $replacement, bool $replaceMarks): bool
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 true.

Returns true on success. On failure it throws Chilkat2\Exception (or, with RaiseError set to false, returns false). $e->getMessage() (or the object's LastErrorText) explains why, and the object remains usable.

More Information and Examples
Implement Preprocessor #include with StringBuilder
top
ReplaceBetween
public function ReplaceBetween(string $beginMark, string $endMark, string $value, string $replacement): int
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
public function ReplaceFirst(string $value, string $replacement): bool
Introduced in version 9.5.0.77

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

Returns true on success. On failure it throws Chilkat2\Exception (or, with RaiseError set to false, returns false). $e->getMessage() (or the object's LastErrorText) explains why, and the object remains usable.

More Information and Examples
StringBuilder RemoveAfterFinal
top
ReplaceI
public function ReplaceI(string $value, int $replacement): int
Introduced in version 9.5.0.67

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

top
ReplaceNoCase
public function ReplaceNoCase(string $value, string $replacement): int
Introduced in version 9.5.0.82

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

top
ReplaceWord
public function ReplaceWord(string $value, string $replacement): int
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
public function RestoreMaskedStrings(int $quoteType, StringTable $maskedStrings): bool
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 true on success. On failure it throws Chilkat2\Exception (or, with RaiseError set to false, returns false). $e->getMessage() (or the object's LastErrorText) explains why, and the object remains usable.

More Information and Examples
Mask Quoted Strings and then Restore Masked Strings
top
SecureClear
public function SecureClear(): void
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
public function SetNth(int $index, string $value, string $delimiterChar, bool $exceptDoubleQuoted, bool $exceptEscaped): bool
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 true, then the delimiter char found between double quotes is not treated as a delimiter. If $exceptEscaped is true, then an escaped (with a backslash) delimiter char is not treated as a delimiter.

Returns true on success. On failure it throws Chilkat2\Exception (or, with RaiseError set to false, returns false). $e->getMessage() (or the object's LastErrorText) explains why, and the object remains usable.

More Information and Examples
StringBuilder SetNth
top
SetString
public function SetString(string $value): bool
Introduced in version 9.5.0.61

Sets this instance to a copy of the specified string.

Returns true on success. On failure it throws Chilkat2\Exception (or, with RaiseError set to false, returns false). $e->getMessage() (or the object's LastErrorText) explains why, and the object remains usable.

top
Shorten
public function Shorten(int $numChars): bool
Introduced in version 9.5.0.87

Shortens the string by removing the last $numChars chars.

Returns true on success. On failure it throws Chilkat2\Exception (or, with RaiseError set to false, returns false). $e->getMessage() (or the object's LastErrorText) explains why, and the object remains usable.

More Information and Examples
Shorten a String in StringBuilder by N Chars
top
StartsWith
public function StartsWith(string $substr, bool $caseSensitive): bool
Introduced in version 9.5.0.62

Returns true if the string starts with $substr. Otherwise returns false. The comparison is case sensitive if $caseSensitive is true, and case insensitive if $caseSensitive is false.

Never throws: false is an answer, not a failure.

top
ToCRLF
public function ToCRLF(): bool
Introduced in version 9.5.0.62

Converts line endings to CRLF (Windows) format.

Returns true on success. On failure it throws Chilkat2\Exception (or, with RaiseError set to false, returns false). $e->getMessage() (or the object's LastErrorText) explains why, and the object remains usable.

top
ToLF
public function ToLF(): bool
Introduced in version 9.5.0.62

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

Returns true on success. On failure it throws Chilkat2\Exception (or, with RaiseError set to false, returns false). $e->getMessage() (or the object's LastErrorText) explains why, and the object remains usable.

top
ToLowercase
public function ToLowercase(): bool
Introduced in version 9.5.0.62

Converts the contents to lowercase.

Returns true on success. On failure it throws Chilkat2\Exception (or, with RaiseError set to false, returns false). $e->getMessage() (or the object's LastErrorText) explains why, and the object remains usable.

top
ToUppercase
public function ToUppercase(): bool
Introduced in version 9.5.0.62

Converts the contents to uppercase.

Returns true on success. On failure it throws Chilkat2\Exception (or, with RaiseError set to false, returns false). $e->getMessage() (or the object's LastErrorText) explains why, and the object remains usable.

top
Trim
public function Trim(): bool
Introduced in version 9.5.0.62

Trims whitespace from both ends of the string.

Returns true on success. On failure it throws Chilkat2\Exception (or, with RaiseError set to false, returns false). $e->getMessage() (or the object's LastErrorText) explains why, and the object remains usable.

top
TrimInsideSpaces
public function TrimInsideSpaces(): bool
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 true on success. On failure it throws Chilkat2\Exception (or, with RaiseError set to false, returns false). $e->getMessage() (or the object's LastErrorText) explains why, and the object remains usable.

top
Unobfuscate
public function Unobfuscate(): void
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
public function WriteFile(string $path, string $charset, bool $emitBom): bool
Introduced in version 9.5.0.62

Writes the contents to a file. If $emitBom is true, 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 true on success. On failure it throws Chilkat2\Exception (or, with RaiseError set to false, returns false). $e->getMessage() (or the object's LastErrorText) explains why, and the object remains usable.

top
WriteFileIfModified
public function WriteFileIfModified(string $path, string $charset, bool $emitBom): bool
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 true, 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 true on success. On failure it throws Chilkat2\Exception (or, with RaiseError set to false, returns false). $e->getMessage() (or the object's LastErrorText) explains why, and the object remains usable.

top