Curious what we can do for you?
©2024 Blue Polar. All rights reserved.
An important part of Polar Script are Variables, Constants and Functions. Variables can hold values, functions can perform a specific operation. Functions can either return a value or have no return value. The latter can also be defined as a Sub. In other words, a Sub is a Function without a return value. Constants are like Variables but have a fixed (hard coded) value.
The scope means in what 'area' of your program a variable of function is available. Within that scope, names of functions and variables must be unique. Polar Script has the following scopes:
| Scope | Notes |
|---|---|
| Function | The variable is defined within a function, either as a Dim or when it is defined as parameter. It is only available within that function. |
| Class | The variable is defined within a Class (outside a function). Can be either defined as Public or Private within the class. |
| Module | The variable or function is defined as a private variable or function within a module. It is only accessible within that module. |
| Global | A variable of function is defined as Public within a module. It is accessible from all modules. |
Dim mName As String 'Scope is module
Public gProjectName As String = "MyProject" 'Scope is Global
Public Function AddNumbers(pNumber1 As Double, pNumber2 As Double) As Double 'Scope of AddNumbers is Global. Scope of parameters is always the Function only.
Dim lResult As Double = pNumber1 + pNumber 2 ' Scope of lResult is function
Return lResult
End Function
Private Function CleanupName(pName As String) As String 'Scope of CleanupName is this Module
Return Left(Replace(pName, " ", "_"), 64)
End Function
Class Planet
Dim mAccessCount As Long 'Scope is Class
Public Name As String 'Scope is Class
Public Sub EraseName() 'Scope is Class
Dim lLength As Long = Len(Name) 'Scope of lLength is Function EraseName only.
If lLength > 32 Then
Name = ""
End If
End Sub
End Class
Variables, Constants and functions must have a unique name within their scope. Names must start with a character (A-Z) or an underscore and can contain characters, underscores and numbers (0-9). A name of only one single underscore is not allowed because the single underscore is also used as line-continuation character.
Within a Class or in a Module (so NOT within a sub/function) you can define a variable with Public, Private or Dim (Dim is equal to Private). Within Functions and Subs, variables are allways defined using Dim
Constants are defined in Modules and Classes with Public Const / [Private] Const. In Functions and Subs, Constants are defined with Const only.
Dim mGroupName
Public RequestCount As Long
Private mMyPrivateVariable As Collection
Const mEndOfTimes = #2500-12-31#
Function SomeFunction()
Const cDaysInWeek = 7
Dim Names(cDaysInWeek - 1) As String 'Note: arrays are zero-based. This example will set the UBound to 6, with effective 7 (0,1,2,3,4,5,6) elements.
End Function
Constants must be defined with a value and Variables can be initialized with initial values. There are two different situations:
Dim mString As String = "Hello World"
Const mDaysInWeekCount = 7
Dim mDictionary As Dictionary ' <= There is no constant for a new dictionary, so you cannot set a default value at module level
Function Demo
Const mMaxDiceValue = 6
Dim lDiceValue As Long = Int(Rnd(1) * mMaxDiceValue) + 1
Dim lCollection As Collection = New Collection 'Within a procedure, you can set a default like this
End Function
Class MyClass
Dim mCollection As Collection
Const ClassName = "MyClass"
Private Sub Initialize()
mCollection = New Collection
End Sub
End Class
Within the expressions you write and for setting initial values, you can use the following syntaxes for the various data types.
| Data type | Example | Notes |
|---|---|---|
| String | "MyString" | |
| Boolean | True False | |
| Long LongLong | 33 -999 12e7 &hFF_FF &b1010_1110_1001 0xFec8cca0 1L | LongLong can be indicated by adding a & or L. Underscores in hex and binary notations are optional and are removed before parsing. |
| Double | 3.14159265 2.5e5 -8e-5 .5 100# 7.7r | Doubles can be indicated by adding a # or R. |
| Decimal | 32.50d -1.77772384d | Decimals can be indicated by adding a @ or D. |
| Date | #2020-12-31 17:55:22# #31-12-2020 17:55:22# #17:55:22# #17:55# #2100-12-31# | |
| Array | {"Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"} {0, 1, 2} {5, "test", #12:00#} |
See also: Array Variables
Functions and Sub-routines are used to encapsulate reusable blocks of code in Polar Script. The only difference between a Functions and a Sub is that a function returns a value, while a Sub does not return a value.
[Public | Private] Function functionName([parameters]) [As returnType]
[statements]
[Return expression | functionName = expression]
End Function
[Public | Private] Sub subName([parameters])
[statements]
End Sub
In the rest of this page, we will only refer to functions, but everything (except return values) also applies to subs.
Parameters for Functions follow the next syntax
[ByVal | ByRef] ParameterName [As VariableType] [, ....]
If a parameter is passed 'ByRef', changes in value of the parameter are passed back into passed variable. In case of a ByVal parameter, changed values are only visible within the Function.
Example:
Public Function DateToPolarScript(pDate As Date) As String
Return Format(pDate, "\#YYYY\/MM\/DD\ HH:MM:SS\#")
End Function
Private Function OldStyleReturnType()
OldStyleReturnType = Int(Rnd(1) * 6) + 1 'Instead of Return statement
End Function
In Polar Script, parameters can also be made optional. Optional parameters can be passed by the calling function but can also be omitted. When omitted, a default value can be specified in the parameter-definition. Optional parameters are always on the end of the list of parameters (no not-optional parameters can be defined after an optional parameter). The syntax of optional parameters is:
Optional [ByVal | ByRef] ParameterName [As VariableType] [= DefaultValueExpression] [, Optional ....]
Optional Parameters that are typed (not being Variant) are set to the default of that type when not passed and no DefaultValueExpression is specified. If no ParameterType and no DefaultValue are specified, and the parameter is omitted, then the value of that parameter is set to Missing. This is a special empty-type.
Example:
Public Function DateToPolarScript(pDate As Date, Optional pIncludeTime As Boolean = True) As String
Return Format(pDate, $"\#YYYY\/MM\/DD\{IIf(pIncludeTime, " HH:MM:SS", "")}\#")
End Function
Public Function SomeFunction(Optional pParameter1)
If IsMissing(pParameter1) Then
pParameter1 = "Not specified"
End If
Return pParameter1
End Function
Sometimes a function must be able to retrieve a list of values. For this, you can use the ParamArray parameters. The passed values are put in an array in that parameter. Please obey the following rules:
Example:
Public Function AddNumbers(Optional Paramarray pNumbers As Double ()) As Double
Dim lResult As Double
Dim lItem As Double
For Each lItem In pNumbers
lResult = lResult + lItem
Next
Return lResult
End Function
There are two methods to set the ReturnValue for a function:
Function Average(Paramarray pValues As Double) As Variant
Dim lItemCount As Long = UBound(pValues) + 1 'Arrays are zero-based. A 1-element array returns a UBound of 0. An empty array has a UBound of -1
If lItemCount = 0 Then Return Null
Return AddNumbers(pValues) / lItemCount
End Function
Function Average(Paramarray pValues As Double) As Variant
Dim lItemCount As Long = UBound(pValues) + 1 'Arrays are zero-based. A 1-element array returns a UBound of 0. An empty array has a UBound of -1
If lItemCount = 0 Then
Average = Null
Else
Average = AddNumbers(pValues) / lItemCount
End If
End Function
To exit a Sub or Function prematurely, you can use either the Return statement or the Exit Sub / Exit Function statement. Within a Function, the Return statement MUST always specify the return value, within a Sub the Return statement does not allow a return value.
Public Function Test(pValue1 As Variant, Paramarray pTestValues)
If IsNULL(pValue1) Then Exit Function
Dim lElement
For Each lElement In pTestValues
If lElement = pValue1 Then Return True
Next
Return False
End Function