strbuf.h | documentation |
#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?); }
TADS 3 Library Manual
Generated on 5/16/2013 from TADS version 3.1.3
Generated on 5/16/2013 from TADS version 3.1.3