Difference between revisions of "Documentation/BASIC Guide/Strings (Runtime Library)"

Revision as of 13:25, 2 April 2008

>]]

Working with Sets of Characters

When administering strings, Apache OpenOffice Basic uses the set of Unicode characters. The Asc and Chr functions allow the Unicode value belonging to a character to be established and/or the corresponding character to be found for a Unicode value. The following expressions assign the various Unicode values to the code variable:

Code = Asc("A")         ' Latin letter A (Unicode-value 65)
Code = Asc("€")         ' Euro character (Unicode-value 8364)
Code = Asc("л")         ' Cyrillic letter л (Unicode-value 1083)

Conversely, the expression

MyString = Chr(13)

ensures that the MyString string is initialized with the value of the number 13, which stands for a hard line break.

The Chr command is often used in Basic languages to insert control characters in a string. The assignment

MyString = Chr(9) + "This is a test" + Chr(13)

therefore ensures that the text is preceded by a tab character (Unicode-value 9) and that a hard line break (Unicode-value 13) is added after the text.

Accessing Parts of a String

Apache OpenOffice Basic provides four functions that return partial strings:

Left(MyString, Length)

returns the first Length characters of MyString.

Right(MyString, Length)

returns the last Length characters of MyString.

Mid(MyString, Start, Length)

returns first Length characters of MyString as of the Start position.

Len(MyString)

returns the number of characters in MyString.

Here are a few example calls for the named functions:

Dim MyString As String
Dim MyResult As String
Dim MyLen As Integer
 
MyString = "This is a small test"
MyResult = Left(MyString,5)      ' Provides the string "This "
MyResult = Right(MyString, 5)    ' Provides the string " test"
MyResult = Mid(MyString, 8, 5)   ' Provides the string " a sm"
MyLen = Len(MyString)            ' Provides the value 21

Search and Replace

Apache OpenOffice Basic provides the InStr function for searching for a partial string within another string:

ResultString = InStr (MyString, SearchString)

The SearchString parameter specifies the string to be searched for within MyString. The function returns a number that contains the position at which the SearchString first appears within MyString. If you want to find other matches for the string, the function also provides the opportunity to specify an optional start position from which Apache OpenOffice Basic begins the search. In this case, the syntax of the function is:

ResultString = InStr(StartPosition, MyString, SearchString)

In the previous examples, InStr ignores uppercase and lowercase characters. To change the search so that InStr is case sensitive, add the parameter 0, as shown in the following example:

ResultString = InStr(MyString, SearchString, 0)

Using the previous functions for editing strings, programmers can search for and replace one string in another string:

Function Replace(Source As String, Search As String, NewPart As String)
  Dim Result As String
  Dim StartPos As Long
  Dim CurrentPos As Long
 
  Result = ""
  StartPos = 1
  CurrentPos = 1
 
  If Search = "" Then
    Result = Source
  Else 
    Do While CurrentPos <> 0
      CurrentPos = InStr(StartPos, Source, Search)
      If CurrentPos <> 0 Then
        Result = Result + Mid(Source, StartPos, _
        CurrentPos - StartPos)
        Result = Result + NewPart
        StartPos = CurrentPos + Len(Search)
      Else
        Result = Result + Mid(Source, StartPos, Len(Source))
      End If                ' Position <> 0
    Loop 
  End If 
 
  Replace = Result
End Function

The function searches through the transferred Search string in a loop by means of InStr in the original term Source. If it finds the search term, it takes the part before the expression and writes it to the Result return buffer. It adds the new Part section at the point of the search term Search. If no more matches are found for the search term, the function establishes the part of the string still remaining and adds this to the return buffer. It returns the string produced in this way as the result of the replacement process.

Since replacing parts of character sequences is one of the most frequently used functions, the Mid function in Apache OpenOffice Basic has been extended so that this task is performed automatically. The following example replaces three characters with the string is from the sixth position of the MyString string.

Dim MyString As String
 
MyString = "This was my text"
Mid(MyString, 6, 3, "is")

Formatting Strings

The Format function formats numbers as a string. To do this, the function expects a Format expression to be specified, which is then used as the template for formatting the numbers. Each place holder within the template ensures that this item is formatted correspondingly in the output value. The five most important place holders within a template are the zero (0), pound sign (#), period (.), comma (,) and dollar sign ($) characters.

The 0 character within the template ensures that a number is always placed at the corresponding point. If a number is not provided, 0 is displayed in its place.

A . stands for the decimal point symbol defined by the operating system in the country-specific settings.

The example below shows how the 0 and . characters can define the digits after the decimal point in an expression:

MyFormat = "0.00"
MyString = Format(-1579.8, MyFormat)     ' Provides "-1579,80"
MyString = Format(1579.8, MyFormat)      ' Provides "1579,80"
MyString = Format(0.4, MyFormat)         ' Provides "0,40"
MyString = Format(0.434, MyFormat)       ' Provides "0,43"

In the same way, zeros can be added in front of a number to achieve the desired length:

MyFormat = "0000.00"
MyString = Format(-1579.8, MyFormat)     ' Provides "-1579,80"
MyString = Format(1579.8, MyFormat)      ' Provides "1579,80"
MyString = Format(0.4, MyFormat)         ' Provides "0000,40"
MyString = Format(0.434, MyFormat)       ' Provides "0000,43"

A , represents the character that the operating system uses for a thousands separator, and the # stands for a digit or place that is only displayed if it is required by the input string.

MyFormat = "#,##0.00"
MyString = Format(-1579.8, MyFormat)   ' Provides "-1.579,80"
MyString = Format(1579.8, MyFormat)      ' Provides "1.579,80"
MyString = Format(0.4, MyFormat)      ' Provides "0,40"
MyString = Format(0.434, MyFormat)      ' Provides "0,43"

In place of the $ place holder, the Format function displays the relevant currency symbol defined by the system:

MyFormat = "#,##0.00 $"   
MyString = Format(-1579.8, MyFormat)   ' Provides "-1.579,80 —" 
MyString = Format(1579.8, MyFormat)      ' Provides "1.579,80 —" 
MyString = Format(0.4, MyFormat)      ' Provides "0,40 —" 
MyString = Format(0.434, MyFormat)      ' Provides "0,43 —"

Template:Documentation/Note