Welcome to B4AScript
B4AScript is based upon the syntax of Basic4ppc, a .NET based development tool for Windows desktop and Windows Mobile device software development. Basic4ppc was a product of Anywhere Software and was the spiritual predecessor to Basic4Android and subsequently the B4X development suite. Within this help file B4AScript may also be referred to as B4Script.
B4AScript is a runtime scripting language implemented in the BasicLib B4A library and intended for incorporation into applications written using B4A. It is a sub-set of the full Basic4ppc language with only minor variations in syntax. A very similar BasicLib library is available for incorporation into Basic4ppc applications. The language implementation under Basic4ppc is termed B4PScript.
There are slight differences between the B4AScript and B4PScript implementations owing to the different underlying platforms on which they are implemented. These differences are in the use of the Format, DateFormat and TimeFormat keywords.
In B4PScript DateFormat and TimeFormat use the .NET Framework DateTime class whereas in B4AScript date and time formats are specified by date and time pattern strings as implemented by the Java SimpleDateFormat class.
In B4PScript Format uses the .NET Framework Double.Parse method whereas in B4AScript formats are specified by the formatting rules for a Java DecimalFormat object.
Thanks to Erel Uziel at Anywhere Software for permitting this help file to be based upon the help for Basic4ppc.
Version 2.0 (c) Erel Uziel & Andrew Graham : 2012-2020
In B4Script statements, operations and names are case-insensitive.
A program starts with an initial code section at the beginning of the program. All Subs must follow this code section. Execution commences at the first line of the program and ends when AppClose is executed or if the code tries to run off the end of this initial section into the first Sub.
Variable and Sub names must start with a letter and may contain letters, numbers, underscores ( _ ) and sharps ( # ). Variables, except for arrays, do not need to be explicitly declared. Any variables used in the initial (non Sub) section of code are global variables and are accessible from within any Sub. Any variables used for the first time in a Sub that are not global are local to that Sub. A local variable name may not be the same as a global variable name so, because parameter names are local names, if a global name is used as a parameter name in a Sub definition then an error occurs. Global variables can of course be passed as parameters and all parameters are passed as values.
All global variables can be Dimmed as multi-dimension arrays of up to three dimensions as many times as required anywhere in the program. Variable "A()" or "A" is always equivalent "A(0)" , "A(0, 0)", "A(0, 0, 0)"or "A()". Where an array reference, as opposed to the value of an array element, is required then A or A() or A(x) are all accepted. Local variables can never be arrays. Multi-dimensioned arrays may also be accessed as single dimensioned arrays using the length returned by ArrayTotalLen or GetTotalLen when an array name is passed as a parameter.
For convenience arrays may be addressed by the "." convention, Array.Variable, where the variable contains the required index into the array. Variables used in this way may be any local or global variables. This facility is provided to emulate the Basic4pp structure and the Dim Type(...) statement is also provided. However despite the syntax being the same as Basic4ppc the implementation differs. In Basic4ppc the indexer names declared by "Type" are constants associated only with that array. In B4Script the indexers are in fact true local or global variables with their values automatically assigned so care needs to be taken not to unwittingly use the indexer names as normal variable names unless this is what is really intended.
Although arrays, as opposed to the value of a single item of an array, cannot be passed as parameters the same functionality can be achieved by passing the array name and then using GetItem, GetLen, GetRank, GetTotalLen and SetItem which provide indirect access to an array specified at runtime.
There is a pre-defined global array, Args(), that contains an argument array passed to the script at runtime.
Strings can be either single or double quotes delimited. The opening delimiter is matched with the closing delimiter allowing the use of the other delimiter within a string literal.
var = "a 'string' within a string"
var = 'a "string" within a string'
Literal numbers are accepted in decimal form with an optional decimal point or can be specified in scientific notation.
var = 1.234
var = 123.4E-2
Unlike B4PScript hexadecimal literals are not supported in B4AScript. However the Script module in the B4A BasicIDE project, that implements an on device IDE for B4AScript, provides the extension functions IntToHex and IntFromHex to transform Int32 values to and from hexadecimal strings.
Only multi-line If statements are allowed. That is:
If Something Then
DoSomething
End If
Single line If statements like this are not supported:
If Something Then DoSomething
Rem is provided for comments but must start a statement on a new line.
# at the beginning of a line is interpreted as a Rem keyword.
The colon statement separator is not supported. Only one statement per line is allowed.
Global variables are always cleared to an empty string at the the start of program execution. Local variables are not guaranteed to be be cleared and so should always be explicitly initialised by the program if this is important.
Select ... End Select structures cannot be directly nested. That is code in a Case may not contain another Select ... End Select although it is permissible to call a Sub that does contain another Select ... End Select structure.
Goto can only be used to jump within a scope or to an outer scope. That is it cannot be used to jump into a For...Next, Do...Loop, If...End If or Select ... End Select structure. It is permissible to jump over or out of such structures but not land within them.
Errors are reported back to the host application and will usually be reported to the user. Most errors are self-explanatory but if the error is "Index was outside the bounds of the array" and it does not seem to be associated with an actual array access statement then an unterminated string is the likely cause.
For historical reasons there are two date/time format specifiers, DateFormat used by the DateParse subroutine and TimeFormat used by the TimeParse subroutine. In the present implementation of the interpreter DateParse and TimeParse function identically and both can parse both dates and times. In B4AScript parsing is according to the rules used by the Java SimpleDateFormat class parse() method.
Subs declarations start with Sub SubName (Parameters) and end with "End Sub".
If there are no parameters for the sub, then write "Sub SubName" without the parentheses. Because parameter names are local names if a global name is used as a parameter name in a Sub definition then an error occurs.
There are no functions in B4Script but instead every Sub can return a value with the keyword "Return".
All parameters are passed by value. That is if an assignment is made to a parameter variable it only alters the value of that local variable and not that of the original variable.
"EndSub" is also accepted in place of "End Sub"
Calling a sub
To call a sub, write its name followed by an opening parenthesis and the parameters separated by "," followed by a closing parenthesis. If there are no parameters then do not write any parentheses.
Example:
Sub ShowMean
Msgbox("The mean of 20 and 30 is " & crlf & Mean(20,30))
End Sub
Sub Mean (a, b)
Return (a+b)/2
End Sub
Result: A message box that displays 25.
All simple variables are variant variables. Which means that any variable can store any type of number or a string. Variables can be global or local. Local variable values can be used only while their parent sub is executing. Global variable values can be used everywhere.
Variable names must begin with a letter, 'A' to 'Z' or 'a' to 'z' or an underscore '_'. Names can include letters, numbers underscores and sharps, '#'.
Except for array variables, there is no need to declare a variable before using it.
Global variables are variables that are declared or used outside a Sub in the main code body, all other variables are local. A point to beware of is that the same variable names may be unwittingly, particularly if simply named like i or j, used as local variables. Normally the fact that these are global is immaterial but if, for example, i is used as a For loop index in the initial code block and so becomes global, and a Sub called by an event uses i as a For loop index and a Sub called within that For loop also uses i as a For loop index then problems will arise. It is recommended to use some prefix for non-array global variables that identify them as such to avoid such problems.
To pass data between Subs you could use global variables, or better, you can pass the data as parameters. When using parameters the variable is not passed, but its value is copied. Remember that if you change a local variable value in one place (even if it had received its data from a parameter), then the change will not affect any other variable outside the current sub.
Array Variables
B4Script supports arrays with up to three dimensions. All global variables can be Dimmed as multi-dimension arrays of up to three dimensions as many times as required anywhere in the program. Variable "A()" or "A" is always equivalent "A(0)" , "A(0, 0)", "A(0, 0, 0)"or "A()". Where an array reference, as opposed to the value of an array element, is required then A or A() or A(x) are all accepted. Local variables can never be arrays.
Multi-dimensioned arrays may also be accessed as single dimensioned arrays using the length returned by ArrayTotalLen or GetTotalLen when an array name is passed as a parameter. When accessed by a single dimension the rightmost rank specifier of the multi-dimension Dim statement is the least significant. i.e. the fastest changing, dimension whose items will be adjacent to each other when accessed as a single dimension array.
Although arrays, as opposed to the value of a single item of an array, cannot be passed as parameters the same functionality can be achieved by passing the array name and then using GetItem, GetLen, GetRank, GetTotalLen and SetItem which provide indirect access to an array specified at runtime.
Declare array variables with the "Dim" keyword.
See "Array" for a convenient method of initializing arrays. The same array can be declared again with a different size and rank any number of times during the program.
An array index starts from 0 and its last index is array dimensions - 1.
Example:
Dim Books (20)
Dim Buffer (100)
Result: Declares an array of 20 items starting from Books(0) and up to Books(19) and an array of items starting from Buffer(0) and up to Buffer(99)
When you need to reference an entire array (not one item in the array) write the array name alone or followed by ().
Example:
Array(buffer(),1 ,2 ,3)
or
Array(buffer,1 ,2 ,3)
Structure Variables
Structure variables are actually arrays with a convenient access mechanism for the rightmost dimension of the arrays. They are declared using "Dim Type" and may have an additional two dimensions specified in addition to the dimension implied by the indexing variables.
For convenience any array may be addressed by the "." convention, "Array.Variable", where the variable contains the required index into the array. Array.LiteralNumber is also accepted. Variables used in this way may be any local or global variables. The "Dim Type(...) "statement is provided to automatically define and initialise variables for this use but any variable, array variable element or numeric literal may be used. These automatically defined indexer variables are local or global variables, depending upon where the Type statement is invoked. and whether a global variable of that name already exists. Once their values are automatically assigned by "Dim Type" care needs to be taken not to unwittingly assign different values to the indexer variables unless this is what is really intended.
See the help entry for "Dim Type" under "Keywords -> General" for more information.
B4Script supports the following operators:
^ Exponent (power) operator
+,-,*,/ Basic math operators
Mod Modulus operator
& String concatenation
AND Logical AND of logical values
OR Logical OR of logical values
BitAnd Bitwise AND of integer values
BitOr Bitwise OR of integer values
BitXor Bitwise XOR of integer values
Rem Remarks, the line is ignored
The precedence of operators, including the conditional operators is as follows, highest first. All operators listed on the same line associate left to right. Parentheses can be used to group expressions to force a different order of evaluation. Such parenthesised expressions can be nested and are evaluated from inner to outer. In fact it is good practice to not rely upon operator precedence for more complex expressions but to explicitly parenthesise those expressions to explicitly indicate the required order of execution.
1) ^
2) * / Mod
3) & + - BitAnd BitOr BitXor
4) < > = <> >= <=
5) AND OR
The conditional operators supported are
< Less than
> Greater than
<> Not equal
= Equal
<= Less than or equal
>= Great than or equal
Two binary operators are supported: AND and OR, and one unary operator is supported: NOT.
A simple condition expression evaluates to one of the boolean values: true or false. The simple conditions can be combined into a more complex condition using the logical operators and using parentheses. Conditions are not "short-circuit" conditions. This means that the expressions will always be evaluated in full even if they cannot affect the result.
Note that the internal values for true and false are "true" and "false", both lower case. The keywords True and False without quotes and regardless of case return the strings "true" and "false" respectively. So
Var = TRUE
Var = true
Var = "true"
are all true for comparison purposes but
Var = "True"
is not as it is not a lower case string.
Boolean values can be used directly.
Enable = true
Example:If Enable then ...
Example: If True then ...
The NOT operator is a function and must have its target included within parentheses.
Enable = true
Example: If NOT (a = b OR a = b/2) Then ...
Example: If NOT (Enable) Then ...
Reading the arguments passed to the script at runtime is done using a special built-in array named Args.
Use "Arraylen" to find the number of arguments available.
Example:
For i = 0 To ArrayLen(args())-1
Msgbox(args(i))
Next
Terminates the program
Syntax:
AppClose
Returns the number that represents a certain color.
Syntax:
ARGB (A, R, G, B)
Example:
White = RGB (255, 255,255,255)
The Array keyword is used to initialize arrays and structures with the specified data. It supports arrays of one dimension only.
Syntax:
Array (DestArray, Array Elements)
Example:
Array(Primes, 1,2,3,5,7,11,13,17,19)
Rem Primes is now an array of length 9
Copies part of the source array to the target array.
Syntax:
ArrayCopy (Source Array, Source Start, Count, Target Array, Target Start)
Source Array - The items will be copied from this array.
Source Start - The first item that will be copied.
Count - Number of items to copy.
Target Start - The position in the target of the first copied item.
Example:
ArrayCopy (buffer(), 0, ArrayLen (buffer()), target(), 0)
Returns the length (size) of a single specified dimension of an array. If the dimension is omitted the default is 1, the leftmost dimension.
Syntax:
ArrayLen (Array [, Dimension])
Example:
Dim items(5,10)
...
i = ArrayLen (items)
Returns the number of dimensions of an array. Possible values are 1, 2 or 3.
Syntax:
ArrayRank (Array)
Example:
Dim items(5,10)
...
i = ArrayRank(items)
Returns the total length (size) of an array including all the dimensions. This is the length used to access the array as a single dimension array.
Syntax:
ArrayTotalLen (Array)
Example:
Dim arr(5,10)
...
For i = 0 To ArrayTotalLen (items) -1
arr(i) = i
Next
The CallHostSub statement and function allow B4A host program subroutines to be directly called from within a B4Script. However if the script is being run on a thread other than the main GUI thread then subroutines that manipulate Graphical User Interface elements must not be directly called using CallHostSub. In this case CallHostGuiSub must be used. If this help file has been supplied with a finished B4A application then there should be other documentation supplied that will detail the subroutine names that may be used by CallHostSub together with their parameters and a description of their functionality.
Syntax:
CallHostSub (Sub Name [, Arguments List])
Sub Name - A string that holds the target sub name.
Arguments List - List of arguments passed to the sub (separated by commas).
Example statement:
CallHostSub("SubWithOneParam", 12345)
Example function:
ret = CallHostSub("DoSomethingWithThis", 12345)
The CallHostGuiSub statement and function allows B4A host program subroutines that manipulate Graphical User Interface elements to be directly called from within a B4Script but necessarily provides somewhat lower performance than using CallHostSub. If this help file has been supplied with a finished B4A application then there should be other documentation supplied that will detail the subroutine names that may be used by CallHostGuiSub together with their parameters and a description of their functionality.
Syntax:
CallHostGuiSub (Sub Name [, Arguments List])
Sub Name - A string that holds the target sub name.
Arguments List - List of arguments passed to the sub (separated by commas).
Example statement:
CallGuiHostSub("SubWithOneParam", 12345)
Example function:
ret = CallHostGuiSub("DoSomethingWithThis", 12345)
CallSub allows you to dynamically call a sub, which means that the called sub is only known at runtime.
Syntax:
CallSub (Sub Name [, Arguments List])
Sub Name - A string that holds the target sub name.
Arguments List - List of arguments passed to the sub (separated by commas).
Example:
For i = 1 to 3
If CallSub("SomeSub" & i, arg1, arg2, arg3) > 10 Then
...
End If
Next
Declares array variables. When declaring arrays, remember that the array's index starts from 0 and its last index is array length - 1. Array variables and structures can only be global and therefore must first be declared in the initial source code block. Array variables can then be re-declared anywhere in any Sub in the program. The same array can be re-declared many times and its size can be changed. You can use ArrayLen to find the length (size) of an array. Arrays of up to three dimensions may be declared.
While arrays cannot be passed as parameters to Sub and received as return values they can be indirectly accessed by GetItem, GetLength and SetItem which accept an array name as a string to identify the array. This allows an array name to be passed as a parameter to a Sub to define the array that the Sub should manipulate.
Syntax:
Dim VariableName(Length1[, Length2 [, Length3]] )
Example:
Dim items(10, 3, 2)
Declares structure variables, which are actually arrays. The Dim Type(...) statement is provided to automatically define and initialise indexer variables for use with the array.variable syntax that can be used to access array elements. These indexer variables are local or global variables, depending upon where the Type statement is invoked. and whether a global variable of that name already exists. Once their values are automatically assigned by Type care needs to be taken not to unwittingly assign different values to the indexer variables unless this is what is really intended.
The leftmost variable in the Type statement corresponds to index 0 into the array, the next index one and so on. The array length is the number of indexers declared in the Type statement. Arrays of up to two dimensions of structures may be declared.
While arrays cannot be passed as parameters to Sub and received as return values they can be indirectly accessed by GetItem, GetLength and SetItem which accept an array name as a string to identify the array. This allows an array name to be passed as a parameter to a Sub to define the array that the Sub should manipulate.
Syntax:
Dim Type(indexer0, indexer1 ...)VariableName[(Length1[, Length2])]
Example:
Dim Type(name, address1, address2)items(10, 2)
...
mailitem.name(3, 1) = "Fred"
Do ... Loop While | Until is similar to Do While | Until ... Loop with the difference that the condition is checked at the end of the loop and not at the beginning.
The loop will be executed at least once.
Syntax:
Do
...
Loop While | Until conditon
Example:
Do
i = i + 1
Loop Until i = 10
Loops until a condition is true.
Syntax:
Do Until condition
...
...
Loop
Example:
Do Until i = 10
i = i + 1
Loop
Loops while a condition is true.
Syntax:
Do While condition
...
...
Loop
Example:
Do While i < 10
i=i+1
Loop
Exits For, While, Until loops.
In case of nested loops Exit will exit only the last level.
Syntax:
Exit
Example:
For n = 1 to 100
If n = 50 Then
Exit
End If
Next
Loop statement that changes a variable value. The loop ends when the variable is greater than the end value if Step is positive or less than the end value if Step is negative. Step may be omitted in which case the step value is 1.
Syntax:
For variable = Value To Value [Step Value]
Example:
For i = 10 To 0 Step -1
Msgbox (i)
Next
Result: It will display a countdown from 10 to 0
GetItem allows you to dynamically access the elements of an array determined at runtime rather than at compile time. It accepts the name of the array as a string or variable together with the index of the required element. GetItem treats a multi-dimension array as a single dimension array. Array indices for multi-dimensioned arrays may be calculated using GetRank, and get GetLen. GetTotalLen returns the total size of the array when regarded as a single dimensioned array.
Syntax:
GetItem(ArrayName, Index)
Example:
arr = "array1"
index = 23
val = GetItem(arr, index)
Returns the length (size) of a single specified dimension of an array specified at runtime. If the dimension is omitted the default is 1, the leftmost dimension.
Syntax:
GetLen (ArrayName [, Dimension])
Example:
Dim items(5,10)
...
i = GetLen ("items")
GetTotalLen allows you to dynamically access the total number of elements of an array specified at runtime rather than at compile time. It accepts the name of the array as a string or variable and returns the length of that array. It returns the same value as ArrayTotalLen.
Syntax:
GetTotalLen(ArrayName)
Example:
arr = "array1"
len = GetTotalLen(arr)
Returns the number of dimensions of an array specified at runtime. Possible values are 1, 2 or 3.
Syntax:
GetRank (ArrayName)
Example:
Dim items(5,10)
...
i = GetRank("items")
These four functions each return either the tranparency value, Alpha, or one of the three color components of a color.
Syntax:
GetR(Color)
Example:
A = GetA(Color) ' Alpha
R = GetR(Color) ' Red
G = GetG(Color) ' Green
B = GetB(Color) ' Blue
Goto causes the execution of the program to move to a predefined label. Label syntax is a word starting with a letter and ending with a colon. When the program reaches the Goto keyword execution will move to the specified line of code. B4Script doesn't allow jumps between different subs, and the target label must be in a scope equal or wider to the calling Goto. That is it cannot be used to jump into a For...Next, Do...Loop or If...End If structure. It is permissible to jump over such structures but not land within them.
Syntax:
Goto Label
Label - the destination line of code of the jump identified as a name as the fist word of the line of code terminated by a colon. Further code can follow on the same line if required.
Example:
Sub Button1_Click
...
StartingPlace:
...
Goto StartingPlace
End Sub
If statements must be multiline. Multiple "Else If" intermediate conditions are supported. "ElseIf" and "EndIf" are also accepted in place of "Else If" and "End If".
Syntax:
If Condition Then
...
Else If Condition Then
...
Else If AnotherCondition Then
...
Else
...
End If
The Msgbox statement takes one or two parameters and passes them to the host application. The result of that depends upon how that applications decides to deal with the data passed to it. Usually this action will be to display a message box to the user with the first parameter as the message and the second parameter, if any, as the message box title. Examples in this help file using the Msgbox statement assume this.
Syntax:
MsgBox(Data1 [,Data2])
Returns the opposite of the given value.
Syntax:
Not (True | False)
Example:
Checked = True
Checked = Not (Checked)
Rem Checked is now False
The Print statement formats a string and passes the result to the host application. The result of that depends upon how that application decides to deal with the data passed to it. Print accepts multiple items to print separated by either a semi-colon or a comma. Semi-colon causes the following item to be concatenated with the previous item, comma inserts a space character between items. The CRLF constant can be used to insert line breaks in the resulting string. Note that Print does NOT require parentheses around the data items.
The traditional "?" is also provided as a synonym for Print.
Syntax:
Print Data1[,|; Data2 ...]
The Rem keyword is used to preface a comment line and must always occur at the beginning of a line. A # character placed at the beginning of a line is interpreted as Rem.
Syntax:
Rem some comment
or
# some comment
Ends the current sub and returns to the calling sub. If Return is followed by a value, then the value will be passed to the calling sub.
Syntax:
Return [Value]
Example:
Sub SomeSub
If IsInteger (a) = true Then
b=a
End If
End Sub
Sub IsInteger (x)
If x = Int(x) Then
Return true
Else
Return false
End If
End Sub
Generates a random integer larger or equal to the minimum value and smaller than the maximum value.
Syntax:
Rnd (Minimum Value, Maximum Value)
Example:
i = Rnd (30, 60)
Select is used to test one value with several values. Only the first case that matches will execute. "EndSelect" is also accepted in place of "End Select".
Syntax:
Select value
Case Value1
...
Case Value2
...
Case Else
...
End Select
Example:
Select StrToLower(Var)
Case ""
Return
Case "one"
num = 1
Case "2"
num = 2
Case Else
num = -1
End Select
SetItem allows you to dynamically assign the elements of an array determined at runtime rather than at compile time. It accepts the name of the array as a string or variable together with the index of the required element and the new value. SetItem treats a multi-dimension array as a single dimension array. Array indices for multi-dimensioned arrays may be calculated using GetRank, and get GetLen. GetTotalLen returns the total size of the array when regarded as a single dimensioned array.
Syntax:
SetItem(ArrayName, Index, Value)
Example:
arr = "array1"
index = 23
val = 1.2345
SetItem(arr, index, val)
Causes the script to wait for the specified time (milliseconds) without using any processor resources and allowing other programs to run.
Syntax:
Sleep (Milliseconds)
Example:
Sleep(1000)
The program will pause for one second.
The Sys keyword is a synonym for CallHostSub.
The SysGui keyword is a synonym for CallHostGuiSub.
Returns the absolute value of a given number.
Syntax:
Abs (Number)
Example: x = Abs (-4)
Now x = 4
Returns the angle (in radians) that correlate with a given number.
Syntax:
ACos (Number)
To convert from radians to degrees, multiply by 180 / cPI
Returns the angle (in radians) that correlate with a given number.
Syntax:
ASin (Number)
To convert from radians to degrees, multiply by 180 / cPI
Returns the angle (in radians) that correlate with a given number.
Syntax:
ATan (Number)
To convert from radians to degrees, multiply by 180 / cPI
Returns the number correlated with a given angle (in radians).
Syntax:
Cos (Radians)
To convert from degrees to radians multiply by cPI / 180
Returns the integer part from a number.
Syntax:
Int (Number)
Example: a = Int (4.8)
Now a = 4
Returns the base e logarithm of a given number.
Syntax:
Ln (Number)
Returns the base 10 logarithm of a specified number.
Syntax:
Log (Number)
Returns the larger of two numbers.
Syntax:
Max (Number, Number)
Example: a = Max (12, 33)
Now a = 33
Returns the smaller number of two numbers.
Syntax:
Min (Number, Number)
Example: a = Min (12,33)
Now a = 12
Returns a rounded number from a number with an optional parameter specifying the number of digits. The default number of digits is 0.
Syntax: Round (Number [,Number of digits])
Example:
Msgbox (Round (4.8))
Displays 5
Returns the number correlated with the given angle (in radians).
Syntax:
Sin (Radians)
To convert from degrees to radians multiply with cPI / 180
Returns the square root of the given number.
Syntax:
Sqrt (Number)
Example:
Msgbox(Sqrt(16))
Displays 4
Returns the number correlated with a given angle (in radians).
Syntax:
Tan (Radians)
To convert from degrees to radians multiply by cPI / 180
Returns the ASCII or Unicode number of the first character in the string.
Syntax: Asc (String)
Example: I = Asc ("0")
Now I = 45
Returns the Unicode character represented by the given number.
Syntax: Chr (Integer)
Integer ranges from 0 to 1,114,112.
Example:
Msgbox (Chr(34) & "Hello" & Chr(34))
This example shows a message box with : "Hello" (including the quotes).
Returns a string representing a given number in a specific format.
A format consists of a pattern and a set of symbols. Many characters in a pattern are taken literally; they are matched during parsing and are written out unchanged during formatting. On the other hand, special characters stand for other characters, strings, or classes of characters. For example, the '#' character is replaced by a localized digit. Often the replacement character is the same as the pattern character; in the U.S. locale, the ',' grouping character is replaced by ','. Some special characters affect the behavior of the formatter by their presence; for example, if the percent character is seen, then the value is multiplied by 100 before being displayed.
A pattern contains a positive and negative sub-pattern, for example, "#,##0.00;(#,##0.00)". Each subpattern has a prefix, a numeric part and a suffix. If there is no explicit negative subpattern, the negative subpattern is the localized minus sign prefixed to the positive subpattern. That is, "0.00" alone is equivalent to "0.00;-0.00". If there is an explicit negative subpattern, it serves only to specify the negative prefix and suffix; the number of digits, minimal digits, and other characteristics are ignored in the negative subpattern. This means that "#,##0.0#;(#)" produces precisely the same result as "#,##0.0#;(#,##0.0#)".
0 represents a digit.
# represents a digit, leading zeroes are not shown.
. represents the decimal separator or monetary decimal separator.
- represents the minus sign.
, represents a grouping separator.
E separates mantissa and exponent in scientific notation.
+ prefix positive exponents with localized plus sign.
; separates positive and negative subpatterns.
% multiply by 100 and show as percentage.
' used to quote special characters in a prefix or suffix, for example, "'#'#" formats 123 to "#123". To create a single quote itself, use two in a row: "# o''clock".
The formatting rules are those for an Java DecimalFormat object.
Syntax:
Format (Number, Format String)
Example:
Msgbox (Format(1234.5678,",##0.##"))
Displays: 1,234.57
Returns true if the first character in the string is a digit.
Syntax:
IsDigit (String)
Example:
If IsDigit (StrAt (Text,2)) = True Then ...
It will be true if the third character is a digit.
Returns true if the first character in the string is a letter.
Syntax:
IsLetter (String)
Example:
If IsLetter (StrAt (Text,2)) = True Then ...
It will be true if the third character is a letter.
Return true if the string is a number.
Syntax:
IsNumber (String)
Example:
If IsNumber(Text) = true Then
Msgbox (TextBox1.Text * 20)
End If
Returns true if the first character in the string is a punctuation symbol.
Syntax:
IsPunctuation (String)
Example:
If IsPunctuation (StrAt (Text,2)) = True Then ...
It will be true if the third character is a punctuation symbol.
Returns the character at a specific position. Index starts from 0 to String length - 1.
Syntax:
StrAt (String, Index)
Example: a = StrAt ("abcdef" , 3)
Now a = "d"
Compares two string and returns a value depending on the lexical order of the strings. It returns a number less than zero if the first string is less than the second string. It returns zero if the strings are equal and a number greater than zero if the first string is greater than the second string. If the Compare Constant is omitted, the comparison will be not case sensitive.
Syntax:
StrCompare(String, String [,CompareConstant])
Compare Constant can be: cCaseSensitive or cCaseUnsensitive.
Example:
i = StrCompare (TextBox1.Text, TextBox2.Text, cCaseSensitive)
If i = 0 Then
Msgbox("Both equal")
Else If i<0 Then
Msgbox("TextBox1 is smaller")
Else
Msgbox("TextBox2 is smaller")
End If
Returns the index of the first letter in the matching string, starting from a given index.
If the matching string isn't found then it will return -1. Value is the string that is searched for in String.
Syntax:
StrIndexOf (String, Value, StartIndex)
Example:
Msgbox (StrIndexOf ("abcdef" , "cd",0))
Displays 2.
Msgbox (StrIndexOf ("abcdef" , "ab",1))
Displays -1 (not found)
Returns a new string which is the result of inserting a one string into another string.
Syntax:
StrInsert (String, StartIndex, Value)
Example:
Old = "12567"
New = StrInsert (Old,2,"34")
Now New = "1234567"
Joins an array of strings with each string except the last being terminated by the Deliminator string. Returns a new string.
Syntax:
SrtJoin (SrcArray, Deliminator)
SrcArray - The array whose contents will be joined.
Deliminator - A string that is used to separate the joined strings..
Example:
Array(words, "one", "two", "three")
Result = StrJoin(words(), " ")
Returns the length of a string (number of characters).
Syntax:
StrLength (String)
Example: Msgbox (StrLength ("B4Script"))
Displays 8
Returns a new string after removing some characters from the old string.
Syntax:
StrRemove (String, StartIndex, Count)
Example:
Old = "B4Script"
New = StrRemove (Old ,3,4)
Now New = "B4St"
Returns a new string after replacing the old value (in the old string) with the new value.
Like all the other string keywords it doesn't change the old string value.
Syntax:
StrReplace (String , Old Value, New Value)
Example:
s = "The sun is bright"
s = StrReplace (s," ","") 'remove white spaces
Now s = "Thesunisbright"
Splits a string and returns an array of strings. If the Separators string is an empty string then all white characters will be used as the separators.
Syntax:
StrSplit (DestArray, RawString, Separators)
DestArray - The array that will receive the result
RawString - The string that will be split.
Separators - Zero or more characters that act as the separators.
Example:
Dim words(0) as string
Nums= "161229.487,3723.2475,12158.3416,1,07"
StrSplit(values(), Nums, ",")
for i = 0 to ArrayLen(values())-1
msgbox(values(i))
next
Returns a new string from the old string with all the letters in lower case.
Syntax:
StrToLower (string)
Example: Msgbox (StrToLower("AbCdE"))
Displays "abcde"
Returns a new string from the old string with all the letters in uppercase.
Syntax:
StrToUpper (string)
Example: Msgbox (StrToUpper("AbCdE"))
Displays "ABCDE"
Returns a new string that is made of part of an old string. If the length of the new string is beyond the length of the original string then white spaces will be added to it.
Syntax: SubString (String, StartIndex, Count)
Example:
Old = "B4Script"
New = SubString (old,1, 2)
Now New = "4S"
Time and date values are stored as their number of milliseconds since January 1, 1970, 00:00:00 GMT.
Keyword Date returns a date string from a milliseconds value.
Keyword Time returns a time string from a milliseconds value.
Date and Time are formatted using DateFormat and TimeFormat keywords.
You can use TimeAdd / DateAdd or the time and date constants to do time and date manipulation.
Date and time formats are specified by date and time pattern strings as implemented by the Java SimpleDateFormat class. Within date and time pattern strings, unquoted letters from 'A' to 'Z' and from 'a' to 'z' are interpreted as pattern letters representing the components of a date or time string. Text can be quoted using single quotes (') to avoid interpretation. "''" represents a single quote. All other characters are not interpreted; they're simply copied into the output string during formatting or matched against the input string during parsing.
Beware of using the 'Week year' format (YYYY) by accident or without fully understanding how it works.
December 27 2015 is day 1 of week 1 of week-year 2016 (and December 27 2026 is day 1 of week 1 of week-year 2027).
If Date/TimeFormat outputs a date it can use all fields: year, month, day, day of week, week of month, week in year, week-year etc.
If parsing Date/TimeParse expects a matching set of values: either day, month, year or day of week, week in year, week-year. If you supply a week-year but do not supply day of week and week in year, those values will be assumed to be 1.
These actual values depend on your locale:
The following pattern letters are defined (all other characters from 'A' to 'Z' and from 'a' to 'z' are reserved):
Letter |
Date or Time Component |
Presentation |
Examples |
G |
Era designator |
AD |
|
y |
Year |
1996; 96 |
|
Y |
Week year |
2009; 09 |
|
M |
Month in year |
July; Jul; 07 |
|
w |
Week in year |
27 |
|
W |
Week in month |
2 |
|
D |
Day in year |
189 |
|
d |
Day in month |
10 |
|
F |
Day of week in month |
2 |
|
E |
Day name in week |
Tuesday; Tue |
|
u |
Day number of week (1 = Monday, ..., 7 = Sunday) |
1 |
|
a |
Am/pm marker |
PM |
|
H |
Hour in day (0-23) |
0 |
|
k |
Hour in day (1-24) |
24 |
|
K |
Hour in am/pm (0-11) |
0 |
|
h |
Hour in am/pm (1-12) |
12 |
|
m |
Minute in hour |
30 |
|
s |
Second in minute |
55 |
|
S |
Millisecond |
978 |
|
z |
Time zone |
Pacific Standard Time; PST; GMT-08:00 |
|
Z |
Time zone |
-0800 |
|
X |
Time zone |
-08; -0800; -08:00 |
Pattern letters are usually repeated, as their number determines the exact presentation:
Text: For formatting, if the number of pattern letters is 4 or more, the full form is used; otherwise a short or abbreviated form is used if available. For parsing, both forms are accepted, independent of the number of pattern letters.
Number: For formatting, the number of pattern letters is the minimum number of digits, and shorter numbers are zero-padded to this amount. For parsing, the number of pattern letters is ignored unless it's needed to separate two adjacent fields.
Otherwise, calendar system specific forms are applied. For both formatting and parsing, if the number of pattern letters is 4 or more, a calendar specific long form is used. Otherwise, a calendar specific short or abbreviated form is used.
If week year 'Y' is specified and the calendar doesn't support any week years, the calendar year ('y') is used instead. The support of week years can be tested with a call to getCalendar().isWeekDateSupported().
GMTOffsetTimeZone:
GMT Sign Hours : Minutes
Sign: one of
+ -
Hours:
Digit
Digit Digit
Minutes:
Digit Digit
Digit: one of
0 1 2 3 4 5 6 7 8 9
Hours must be between 0 and 23, and Minutes must be between 00 and 59. The format is locale independent and digits must be taken from the Basic Latin block of the Unicode standard.
For parsing, RFC 822 time zones are also accepted.
RFC822TimeZone:
Sign TwoDigitHours Minutes
TwoDigitHours:
Digit Digit
TwoDigitHours must be between 00 and 23. Other definitions are as for general time zones.
For parsing, general time zones are also accepted.
ISO8601TimeZone:
OneLetterISO8601TimeZone
TwoLetterISO8601TimeZone
ThreeLetterISO8601TimeZone
OneLetterISO8601TimeZone:
Sign TwoDigitHours
Z
TwoLetterISO8601TimeZone:
Sign TwoDigitHours Minutes
Z
ThreeLetterISO8601TimeZone:
Sign TwoDigitHours : Minutes
Z
Other definitions are as for general time zones or RFC 822 time zones.
For formatting, if the offset value from GMT is 0, "Z" is produced. If the number of pattern letters is 1, any fraction of an hour is ignored. For example, if the pattern is "X" and the time zone is "GMT+05:30", "+05" is produced.
For parsing, "Z" is parsed as the UTC time zone designator. General time zones are not accepted.
If the number of pattern letters is 4 or more, IllegalArgumentException is thrown when constructing a SimpleDateFormat or applying a pattern.
SimpleDateFormat also supports localized date and time pattern strings. In these strings, the pattern letters described above may be replaced with other, locale dependent, pattern letters. SimpleDateFormat does not deal with the localization of text other than the pattern letters; that's up to the client of the class.
The following examples show how date and time patterns are interpreted in the U.S. locale. The given date and time are 2001-07-04 12:08:56 local time in the U.S. Pacific Time time zone.
Date and Time Pattern |
Result |
"yyyy.MM.dd G 'at' HH:mm:ss z" |
2001.07.04 AD at 12:08:56 PDT |
"EEE, MMM d, ''yy" |
Wed, Jul 4, '01 |
"h:mm a" |
12:08 PM |
"hh 'o''clock' a, zzzz" |
12 o'clock PM, Pacific Daylight Time |
"K:mm a, z" |
0:08 PM, PDT |
"yyyyy.MMMMM.dd GGG hh:mm aaa" |
02001.July.04 AD 12:08 PM |
"EEE, d MMM yyyy HH:mm:ss Z" |
Wed, 4 Jul 2001 12:08:56 -0700 |
"yyMMddHHmmssZ" |
010704120856-0700 |
"yyyy-MM-dd'T'HH:mm:ss.SSSZ" |
2001-07-04T12:08:56.235-0700 |
"yyyy-MM-dd'T'HH:mm:ss.SSSXXX" |
2001-07-04T12:08:56.235-07:00 |
"YYYY-'W'ww-u" |
2001-W27-3 |
Return a date string from a ticks value.
Syntax:
Date (Ticks)
Example:
Msgbox (Date(Now))
Displays the current date.
Returns the ticks value of the given ticks + years + months + days.
Syntax:
DateAdd (Ticks, Years, Months, Days)
Example:
x = Now
tomorrow = DateAdd(x, 0, 0, 1)
Returns the day (starting from the beginning of the month) component from a ticks value.
Syntax:
DateDay (Ticks)
Returns the name of the day in the week from a ticks value.
Syntax:
DateDayOfWeek (Ticks)
Returns the day (starting from the beginning of the year) component from a ticks value.
Syntax:
DateDayOfYear (Ticks)
Changes the format of showing and parsing dates. The default value is: "MM/dd/yyyy" (If you do not use the DateFormat keyword then the date format will be this value). In fact DateFormat and TimeFormat are both capable of independently formatting both dates and times and mixtures thereof. Their titles and apparent separation of functionality are for historical reasons.
Syntax:
DateFormat (Format String)
Example:
x = DateParse ("04/25/2006")
DateFormat ("dddd - mmmm - yy")
Msgbox(Date(x))
This example will show: Tuesday - April - 06
Returns the month (starting from the beginning of the year) component from a ticks value.
Syntax:
DateMonth (Ticks)
Returns the ticks value of a date string.
The date string must be formatted exactly as the date format. (Default "MM/dd/yyyy")
Syntax:
DateParse (Date String)
Example:
T = DateParse ("01/30/2012")
Returns the year component from a ticks value.
Syntax:
DateYear (Ticks)
Returns the ticks value of the current date and time.
Syntax:
Now
Example:
Msgbox(Date(Now))
Shows the current date formatted as a date string
Return a time string from the ticks value.
Syntax:
Time (Ticks)
Example:
Msgbox (Time (Now))
Displays the current time.
Returns the ticks value of the given ticks + hours + minutes + seconds.
Syntax:
TimeAdd (Ticks, Hours, Minutes, Seconds)
Example:
x = Now
tomorrow = TimeAdd(x, 24, 0, 0)
Changes the format of showing and parsing times. The default value is: "HH:mm" (If you do not use the TimeFormat keyword then the time format will be this value.). In fact DateFormat and TimeFormat are both capable of independently formatting both dates and times and mixtures thereof. Their titles and apparent separation of functionality are for historical reasons
Syntax:
TimeFormat (Format String)
"H" - 24 hours format.
"h" - 12 hours format.
"tt" - AM / PM
TimeFormat can be used any number of times inside an application.
Example:
TimeFormat ("HH:mm:ss")
x = TimeParse ("23:15:23")
TimeFormat ("hh:mm tt")
Msgbox(Time(x))
This example will show: 11:15 PM
Returns the hour (starting from the beginning of the day) component from the ticks value.
Syntax:
TimeHour (Ticks)
Returns the minute (starting from the beginning of the hour) component from the ticks value.
Syntax:
TimeMinute (Ticks)
Returns the ticks value of the time string. The ticks value returned is the time entered plus the ticks value for the current date. The time string must be formatted exactly as the time format. (Default "HH:mm")
Syntax:
TimeParse (TimeString)
Example:
T = TimeParse ("21:34")
Returns the second (starting from the beginning of the minute) component from the ticks value.
Syntax:
TimeSecond (Ticks)
cBeige
cBlack
cBlue
cBrown
cCyan
cGold
cGreen
cGray
cOrange
cPink
cPurple
cRed
cSilver
cWhite
cYellow
cTicksPerDay - Number of ticks per day
cTicksPerHour - Number of ticks per hour
cTicksPerMinute - Number of ticks per minute
cTicksPerSecond - Number of ticks per second
Version - The version of the B4Script library
cE (e)
cPI
cCaseSensitive
cCaseUnsensitive
cTab
crlf (New Line)