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

Latest revision as of 12:09, 30 January 2021

>]]

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.

Case conversion

Apache OpenOffice Basic provides two functions to convert lowercase characters in a string to uppercase and vice-versa.

LCase(MyString)

converts all letters in MyString to lowercase. Only uppercase letters within the string are converted. All lowercase letters and nonletter characters remain unchanged.

UCase(MyString)

converts all letters in MyString to uppercase. Only lowercase letters within the string are converted. All uppercase letters and nonletter characters remain unchanged.

Accessing Parts of a String

Apache OpenOffice Basic provides four functions that return partial strings, plus a length function:

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.

Trim(MyString)

removes all leading and trailing spaces from MyString.

Len(MyString)

returns the number of characters in MyString.

Unlike array subscripts, character positions in a string start with 1. 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"
MyResult = Trim("   String with spaces   ") ' Provides the string "String with spaces"
MyLen = Len(MyString)            ' Provides the value 20

Search and Replace

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

PositionOfMatch = InStr(MyString, StringToFind)

The StringToFind parameter specifies the string to be searched for within MyString. The function returns a number that contains the position at which the StringToFind first appears within MyString; a return value of zero indicates no match. 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:

PositionOfMatch = InStr(StartPosition, MyString, StringToFind)

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:

PositionOfMatch = InStr(MyString, StringToFind, 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 NewPart 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")

Or this much simpler function can be used. First it splits "Source" dividing it at all "Search", and joins the parts back with "NewPart". So Replace("This is a test", " ", "_") yields "This_is_a_test" :D

Function Replace(Source As String, Search As String, NewPart As String)
  Dim Result As String  
  Result = join(split(Source, Search), NewPart)
  Replace = Result
End Function

When it is used with 4 arguments, to replace a sub-string in a string, Mid is an instruction, not a function : it does not return any value !

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 placeholder within the template ensures that this item is formatted correspondingly in the output value. The five most important placeholders 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 characters 0 and . 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 $ placeholder, the Format function displays the relevant currency symbol defined by the system (this example assumes a European locale has been defined):

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 €"

The format instructions used in VBA for formatting date and time details can also be used:

sub main
    dim myDate as date
    myDate = "01/06/98"
    TestStr = Format(myDate, "mm-dd-yyyy") ' 01-06-1998
    MsgBox TestStr
end sub