Back to Contents

The StringBuffer class

Summary:

See also: Built-in classes

Syntax

The StringBuffer class is a built-in class designed to manipulate character strings.

Syntax:

base.StringBuffer

Methods:

Class Methods
Name Description
create( )
  RETURNING base.StringBuffer		 Creates a new empty StringBuffer object.
Object Methods
Name Description
append( str STRING ) Appends a string to the string buffer.
clear( ) Clears the string buffer.
equals( src STRING )
  RETURNING INTEGER		 Returns TRUE if the string passed as parameter matches the current string. If one of the strings is NULL the method returns FALSE.
equalsIgnoreCase( src STRING )
  RETURNING INTEGER		 Returns TRUE if the string passed as parameter matches the current string, ignoring character case. If one of the strings is NULL the method returns FALSE.
getCharAt( pos INTEGER )
  RETURNING STRING		 Returns the character at the byte position pos (starts at 1). Returns NULL if the position does not match a valid character-byte position in the current string.
getIndexOf( str STRING, spos INTEGER )
  RETURNING INTEGER		 Returns the position of the sub-string str in the current string, starting from byte position spos. Returns zero if the sub-string was not found.
getLength( )
  RETURNING INTEGER		 Returns the number of bytes of the current string, including trailing spaces.
subString( spos INTEGER, epos INTEGER )
  RETURNING STRING		 Returns the sub-string starting at the byte position spos and ending at epos. Returns NULL if the positions do not delimit a valid sub-string in the current string. First character-byte starts at 1.
toLowerCase( ) Converts the current string to lowercase.
toUpperCase( ) Converts the current string to uppercase.
trim( ) Removes white space characters from the beginning and end of the current string.
trimLeft( ) Removes white space characters from the beginning of the current string.
trimRight( ) Removes white space characters from the end of the current string.
replaceAt( pos INTEGER, len INTEGER, str STRING ) Replaces a part of the current string by another string, starting from byte position pos for len bytes.  First character-byte position is 1.
replace( oldString STRING, newString STRING, occ INTEGER ) Replaces in the current string the STRING oldString by the STRING newString, occ time(s) (all occurrences, if occ set to 0). 
insertAt( pos INTEGER, str STRING ) Inserts a string before the byte position pos. First character-byte position is 1.
toString( ) RETURNING STRING Creates a STRING value from the current buffer.

Usage:

Create a StringBuffer object with the base.StringBuffer.create() class method.

The StringBuffer class is optimized for string operations. When using a StringBuffer object, you work directly on the internal string buffer. Use the StringBuffer class to implement heavy string manipulations. For example, if you need to process 500Kb of text (such as when you are performing a global search-and-replace of specific words), you get much better performances with a StringBuffer object than you would using a basic STRING variable.

Warning: The StringBuffer methods are all based on byte-semantics. In a multi-byte environment, the getLength() method returns the number of bytes, which can be different from the number of characters.

When you pass a StringBuffer object as function parameter, the function receives a variable that references the StringBuffer object. Passing the StringBuffer object by reference is much more efficient than using a STRING that is passed by value (i.e. data is copied on the stack). The function manipulates the original string, not a copy of the string as if it was a STRING variable.

A StringBuffer object has different semantics than a STRING variable: When using the STRING data type, the runtime system always creates a new buffer when you modify a string.

For example, when you concatenate strings with the append() method of a STRING variable, the runtime system creates a new buffer to hold the new string. This does not impact performances of programs with a user interface or even batch programs doing SQL, but can be an issue when you want to rapidly process large character strings.

The append() method appends a string to the string  buffer.

The clear() method clears the string buffer.

The equals() method compares two strings.

The equalsIgnoreCase() method compares two strings ignoring case.

The getCharAt( ) method returns the character at the specified position.

The getIndexOf() method returns the position of the specified substring.

The getLength() method returns the number of bytes in the current string.

The subString() method returns the substring at the specified position.

The toLowerCase() method converts the current string to lowercase.

The toUpperCase() method converts the current string to uppercase.

The trim() method removes white space from the beginning and end of the current string.

The trimLeft() method removes white space from the beginning of the current string.

The trimRight()method removes white space from the end of the current string.

The replaceAt() method freplaces part of the current string with another string.

The replace()  method replaces the current string with another string.

The insertAt() method inserts a string before the specified position.

The toString() method creates a STRING value from the current buffer.

Examples

Example 1: Adding strings to a StringBuffer.

01 MAIN
02   DEFINE buf base.StringBuffer
03   LET buf = base.StringBuffer.create()
04   CALL buf.append("abc")
05   DISPLAY buf.toString()
06   CALL buf.append("def")
07   DISPLAY buf.toString()
08   CALL buf.append(123456)
09   DISPLAY buf.toString()
10 END MAIN

Example 2: Modifying a StringBuffer with a function.

01 MAIN
02   DEFINE buf base.StringBuffer
03   LET buf = base.StringBuffer.create()
04   CALL modify(buf)
05   DISPLAY buf.toString()
06 END MAIN
07
08 FUNCTION modify(sb)
09   DEFINE sb base.StringBuffer
10   CALL sb.append("more")
11 END FUNCTION