Chapter 6: String Routines

Overview

This chapter introduces the subroutines and functions supported by OpenOffice.org Basic that are related to strings. This includes functions to manipulate strings, convert other data types to strings, and to perform special formatting.

Text data is stored in strings as a sequence of 16-bit unsigned integer Unicode version 2.0 values. The Unicode Worldwide Character Standard is a set of binary codes representing textual or script characters designed because ASCII, the original standard, can handle only 256 distinct characters. The first 128 characters (numbered 0 through 127) correspond to the letters and symbols on a standard U.S. keyboard. The next 128 characters (numbered 128 through 255) consist of special characters such as accent marks, Latin-based characters, and a few symbols. The remaining 65,280 values-of which only about 34,000 are currently used-are used for a wide variety of worldwide text characters, mathematical symbols, accent marks (diacritics), and technical symbols.

OpenOffice.org has a large number of functions that allow you to manipulate strings. These string-manipulation operations range from converting uppercase to lowercase (or vice versa) to selecting substrings out of a longer string. The functions listed in Table 1 are the string functions covered in this chapter. The functions listed in Table 2 are related to strings as well as either numerical or array manipulations; these are covered in other chapters.

Table 1: These string-related functions are covered in this section.

Function	Description
ASC(str)	Return the integer ASCII value of the first character in the string. This supports 16-bit Unicode values as well.
CHR(n)	Convert an ASCII number to a character.
CStr(obj)	Convert standard types to a string.
Format(obj, format)	Fancy formatting; works only for strings.
Hex(n)	Return the hexadecimal representation of a number as a string.
InStr(str, str) InStr ( start, str, str) InStr(start, str, str, mode)	Attempt to find string 2 in string 1. Returns 0 if not found and starting location if it is found. The optional start argument indicates where to start looking. The default value for mode is 1 (case-insensitive comparison). Setting mode to 0 performs a case-sensitive comparison.
Join(s()) Join(s(), str)	Concatenate the array elements, separated by the optional string delimiter, and return the value as a string. The default delimiter is a single space. Inverse of the Split function.
LCase(str)	Return a lowercase copy of the string.
Left(str, n)	Return the leftmost n characters from the string.
Len(str)	Return the length of the string.
LSet str1 = str2	Left-justify a string into the space taken by another string.
LTrim(str)	Return a copy of the string with all leading spaces removed.
Mid(str, start) Mid(str, start, len) Mid(str, start, len, str)	Return the substring, starting at start. If the length is omitted, the entire end of the string is returned. If the final string argument is included, this replaces the specified portion of the first string with the last string.
Oct(n)	Return the octal representation of a number as a string.
Right(str, n)	Return the rightmost n characters.
RSet str1 = str2	Right-justify a string into the space taken by another string.
RTrim(str)	Return a copy of the string with all trailing spaces removed.
Space(n)	Return a string with the number of specified spaces.
Split(str) Split(str, str)	Split a string into an array based on an optional delimiter. Inverse of the Join function.
Str(n)	Convert a number to a string with no localization.
StrComp(s1, s2) StrComp(s1, s2, mode)	Compare two strings returning -1 , 0, or 1 if the first string is less than, equal to, or greater than the second in alphabetical order. Set the optional third argument to zero for a case-insensitive comparison. The default is 1 for a case-sensitive comparison.
String(n, char) String(n, ascii)	Return a string with a single character repeated multiple times. The first argument is the number of times to repeat; the second argument is the character or ASCII value.
Trim(str)	Return a copy of the string with all leading and trailing spaces removed.
UCase(str)	Return an uppercase copy of the string.
Val(str)	Convert a string to a double. This is very tolerant to non-numeric text.

Table 2: These string-related functions are covered in other chapters.

Function	Covered In	Description
Join(s()) Join(s(), str)	Chapter 4	Split a string into an array based on an optional delimiter. This is the inverse of the Join function.
Split(str) Split(str, str)	Chapter 4	Split a string into an array based on an optional delimiter.
CStr(obj)	Chapter 3	Convert standard types to a string.
Str(n)	Chapter 3	Convert a number to a string with no localization.
Hex(n)	Chapter 3	Return the hexadecimal representation of a number as a string.
Oct(n)	Chapter 3	Return the octal representation of a number as a string.
Val(str)	Chapter 3	Convert a string to a double. This is very tolerant to non-numeric text.

The subroutines and functions related to string handling in OOo Basic are listed in Table 1. Some of these functions (see Table 2) have in-depth coverage in other chapters, because they are directly related to the content in those chapters. They are covered briefly near the end of this chapter, in the section titled "Converting data to a string."