#charset "us-ascii"
#pragma once
/*
* Copyright 2009 Michael J. Roberts.
*
* This file is part of TADS 3.
*
* This module defines the StringBuffer intrinsic class. StringBuffer is
* essentialy a mutable version of String: you can append, insert, replace,
* and delete characters in place, without creating new objects as a
* result. This is useful for complex string constructions that involve
* many incremental steps, since it avoids the repeated memory allocation
* and string copying operations that would be involved if the intermediate
* steps were performed with ordinary String objects.
*/
/*
* A StringBuffer is a mutable character string object. You can insert,
* append, delete, and replace characters in the buffer in place. These
* operations don't create new objects as they do with ordinary strings,
* but simply modify the existing StringBuffer object's contents.
*
* The object manages memory automatically. When you first create the
* object, it allocates an initial buffer to hold its character contents.
* You can specify the initial buffer size with a constructor argument, or
* simply let the object pick a default. As you add text to the buffer,
* the object automatically allocates more memory as needed to accommodate
* the added text. The maximum size for the string contained in the buffer
* is about 32000 characters.
*
* Construction: new StringBuffer() creates a buffer with default initial
* size values. new StringBuffer(length, increment) specifies the initial
* buffer size in characters ('length'), and the minimum number of
* characters to add to the buffer each time it's automatically expanded
* ('increment').
*
* Passing a StringBuffer to an internal function or method that takes a
* String argument, such as tadsSay(), will automatically convert the
* object to a string. To explicitly convert a StringBuffer to an ordinary
* String, use the toString() function. You can also create an ordinary
* string from a section of the buffer using the substr() method.
*/
intrinsic class StringBuffer 'stringbuffer/030000'
{
/*
* Get the length in characters of the current text in the buffer.
*/
length();
/*
* Retrieve the Unicode character value of the character at the given
* index. Returns an integer with the Unicode value. If idx is
* negative, it's an index from the end of the string: -1 is the last
* character, -2 is the second to last, etc.
*/
charAt(idx);
/*
* Append text to the current contents of the buffer. This adds the
* new text at the end of the current text. The value is automatically
* converted to a string if possible; this includes numbers and
* true and nil values.
*/
append(str);
/*
* Insert text into the buffer just before the character at the given
* index. The first character is at index 1, so to insert the new text
* before the first current character, insert at index 1. If the index
* is past the end of the current text, this has the same effect as
* append(). A negative value indexes from the end of the string. The
* text is automatically converted to a string if possible.
*/
insert(txt, idx);
/*
* Copy text into the buffer, starting at the given index (the first
* character in the buffer is at index 1). Overwrites any text
* currently in the buffer at this point.
*/
copyChars(txt, idx);
/*
* Delete the given text. This deletes 'len' characters starting at
* the given index (the first character is at index 1). If the length
* is omitted, the portion from idx to the end of the string is
* deleted. A negative idx value indexes from the end of the string.
*/
deleteChars(idx, len?);
/*
* Splice text. This deletes 'len' characters starting at the given
* index (the first character is at index 1), and replaces them with
* the given new text. If the new text is nil, this simply deletes the
* old characters without inserting anything new. If 'len' is zero,
* simply inserts the new text without deleting any old text. A
* negative idx value indexes from the end of the string. The 'str'
* value is automatically converted to a string if possible.
*/
splice(idx, len, str);
/*
* Retrieve the substring of the buffer starting at the given index and
* running for the given character length. If the length is omitted,
* everything from the starting index to the end of the buffer is
* included in the result string. A negative value for 'idx' indexes
* from the end of the string.
*/
substr(idx, len?);
}
Adv3Lite Library Reference Manual
Generated on 03/07/2024 from adv3Lite version 2.1