Package com.chilkatsoft.chilkat2

Class StringBuilder

java.lang.Object
com.chilkatsoft.chilkat2.ChilkatObject
com.chilkatsoft.chilkat2.StringBuilder
All Implemented Interfaces:
AutoCloseable
public class StringBuilder extends ChilkatObject
<section class="stringbuilder-summary">

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.

</section>

Instances hold a native Chilkat object: close them with ChilkatObject.close() (try-with-resources) when done; an unclosed instance is freed when it becomes unreachable.

See Also:
Online reference

  • Constructor Summary

    Constructors
    Constructor
    Description
    StringBuilder()
    Creates a new StringBuilder object.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    append​(String value)
    Appends a copy of the specified string to this instance.
    void
    appendBd​(BinData binData, String charset, int offset, int numBytes)
    Appends the contents of binData.
    void
    appendInt​(int value)
    Appends the string representation of a specified 32-bit signed integer to this instance.
    void
    appendInt64​(long value)
    Appends the string representation of a specified 64-bit signed integer to this instance.
    void
    appendLine​(String str, boolean crlf)
    Appends the str followed by a CRLF or LF to the end of the curent StringBuilder object.
    void
    appendLn​(String str)
    Appends the str followed by a CRLF to the end of this object.
    void
    appendRandom​(int numBytes, String encoding)
    Append numBytes random bytes encoded according to encoding.
    void
    appendSb​(StringBuilder sb)
    Appends the contents of another StringBuilder to this instance.
    void
    appendUuid​(boolean lowerCase)
    Generates and appends a random GUID/UUID such as 63c35f38-2b5f-4600-b3da-3ddee86d62b3.
    void
    appendUuid7​(boolean lowerCase)
    Generates and appends a random version 7 UUID.
    void
    clear()
    Removes all characters from the current StringBuilder instance.
    boolean
    contains​(String str, boolean caseSensitive)
    Returns true if the str is contained within this object.
    boolean
    containsWord​(String word, boolean caseSensitive)
    Returns true if the word is contained within this object, but only if it is a whole word.
    boolean
    contentsEqual​(String str, boolean caseSensitive)
    Returns true if the contents of this object equals the str.
    boolean
    contentsEqualSb​(StringBuilder sb, boolean caseSensitive)
    Returns true if the contents of this object equals the sb.
    void
    decode​(String encoding, String charset)
    Decodes and replaces the contents with the decoded string.
    void
    decodeAndAppend​(String value, String encoding, String charset)
    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.
    void
    encode​(String encoding, String charset)
    Encodes to base64, hex, quoted-printable, URL encoding, etc.
    boolean
    endsWith​(String substr, boolean caseSensitive)
    Returns true if the string ends with substr.
    void
    entityDecode()
    Decodes HTML entities.
    String
    getAfterBetween​(String searchAfter, String beginMark, String endMark)
    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.
    String
    getAfterFinal​(String marker, boolean removeFlag)
    Returns the substring found after the final occurrence of marker.
    String
    getAsString()
    Returns the contents as a string.
    String
    getBefore​(String marker, boolean removeFlag)
    Returns the substring found before the 1st occurrence of marker.
    String
    getBetween​(String beginMark, String endMark)
    Returns the substring found between the 1st occurrence of beginMark and the next occurrence of endMark.
    String
    getEncoded​(String encoding, String charset)
    Returns the string contents encoded in an encoding such as base64, hex, quoted-printable, or URL-encoding.
    boolean
    getHasEmojis()
    Returns true if the content contains one or more emoji characters.
    String
    getHash​(String algorithm, String encoding, String charset)
    Returns the hash of the contents of this object.
    int
    getIntValue()
    Returns the content of the string converted to an integer.
    boolean
    getIsBase64()
    Returns true if the content contains only those characters allowed in the base64 encoding.
    int
    getLength()
    The number of characters of the string contained within this instance.
    String
    getNth​(int index, String delimiterChar, boolean exceptDoubleQuoted, boolean exceptEscaped)
    Returns the Nth substring in string that is a list delimted by delimiterChar.
    String
    getRange​(int startIndex, int numChars, boolean removeFlag)
    Returns a string containing the specified range of characters from this instance.
    void
    getRangeSb​(int startIndex, int numChars, boolean removeFlag, StringBuilder sb)
    Appends to startIndex the specified range of characters from this instance.
    void
    htmlToMarkdown()
    Converts the HTML contained in this object to Markdown, replacing the contents with the Markdown.
    boolean
    isWellFormed​(String format)
    Returns true if the contents of this object are well-formed JSON or XML.
    String
    lastNLines​(int numLines, boolean bCrlf)
    Returns the last N lines of the text.
    void
    loadFile​(String path, String charset)
    Loads the contents of a file.
    void
    markdownToHtml​(JsonObject options, StringBuilder sbHtml)
    This method converts the Markdown content of this object to HTML, storing the result in sbHtml.
    void
    maskQuotedStrings​(String maskChar, int quoteType, StringTable maskedStrings)
    This function masks the content inside single and/or double-quoted strings by replacing it with a specified mask character (maskChar).
    void
    obfuscate()
    Obfuscates the string.
    void
    prepend​(String value)
    Prepends a copy of the specified string to this instance.
    void
    punyDecode()
    In-place decodes the string from punycode.
    void
    punyEncode()
    In-place encodes the string to punycode.
    int
    regexMatch​(String pattern, JsonObject json, int timeoutMs)
    Searches the content of this object for substrings that match a regular expression pattern and returns the matches in json.
    void
    regexReplace​(JsonObject json)
    Replaces the substrings of capture groups found in a previous call to RegexMatch.
    void
    removeAccents()
    Removes the accents (diacritics) from European accented characters.
    void
    removeAfterFinal​(String marker)
    Removes the substring found after the final occurrence of the marker.
    void
    removeBefore​(String marker)
    Removes the substring found before the 1st occurrence of the marker.
    void
    removeCharsAt​(int startIndex, int numChars)
    Removes the specified range of characters from this instance.
    void
    removeEmojis()
    Removes all emoji characters from the string.
    int
    replace​(String value, String replacement)
    Replaces all occurrences of a specified string in this instance with another specified string.
    void
    replaceAfterFinal​(String marker, String replacement)
    Replaces the content found after the final occurrence of marker with replacement.
    void
    replaceAllBetween​(String beginMark, String endMark, String replacement, boolean replaceMarks)
    Replaces the first occurrence of ALL the content found between beginMark and endMark with replacement.
    int
    replaceBetween​(String beginMark, String endMark, String value, String replacement)
    Replaces all occurrences of value with replacement, but only where value is found between beginMark and endMark.
    void
    replaceFirst​(String value, String replacement)
    Replaces the first occurrence of a specified string in this instance with another string.
    int
    replaceI​(String value, int replacement)
    Replaces all occurrences of value with the decimal integer replacement.
    int
    replaceNoCase​(String value, String replacement)
    Replaces all occurrences of value with replacement (case insensitive).
    int
    replaceWord​(String value, String replacement)
    Replaces all word occurrences of a specified string in this instance with another specified string.
    void
    restoreMaskedStrings​(int quoteType, StringTable maskedStrings)
    Restores single and/or double-quoted strings previously masked by MaskQuotedStrings.
    void
    secureClear()
    Removes all characters from the current StringBuilder instance, and write zero bytes to the allocated memory before deallocating.
    void
    setIntValue​(int value)
    Sets the IntValue property; see getIntValue().
    void
    setNth​(int index, String value, String delimiterChar, boolean exceptDoubleQuoted, boolean exceptEscaped)
    Sets the Nth substring in string in a list delimted by delimiterChar.
    void
    setString​(String value)
    Sets this instance to a copy of the specified string.
    void
    shorten​(int numChars)
    Shortens the string by removing the last numChars chars.
    boolean
    startsWith​(String substr, boolean caseSensitive)
    Returns true if the string starts with substr.
    void
    toCRLF()
    Converts line endings to CRLF (Windows) format.
    void
    toLF()
    Converts line endings to LF-only (UNIX) format.
    void
    toLowercase()
    Converts the contents to lowercase.
    void
    toUppercase()
    Converts the contents to uppercase.
    void
    trim()
    Trims whitespace from both ends of the string.
    void
    trimInsideSpaces()
    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.
    void
    unobfuscate()
    Unobfuscates the string.
    void
    writeFile​(String path, String charset, boolean emitBom)
    Writes the contents to a file.
    void
    writeFileIfModified​(String path, String charset, boolean emitBom)
    Writes the contents to a file, but only if it is a new file or if the contents are different than the existing file.

    Methods inherited from class com.chilkatsoft.chilkat2.ChilkatObject

    close, getDebugLogFilePath, getLastErrorHtml, getLastErrorText, getLastErrorXml, getLastMethodSuccess, getVerboseLogging, getVersion, isClosed, setDebugLogFilePath, setLastMethodSuccess, setVerboseLogging, toString

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

  • Constructor Details

    • StringBuilder

      public StringBuilder()
      Creates a new StringBuilder object.

  • Method Details

    • getHasEmojis

      public boolean getHasEmojis()
      Returns true if the content contains one or more emoji characters.
      Returns:
      the value of the HasEmojis property (read-only)

    • getIntValue

      public int getIntValue()
      Returns the content of the string converted to an integer.
      Returns:
      the value of the IntValue property

    • setIntValue

      public void setIntValue​(int value)
      Sets the IntValue property; see getIntValue().
      Parameters:
      value - the new value

    • getIsBase64

      public boolean getIsBase64()
      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.
      Returns:
      the value of the IsBase64 property (read-only)

    • getLength

      public int getLength()
      The number of characters of the string contained within this instance.
      Returns:
      the value of the Length property (read-only)

    • append

      public void append​(String value)
      Appends a copy of the specified string to this instance.
      Parameters:
      value - the value argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • appendBd

      public void appendBd​(BinData binData, String charset, int offset, int numBytes)
      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.
      Parameters:
      binData - the binData argument (not null)
      charset - the charset argument (not null)
      offset - the offset argument
      numBytes - the numBytes argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • appendInt

      public void appendInt​(int value)
      Appends the string representation of a specified 32-bit signed integer to this instance.
      Parameters:
      value - the value argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • appendInt64

      public void appendInt64​(long value)
      Appends the string representation of a specified 64-bit signed integer to this instance.
      Parameters:
      value - the value argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • appendLine

      public void appendLine​(String str, boolean crlf)
      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.
      Parameters:
      str - the str argument (not null)
      crlf - the crlf argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • appendLn

      public void appendLn​(String str)
      Appends the str followed by a CRLF to the end of this object. This method is the same as appendLine(String, boolean) , except the line-ending is always CRLF.
      Parameters:
      str - the str argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • appendRandom

      public void appendRandom​(int numBytes, String encoding)
      Append numBytes random bytes encoded according to encoding. encoding can be hex, hex_lower, base64, base64url, or any other encoding supported by Chilkat.
      Parameters:
      numBytes - the numBytes argument
      encoding - the encoding argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • appendSb

      public void appendSb​(StringBuilder sb)
      Appends the contents of another StringBuilder to this instance.
      Parameters:
      sb - the sb argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • appendUuid

      public void appendUuid​(boolean lowerCase)
      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.

      Parameters:
      lowerCase - the lowerCase argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • appendUuid7

      public void appendUuid7​(boolean lowerCase)
      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).
      Parameters:
      lowerCase - the lowerCase argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • clear

      public void clear()
      Removes all characters from the current StringBuilder instance.

    • contains

      public boolean contains​(String str, boolean caseSensitive)
      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.
      Parameters:
      str - the str argument (not null)
      caseSensitive - the caseSensitive argument
      Returns:
      the result; this method never throws ChilkatException

    • containsWord

      public boolean containsWord​(String word, boolean caseSensitive)
      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.

      Parameters:
      word - the word argument (not null)
      caseSensitive - the caseSensitive argument
      Returns:
      the result; this method never throws ChilkatException

    • contentsEqual

      public boolean contentsEqual​(String str, boolean caseSensitive)
      Returns true if the contents of this object equals the str. Returns false if unequal. For case insensitive equality, set caseSensitive equal to false.
      Parameters:
      str - the str argument (not null)
      caseSensitive - the caseSensitive argument
      Returns:
      the result; this method never throws ChilkatException

    • contentsEqualSb

      public boolean contentsEqualSb​(StringBuilder sb, boolean caseSensitive)
      Returns true if the contents of this object equals the sb. Returns false if unequal. For case insensitive equality, set caseSensitive equal to false.
      Parameters:
      sb - the sb argument (not null)
      caseSensitive - the caseSensitive argument
      Returns:
      the result; this method never throws ChilkatException

    • decode

      public void decode​(String encoding, String charset)
      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.

      Parameters:
      encoding - the encoding argument (not null)
      charset - the charset argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • decodeAndAppend

      public void decodeAndAppend​(String value, String encoding, String charset)
      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.
      Parameters:
      value - the value argument (not null)
      encoding - the encoding argument (not null)
      charset - the charset argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • encode

      public void encode​(String encoding, String charset)
      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.
      Parameters:
      encoding - the encoding argument (not null)
      charset - the charset argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • endsWith

      public boolean endsWith​(String substr, boolean caseSensitive)
      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.
      Parameters:
      substr - the substr argument (not null)
      caseSensitive - the caseSensitive argument
      Returns:
      the result; this method never throws ChilkatException

    • entityDecode

      public void entityDecode()
      Decodes HTML entities. See HTML entities for more information about HTML entities.
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getAfterBetween

      public String getAfterBetween​(String searchAfter, String beginMark, String endMark)
      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.
      Parameters:
      searchAfter - the searchAfter argument (not null)
      beginMark - the beginMark argument (not null)
      endMark - the endMark argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getAfterFinal

      public String getAfterFinal​(String marker, boolean removeFlag)
      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.

      Parameters:
      marker - the marker argument (not null)
      removeFlag - the removeFlag argument
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getAsString

      public String getAsString()
      Returns the contents as a string.
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getBefore

      public String getBefore​(String marker, boolean removeFlag)
      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.

      Parameters:
      marker - the marker argument (not null)
      removeFlag - the removeFlag argument
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getBetween

      public String getBetween​(String beginMark, String endMark)
      Returns the substring found between the 1st occurrence of beginMark and the next occurrence of endMark.
      Parameters:
      beginMark - the beginMark argument (not null)
      endMark - the endMark argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getEncoded

      public String getEncoded​(String encoding, String charset)
      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.

      Parameters:
      encoding - the encoding argument (not null)
      charset - the charset argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getHash

      public String getHash​(String algorithm, String encoding, String charset)
      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.

      Parameters:
      algorithm - the algorithm argument (not null)
      encoding - the encoding argument (not null)
      charset - the charset argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getNth

      public String getNth​(int index, String delimiterChar, boolean exceptDoubleQuoted, boolean exceptEscaped)
      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.
      Parameters:
      index - the index argument
      delimiterChar - the delimiterChar argument (not null)
      exceptDoubleQuoted - the exceptDoubleQuoted argument
      exceptEscaped - the exceptEscaped argument
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getRange

      public String getRange​(int startIndex, int numChars, boolean removeFlag)
      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.

      Parameters:
      startIndex - the startIndex argument
      numChars - the numChars argument
      removeFlag - the removeFlag argument
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getRangeSb

      public void getRangeSb​(int startIndex, int numChars, boolean removeFlag, StringBuilder sb)
      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.
      Parameters:
      startIndex - the startIndex argument
      numChars - the numChars argument
      removeFlag - the removeFlag argument
      sb - the sb argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • htmlToMarkdown

      public void htmlToMarkdown()
      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(JsonObject, StringBuilder). 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.

      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • isWellFormed

      public boolean isWellFormed​(String format)
      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.

      Parameters:
      format - the format argument (not null)
      Returns:
      the result; this method never throws ChilkatException

    • lastNLines

      public String lastNLines​(int numLines, boolean bCrlf)
      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.
      Parameters:
      numLines - the numLines argument
      bCrlf - the bCrlf argument
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • loadFile

      public void loadFile​(String path, String charset)
      Loads the contents of a file.
      Parameters:
      path - the path argument (not null)
      charset - the charset argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • markdownToHtml

      public void markdownToHtml​(JsonObject options, StringBuilder sbHtml)
      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 "_LT_!DOCTYPE html>"
        • "rootElement": "root_element" The html element. The default is "_LT_html>"
        • "head": "head_section" The HTML fragment for the HTML head section. The default is "_LT_head>_LT_meta charset="utf-8" />_LT_/head>".
          Note: If usesPrism is true, then prism related links will be inserted just before the _LT_/head>.
        • "bodyStart": "html_fragment" The HTML fragment to begin the body section. The default is "_LT_body>_LT_div id="content">"
        • "bodyEnd": "html_fragment" The HTML fragment to end the body section. The default is "_LT_/div>_LT_!-- end-of-content-div -->_LT_/body>"
        • "noContentDiv": true If set, the default bodyStart and bodyEnd do not include the "_LT_div id="content">" and "_LT_/div>_LT_!-- 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.

      Parameters:
      options - the options argument (not null)
      sbHtml - the sbHtml argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • maskQuotedStrings

      public void maskQuotedStrings​(String maskChar, int quoteType, StringTable maskedStrings)
      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.

      Parameters:
      maskChar - the maskChar argument (not null)
      quoteType - the quoteType argument
      maskedStrings - the maskedStrings argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • obfuscate

      public void obfuscate()
      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.

    • prepend

      public void prepend​(String value)
      Prepends a copy of the specified string to this instance.
      Parameters:
      value - the value argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • punyDecode

      public void punyDecode()
      In-place decodes the string from punycode.
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • punyEncode

      public void punyEncode()
      In-place encodes the string to punycode.
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • regexMatch

      public int regexMatch​(String pattern, JsonObject json, int timeoutMs)
      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.
      Parameters:
      pattern - the pattern argument (not null)
      json - the json argument (not null)
      timeoutMs - the timeoutMs argument
      Returns:
      the result (see ChilkatObject.getLastMethodSuccess() where the description mentions failure)

    • regexReplace

      public void regexReplace​(JsonObject json)
      Replaces the substrings of capture groups found in a previous call to RegexMatch.
      Parameters:
      json - the json argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • removeAccents

      public void removeAccents()
      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.
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • removeAfterFinal

      public void removeAfterFinal​(String marker)
      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.
      Parameters:
      marker - the marker argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • removeBefore

      public void removeBefore​(String marker)
      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.
      Parameters:
      marker - the marker argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • removeCharsAt

      public void removeCharsAt​(int startIndex, int numChars)
      Removes the specified range of characters from this instance.
      Parameters:
      startIndex - the startIndex argument
      numChars - the numChars argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • removeEmojis

      public void removeEmojis()
      Removes all emoji characters from the string.

    • replace

      public int replace​(String value, String replacement)
      Replaces all occurrences of a specified string in this instance with another specified string. Returns the number of replacements.
      Parameters:
      value - the value argument (not null)
      replacement - the replacement argument (not null)
      Returns:
      the result (see ChilkatObject.getLastMethodSuccess() where the description mentions failure)

    • replaceAfterFinal

      public void replaceAfterFinal​(String marker, String replacement)
      Replaces the content found after the final occurrence of marker with replacement.
      Parameters:
      marker - the marker argument (not null)
      replacement - the replacement argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • replaceAllBetween

      public void replaceAllBetween​(String beginMark, String endMark, String replacement, boolean replaceMarks)
      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.
      Parameters:
      beginMark - the beginMark argument (not null)
      endMark - the endMark argument (not null)
      replacement - the replacement argument (not null)
      replaceMarks - the replaceMarks argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • replaceBetween

      public int replaceBetween​(String beginMark, String endMark, String value, String replacement)
      Replaces all occurrences of value with replacement, but only where value is found between beginMark and endMark. Returns the number of replacements made.
      Parameters:
      beginMark - the beginMark argument (not null)
      endMark - the endMark argument (not null)
      value - the value argument (not null)
      replacement - the replacement argument (not null)
      Returns:
      the result (see ChilkatObject.getLastMethodSuccess() where the description mentions failure)

    • replaceFirst

      public void replaceFirst​(String value, String replacement)
      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.
      Parameters:
      value - the value argument (not null)
      replacement - the replacement argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • replaceI

      public int replaceI​(String value, int replacement)
      Replaces all occurrences of value with the decimal integer replacement. Returns the number of replacements.
      Parameters:
      value - the value argument (not null)
      replacement - the replacement argument
      Returns:
      the result (see ChilkatObject.getLastMethodSuccess() where the description mentions failure)

    • replaceNoCase

      public int replaceNoCase​(String value, String replacement)
      Replaces all occurrences of value with replacement (case insensitive). Returns the number of replacements.
      Parameters:
      value - the value argument (not null)
      replacement - the replacement argument (not null)
      Returns:
      the result (see ChilkatObject.getLastMethodSuccess() where the description mentions failure)

    • replaceWord

      public int replaceWord​(String value, String replacement)
      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.)

      Parameters:
      value - the value argument (not null)
      replacement - the replacement argument (not null)
      Returns:
      the result (see ChilkatObject.getLastMethodSuccess() where the description mentions failure)

    • restoreMaskedStrings

      public void restoreMaskedStrings​(int quoteType, StringTable maskedStrings)
      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.

      Parameters:
      quoteType - the quoteType argument
      maskedStrings - the maskedStrings argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • secureClear

      public void secureClear()
      Removes all characters from the current StringBuilder instance, and write zero bytes to the allocated memory before deallocating.

    • setNth

      public void setNth​(int index, String value, String delimiterChar, boolean exceptDoubleQuoted, boolean exceptEscaped)
      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.
      Parameters:
      index - the index argument
      value - the value argument (not null)
      delimiterChar - the delimiterChar argument (not null)
      exceptDoubleQuoted - the exceptDoubleQuoted argument
      exceptEscaped - the exceptEscaped argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setString

      public void setString​(String value)
      Sets this instance to a copy of the specified string.
      Parameters:
      value - the value argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • shorten

      public void shorten​(int numChars)
      Shortens the string by removing the last numChars chars.
      Parameters:
      numChars - the numChars argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • startsWith

      public boolean startsWith​(String substr, boolean caseSensitive)
      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.
      Parameters:
      substr - the substr argument (not null)
      caseSensitive - the caseSensitive argument
      Returns:
      the result; this method never throws ChilkatException

    • toCRLF

      public void toCRLF()
      Converts line endings to CRLF (Windows) format.
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • toLF

      public void toLF()
      Converts line endings to LF-only (UNIX) format.
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • toLowercase

      public void toLowercase()
      Converts the contents to lowercase.
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • toUppercase

      public void toUppercase()
      Converts the contents to uppercase.
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • trim

      public void trim()
      Trims whitespace from both ends of the string.
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • trimInsideSpaces

      public void trimInsideSpaces()
      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.
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • unobfuscate

      public void unobfuscate()
      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.

    • writeFile

      public void writeFile​(String path, String charset, boolean emitBom)
      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.)
      Parameters:
      path - the path argument (not null)
      charset - the charset argument (not null)
      emitBom - the emitBom argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • writeFileIfModified

      public void writeFileIfModified​(String path, String charset, boolean emitBom)
      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.)
      Parameters:
      path - the path argument (not null)
      charset - the charset argument (not null)
      emitBom - the emitBom argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why