Back to Contents

The StringBuffer class

Summary:

See also: Built-in classes

Basics

Purpose:

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 position pos (starts at 1). Returns NULL if the position does not match a character 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 position spos. Returns zero if the sub-string was not found.
getLength( )
  RETURNING INTEGER		 Returns the number of characters of the current string, including trailing spaces.
subString( spos INTEGER, epos INTEGER )
  RETURNING STRING		 Returns the sub-string starting at spos and ending at epos. Returns NULL if the positions do not delimit a sub-string in the current string. First character position is 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 position pos for len characters.  First character 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 position pos. First character position is 1.
toString( ) RETURNING STRING Creates a STRING value from the current buffer.

Usage:

This class is provided to reference a character string. It is optimized for string operations.

Warnings:

  1. Do not confuse StringBuffer with the STRING data type: 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 STRING.append() method, the runtime system creates a new buffer to hold the new string. When using a StringBuffer object, you modify the current buffer. This class is particularly useful in writing library functions.
  2. When you pass a StringBuffer object as function parameter, the function gets a variable that references the string buffer object. This means that the function manipulates the original string, not a copy of the string as if it was a STRING variable.

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