GAMBAS BOOK 3.19.1

The arsenal of functions for manipulating strings in gambas is manifold. Gambas has two sets of string manipulation functions. One set for manipulating ASCII strings and another that can handle UTF-8 strings.

Note the following notes if you use the character string or string functions of both sets:

• The terms string and string are used synonymously.
• Many string functions can only handle ASCII strings.
• To manipulate UTF-8 strings, use the equivalent methods of the (static) string class specified in the following table under UTF8.
• If you are editing a string to be translated, you must use the UTF-8 functions of the string class.
• The (UTF-8-)string class must be distinguished from the native data type string.
• If no UTF-8 equivalent string function is specified, the string function manipulates both ASCII strings and UTF-8 strings. Be careful, be careful! Gambas uses the UTF-8 character set internally, so a character code larger than 128 does not have the same meaning as ISO 8859-1.

Table 9.8.1.1: Overview of string functions

The scan function splits a string using a regular expression (LIKE format). In the following example, the command 'df' (disk free) is used without parameters and provides information about the disk space on all mounted file systems:

Dim sResult, sLine, sElementAs String
Shell "df" To sResult
For Each sLine In Split(sResult, "\n")
  For Each sElement In Scan(sLine, "* * * * *")
    Print sElement; " | ";
  Next ' sElement
  Print
Next ' sLine

Output in the console of the IDE:

Datasystem | 1K-Blocks | Used | Available | Used% Mounted on |
|---------------------------------------------------------------------|
/dev/sda6   | 50395844  | 10974228 | 36861616  | 23%   /              |
udev        | 4037720   | 4        | 4037716   | 1%    /dev           |
tmpfs       | 809308    | 944      | 808364    | 1%    /run           |
none        | 5120      | 0        | 5120      | 0%    /run/lock      |
none        | 4046520   | 156      | 4046364   | 1%    /run/shm       |
/dev/sda7   | 218656644 | 57277676 | 150271848 | 28%   /home          |

If you call a program with the shell instruction, the command line can quickly become complicated if you pass many arguments that are variables in the Gambas process. For example, we consider the program “tar”as it is called in the patch dialogs of the Gambas IDE.

The “Generate Patch”dialog asks for the path of an old source code archive from which a patch for the state of the current project is to be generated. In order for the “patch”program to work on the sources, the archive must be unpacked. This is done by means of “tar”:

Shell "tar -" & sType & "xf "  & Shell$(sOldSource) & " -C " &sOld &  " --strip-components=1"

If you now use the function Subst$ () instead of the & concatenations, you will see its meaning later on:

Shell Subst$("tar -&1xf &2 -C &3 --strip-components=1", sType, Shell$(sOldSource), sOld)

The Subst$ () function is the method of choice when you assemble strings in your translatable project from variables and string constants, such as in this case:

Message(("The Server ") & sServer & (" reports: everything OK!"))

Message(Subst$(("The Server &1 reports: everything OK!"), sServer))

Here, the translator himself can choose the syntax for his own language by moving the placeholder &1 appropriately.

Note: If you use more than 9 substrings, for example, you have to place the (predefined) substring in braces {&10} instead of &10.

You can use the Split(string[, Separators, Escape, IgnoreVoid, KeepEscape] function) to split a string into individual strings if the substrings are separated by separators and (optional) are delimited by escape characters. This function returns a string array containing each recognized substring.

• String is the string that is divided into substrings at all specified separators from the list of separators.
• Separator is a comma-separated list of separators. By default, the' comma' is used as a separator.
• Escape is an escape character. Only 1-byte ASCII characters may be used. By default, no escape character is specified. A maximum of 2 escape characters can be used. If 2 escape characters are used, the first is the start escape character and the second character is the end escape character.
• All separators enclosed between two escape characters are ignored when splitting. This makes it possible, for example, to use a number with a comma in a substring, even if the separator is a comma!
• IgnoreVoids is of the data type Boolean. The default setting is False. If the value is True, empty substrings are ignored when splitting.
• KeepEscape is also of the Boolean type. The default setting is False. If the value is True, the escape characters are returned in the substring.
• The separator characters are not returned in the substring. The escape characters are only returned in the substring if the value of KeepEscape is set to False.
• If the string itself contains escape characters, these escape characters must be duplicated.
• You cannot use the Split function to split a string of non-ASCII characters.

This source code:

sInput = "(12,3 )*()+(789),(    def)*(45,76)+     (a b c)"

Print "String  : (12,3 )*()+(789),(    def)*(45,76)+     (a b c)"
Print "Funktion: Split(sInput, \"+,*\", \"()\", IgnoreVoid, KeepEscape)"
Print String$(61, "-") & gb.NewLine
Print "IgnoreVoid = False, KeepEscape = False"
aStringFieldArray = Split(sInput, "+,*", "()", False, False)
For k = 0 To aStringFieldArray.Max
   Print "k = "; k; "  ~>  "; Trim(aStringFieldArray[k])
Next
Print "IgnoreVoid = True, KeepEscape = False"
aStringFieldArray = Split(sInput, "+,*", "()", True, False)
For k = 0 To aStringFieldArray.Max
  Print "k = "; k; "  ~>  "; Trim(aStringFieldArray[k])
Next
Print "IgnoreVoid = False, KeepEscape = True"
aStringFieldArray = Split(sInput, "+,*", "()", False, True)
For k = 0 To aStringFieldArray.Max
  Print "k = "; k; "  ~>  "; Trim(aStringFieldArray[k])
Next
Print "IgnoreVoid = True, KeepEscape = True"
aStringFieldArray = Split(sInput, "+,*", "()", True, True)
For k = 0 To aStringFieldArray.Max
  Print "k = "; k; "  ~>  "; Trim(aStringFieldArray[k])
Next

produces these editions in the console of the Gambas IDE:

IgnoreVoid = False, KeepEscape = False
k = 0  ~>  12,3
k = 1  ~>
k = 2  ~>  789
k = 3  ~>  def
k = 4  ~>  45,76
k = 5  ~>  a b c

IgnoreVoid = True, KeepEscape = False
k = 0  ~>  12,3
k = 1  ~>  789
k = 2  ~>  def
k = 3  ~>  45,76
k = 4  ~>  a b c

IgnoreVoid = False, KeepEscape = True
k = 0  ~>  (12,3 )
k = 1  ~>  ()
k = 2  ~>  (789)
k = 3  ~>  (    def)
k = 4  ~>  (45,76)
k = 5  ~>  (a b c)

IgnoreVoid = True, KeepEscape = True
k = 0  ~>  (12,3 )
k = 1  ~>  ()
k = 2  ~>  (789)
k = 3  ~>  (    def)
k = 4  ~>  (45,76)
k = 5  ~>  (a b c)

The next section of the source code shows you how to use selected string functions:

Public Sub btnStringManipulationen_Click()
  Dim iCount, k As Integer
  Dim sCommand As String = "Open"
  Dim sZK As String = "Today is the "
  Dim sLine, sInput, sText, sMessage1, sMessage2 As String
  Dim aStringFieldArray, aDateArray As String[]
  Dim aVariantFieldArray, vElement As Variant[]
  Dim vVariant As Variant
  Dim aCSV As New Variant[][]
  Dim hFile As File

  Print "ASC(\"Tobias\") = "; Asc("Tobias"), "ASC(\"Tobias\",2) = "; Asc("Tobias", 2)
  Print "ASC(\"ö\") = "; Asc("ö")
  Print "STRING.CODE(\"Anger\") = "; String.Code("Anger"); " ("; Hex(String.Code("Anger")); " hex)"
  Print "BASE64(\"Tobias\") = "; Base64("Tobias"), "UNBASE64(\"VG9iaWFz\") = "; UnBase64("VG9iaWFz")
  Print "CHR(66) = "; Chr(66), "STRING.CHR(246) = "; String.Chr(246)
  Print "Line 1"; Chr(10); "Line 2"
  If Comp(Upper(sCommand), "OPEN") = 0 Then Print "The file is opened!"
  Print "Html(\"Anger in the office...\")  "; Html("Anger in the office...")

  Print "The string 'bas' was found at Pos "; InStr("Gambas as Basic dialect.", "bas"); " for the first time."
  Print IIf(Comp(Lower(sCommand), "open") = 0, "The file is opened!", "Error!")
  Print "Lower(\"Anger?\") = "; Lower("Anger?"); "  String.Lower(\"Anger!\") = "; String.Lower("Anger!")
  If Comp(Upper(sCommand), "OPEN") = 0 Then Print "The File is opened!"
  Print Left("Hans-Joachim", 4), Left("Hans-Joachim"), Left("Hans-Joachim", -8)
  Print Mid("Gambas-Book", 8), Mid("Gambas-Book", 4, 5), Mid("Gambas-Book", 2, -5)
  Mid$(sZK, Len(sZK) + 1) = Format(Now(), "d. mmmm yyyy!")
  Print sZK; gb.NewLine

  sInput = "-3.88+4.275i"
  With Scan(sInput, "*+*i")
    Print "    Realpart =", .[0]; " (z = "; sInput; ")"
    Print "Imaginarypart = ", .[1]; " (z = "; sInput; ")"
  End With
  Print
  Print "Eight spaces between < and >: "; "<"; Space(8); ">"
  Print "Original: "; "\"   That is - not only with gambas - Standard!   \""
  Print "LTRIM: "; "<"; LTrim("   That is - not only with gambas - Standard!   "); ">"
  Print "TRIM: "; "<"; Trim("   That is - not only with gambas - Standard!   "); ">"
  Print "RTRIM: "; "<"; RTrim("   That is - not only with gambas - Standard!   "); ">"
  Print "Byte Number 'Gambas' = "; Len("Gambas"); "  Byte Number 'Äöü' = "; Len("Äöü")

  Print "Position of 'bas' in 'Gambas is basic' with RInstr(..) = "; RInStr("Gambas is basic", "bas")
  Print "Pos of 'bas' in 'Gambas is basic' with RInstr(..) from Pos 10="; RInStr("Gambas is basic","bas", 10)

  sText = "Gambas is basic"
  sMessage1 = "Text 'BAS' in '" & sText & "' found!"
  sMessage2 = "Text 'BAS' in '" & sText & "' not found!"
  Print IIf(RInStr(sText, "BAS", gb.IgnoreCase), sMessage1, sMessage2)
  Print "Replaces + in '+123.45 with ZERO-String: "; Replace("+123.45", "+", "")
  Print String$(11, "-----")
  Print Subst("Today is &1. &2", Format(Now(), "dddd"), "Isn't that beautiful?")
  Print "Number of lines (TextArea) = "; Split(TextArea1.Text, gb.NewLine).Count
  Wait 3
  Print
  Print Quote("This is a 'multi-Line' string." & gb.NewLine)

  TextArea1.Clear
  hFile = Open "example.csv" For Input
  While Not Eof(hFile)
    Line Input #hFile, sLine
    TextArea1.Insert(sLine & gb.NewLine)
    aStringFieldArray = New String[] ' A new array is used for each line
    aStringFieldArray = Split(sLine, ",", "\"", False, False)

    aVariantFieldArray = New Variant[]
    For iCount = 0 To aStringFieldArray.Max
      If IsFloat(aStringFieldArray[iCount]) Then
         aStringFieldArray[iCount] = Replace(aStringFieldArray[iCount], ",", ".")
         aVariantFieldArray.Add(CFloat(aStringFieldArray[iCount]))
      Else If IsBoolean(aStringFieldArray[iCount]) Then
         aVariantFieldArray.Add(aStringFieldArray[iCount])
      Else If IsDate(aStringFieldArray[iCount]) Then
         aDateArray = Split(aStringFieldArray[iCount], ".")
         aVariantFieldArray.Add(Date(aDateArray[2], aDateArray[1], aDateArray[0]))
       ' aVariantFieldArray.Add(Val(aStringFieldArray[iCount])) ' Quick Alternative
      Else
         aVariantFieldArray.Add(aStringFieldArray[iCount])
      Endif
    Next
    aCSV.Add(aVariantFieldArray)
   Wend

   Print
   For Each vElement In aCSV
        For Each vVariant In vElement
            If IsDate(Str(vVariant)) Then
               Print Format(vVariant, "dd.mm.yyyy")
            Else
               Print vVariant,
            Endif
        Next ' vVariant
   Next ' sElement
End ' StringManipulationen

This is the content of the csv file example. csv:

"8,03","False","FIRST","24.06.2014"
"58,1","True","Peter","23.02.2015"
"66,3","True","Paula","08.08.2015"
"83,1","False","Anna","14.01.2015"
"13,8","True","Thomas","04.02.2014"
"-8,9","False","Peter","07.05.2015"
"8,95","True","Paul","21.09.2013"
"52,5","True","Peter","23.02.2015"
"16,7","True","LATEST","08.04.2015"

Here you can see the generated outputs:

ASC("Tobias") = 84
ASC("Tobias",2) = 111
ASC("ö") = 195
STRING.CODE("Anger") = 196 (C4 hex)
BASE64("Tobias") = VG9iaWFz
UNBASE64("VG9iaWFz") = Tobias
CHR(66) = B
STRING.CHR(246) = ö
Line 1
Line 2
The file is opened!
Html(" Anger in the office...") Anger in the office...
The search string 'bas' was found for the first time at position 4.
The file is opened!
Lower(" Anger?") = Anger?
String.Lower(" Anger!") = anger!
The file is opened!
Hans    H       Hans
Book    bas-B   Gambas
Today is the 29. June 2014!

Realpart =  -3.88 (z = -3.88+4.275i)
Imaginarypart =  4.275 (z = -3.88+4.275i)

Eight spaces between < and >: <        >
Original: "   This is - not only with Gambas - standard!   "
LTRIM: <This is - not only with Gambas - standard!   >
TRIM: <This is - not only for Gambas - standard!>
RTRIM: <   This is - not only for Gambas - standard!>
Number of bytes 'Gambas' = 6 Number of bytes 'Äöü' = 6
Position of 'bas' in 'Gambas is basic' with RInstr(..) = 11
Position of 'bas' in 'Gambas is basic' with RInstr(..) from position 10 = 4
Text 'BAS' in 'Gambas is basic' not found!
Replace + in '+123.45 with ZERO-String: 123.45
-------------------------------------------------------
Today is Sunday. Isn't that nice?
Number of lines (TextArea) = 9

"This is a 'multi-Line' string.\n"

8,03    False   FIRST  24.06.2014
58,1    True    Peter   23.02.2015
66,3    True    Paula   08.08.2015
83,1    False   Anna    14.01.2015
13,8    True    Thomas  04.02.2014
-8,9    False   Peter   07.05.2015
8,95    True    Paul    21.09.2013
52,5    True    Peter   23.02.2015
16,7    True    LATEST 08.04.2015