Programming Gambas from Zip/Functions
Functions Reference
editString Functions
edit| Character Codes | ||
| Asc | Returns the ASCII code of a character | Every character has an ASCII code, eg Asc("A") is 65. |
| Chr | Returns a character from its ASCII code | Chr(65) is "A" . Chr(32) is the space. Chr(1) is Ctrl-A
When checking to see if a key was pressed, use Key["A"] or Key[Key.ShiftKey] instead for the number of a key on the keyboard, rather than the number of a character. |
| Parts of Strings | ||
| Left | The left-hand end of a string | Left("Hello", 4) is "Hell" |
| Mid | The “middle” part of a string
Mid(String, StartingAt, HowLong) |
Mid("Gambas", 3, 2) is mb because that is the string that starts at position 3 and is 2 characters long. |
| Right | The right-hand end of a string | Right("String", 4) is "ring" |
| Find and Replace | ||
| InStr | The position of the second string in the first
InStr(String, LookFor) InStr(String, LookFor, StartingAt) |
InStr("Gambas is basic", "bas") is 4, because bas starts at position 4.
InStr("Gambas is basic", "bas", 6) is 11, because InStr only starts looking for bas from position 6. If the string is not found it returns 0. InStr("Gambas is basic", "bas", -5) is 11. The -5 means only start looking five from the end until the end, i.e. at position 10, the second space. Note that the last letter, c, is not 1 from the end. It is the end. i is 1 from the end. |
| Replace | The string with every occurrence of something replaced by something else
Replace(String, LookFor, WithThis) |
Replace("Abracadabra", "a", "*") is Abr*c*d*br*
Message( Replace(LetterText, "<name>", FirstName&" "&LastName) ) |
| Subst | A string with its markers replaced by other strings | Subst("Tell &1 to arrive at &2 PM", "Mark", "4") is
"Tell Mark to arrive at 4 PM" |
| Change Case | ||
| UCase | Converts a string to uppercase. | UCase("gerard") is "GERARD" |
| LCase | The string converted to lower case | LCase("GERARD") is "gerard" |
| Trimming | ||
| Trim | A string with no spaces at either end | Trim(" Hello ") is "Hello" |
| LTrim | Left Trim
The string with spaces removed from the start |
LTrim(" Hello") is "Hello" |
| RTrim | Right Trim
The string with spaces removed from the end |
RTrim("Hello ") is "Hello" |
| Building Strings | ||
| String | A string made of the same string repeated many times.
String(HowMany, WhichString) |
String(6, "*") is "******"
String(2, "Gambas") is "GambasGambas" |
| Space | A string of spaces | Space(8) is eight spaces |
| Quote | The string in quotation marks
The UnQuote function removes them. |
Quote("Hello,") & " she said." is "Hello," she said. |
| Miscellaneous | ||
| Len | The length of a string | Len("Gambas is basic") is 15 |
| Comp | Compares two strings
Comp(FirstString, SecondString) Comp(FirstString, SecondString, Mode) |
If the two strings are the same, it returns 0.
If the first string comes after the second in a dictionary, it returns +1 If the first string comes before the second it is -1 If Comp(UserName, "Akiti", gb.IgnoreCase) = 0 Then Message("Welcome Akiti!") else Message("You’re not Akiti!") |
| Split | An array made from a string
Split(String, Separator) |
Dim z As String[] = Split("John,Mary,Paul,Gemma,Lucille,Hamish", ",")
The string is split at the commas. |
Numeric Functions
edit| Positives and Negatives | ||
| Abs | Absolute value of a number — remove the negative sign if any. | Abs(7) = 7
Abs(-7) = 7 |
| Sgn | Sign (+, 0, –) of a number | Sign(3.14) = +1
Sign(–6) = –1 Sign(0) = 0 |
| To Whole Numbers | ||
| Int | Integer part of a number
Negative numbers are rounded down; positive numbers abandon the fraction part. |
Int(3.2) = 3
Int(3.9) = 3 Int(6) = 6 Int(-7.2) = -8 Int(-7.9) = -8 |
| Round | Round a number to the nearest integer or power of ten
e.g. 10^2 is 100, so Round(x,2) is to the nearest 100. Negative powers are how many decimal places |
Round(Pi, -2) = 3.14
Print Round(1972, 2) = 2000 |
| Frac | The fractional part of a number
The fractional part of a date is the time. |
Frac(3.14) = 0.14
Frac(Date(1999, 12, 13, 14, 20, 00)) = 0.597222222015 CDate(Frac(Date(1999, 12, 13, 14, 20, 00))) = 14:20:00 |
| Fix | Integer part of a number—remove any fractional part | Fix(3.14) = 3
Fix(-3.14) = -3 |
| CInt | Convert to an integer
Abandon the fraction part completely. |
Int(3.2) = 3
Int(3.9) = 3 Int(6) = 6 Int(-7.2) = -7 Int(-7.9) = -7 |
| Floor | Round down to the next lowest whole number | Floor(3.14) = 3
Floor(-3.14) = -4 |
| Ceil | Ceiling: round up to the next highest whole number | Ceil(3.14) = 4
Ceil(-3.14) = 3 |
| Comparing | ||
| Max | Whichever of two numbers is greater
Also works with dates |
Max(6,4) = 6 |
| Min | Whichever of two numbers is lesser
Also works with dates |
Min(6,4) = 4 |
| Increment and Decrement | ||
| INC | Increments a variable; same as x += 1 or x = x+1
This is an procedure rather than a function (no brackets; it’s a verb, not a noun) |
INC x |
| DEC | Decrement a variable; same as x –= 1 or x = x–1
This is an procedure rather than a function. |
DEC x |
Character Test Functions
editThe empty string is NULL. IsNull("") is True. IsNull("M") is False.
| IsAscii | Tests if a string contains only ASCII characters. |
| IsBlank | Tests if a string contains only blank characters. |
| IsDigit | Tests if a string contains only digits. |
| IsHexa | Tests if a string contains only hexadecimal digits. |
| IsLCase | Tests if a string contains only lowercase letters. |
| IsLetter | Tests if a string contains only letters. |
| IsPunct | Tests if a string contains only printable non-alphanumeric characters. |
| IsSpace | Tests if a string contains only space characters. |
| IsUCase | Tests if a string contains only uppercase letters. |
Random Numbers
edit| Randomize | Without it you get the same series of random numbers each time your program is run. | Randomize
Just the word by itself. |
| Rand | A random integer between two numbers. | Rand(1,6) is a random number between 1 and 6 inclusively. This could be a dice throw.
Rand(1,2) is either a 1 or a 2. |
| Rnd | A random floating point number. | Rnd( ) is between 0 and 1
Rnd(9) is between 0 and 9, but never 9 itself. Rnd(10, 20) is between 10 and 20, but never 20. |
Time And Date
editA given date and time is stored internally as two integers, the first being the date and the second being the time. The following examples may explain what you can do with dates and times.
Examples:
| Now | 07/08/2019 19:18:54.929 | 8 July 2019, almost 8:19 pm
The current date and time |
| Format(Now, "dddd dd/mm/yyyy hh:nn:ss") | Tuesday 09/07/2019 20:45:13 | More on Format() later. Use it to present a date and/or time, or indeed any number, in the way you want. And it is now 8:46pm on July 9, by the way. |
| Date() | 07/07/2019 23:00:00 | When today started, less one hour for Daylight Saving Time. |
| Date(1955, 6, 1) | 05/31/1955 23:00:00 | Someone’s birthday, less one hour for Daylight Saving Time. The date is assembled from Year, Month, Day. |
| Date(2019, 12, 25, 6, 15, 0) | 12/25/2019 05:15:00 | 6:15 am on Christmas Day, 2019. Time for opening Christmas presents.
Year, Month, Day, Hours, Minutes, Seconds |
| DateAdd(Date(1955, 6, 1), gb.Day, 14) | 06/14/1955 23:00:00 | 14 days after 1 June 1955. DS again.
You can add other things besides days: gb.Second, gb.Minute, gb.Hour, gb.Day, gb.Week, gb.WeekDay (ignore Saturday and Sunday), gb.Month, gb.Quarter, gb.Year |
| DateDiff(Date(2019, 7, 6), Date(Now), gb.Day) | 2 | Days between two days ago and now |
| DateDiff(Date(Now), Date(2018, 12, 25), gb.Day) | 195 | How many days since Christmas?
(It’s now 2019. Last Xmas was 2018.) DateDiff(RecentDate, PastDate, Units) |
| DateDiff(Date(Now), Date(2019, 12, 25), gb.Day) | 170 | How many days until Christmas?
(It’s now 2019.) |
| DateDiff(Date(1955, 6, 1), Now, gb.Second) | 2022959392 | How many seconds I have been alive |
| DateDiff(Date(1955, 6, 1), Now, gb.Day) | 23413 | How many days I have been alive |
| CLong(DateDiff(Date(1955, 6, 1), Now, gb.Minute)) * 72 | 2427551928 … no, wait, it’s 2427552144 … no, wait, it’s 2427552216 ... | How many heartbeats since my birth.
Had to convert the DateDiff to Long Integer because without it there is an overflow problem: it shows as a negative number. Longs can hold very big numbers. |
| Parts of Dates and Times | ||
| Hour(Now) & " hrs " & Minute(Now) & " mins" | 14 hrs 39 mins | It is now 2:39 pm.
You can also use these: Day(), Hour(), Minute(), Month() Second(), Time(), Week(), Weekday() Year() |
| "Rip van Winkle, this is " & Year(Now) | Rip van Winkle, this is 2019 | The year part of a date |
| WeekDay(Now) | 2 | 0 = Sunday, 6 = Saturday
2 means it is Tuesday. |
| If WeekDay(Now) = gb.Tuesday then label1.text = "It is Tuesday." else label1.text = "It is not Tuesday." | It is Tuesday. | gb.Tuesday is a constant whose value is 2. Using the constant means you need not remember Tuesday is 2.
Others are gb.Monday, gb.Wednesday, gb.Thursday, gb.Friday, gb.Saturday and gb.Sunday |
| Time(Now) | 14:58:44.654 | The time part of a date (Now is the current date and time) |
| Time(14, 08, 25) | 14:08:25 | Assemble a time from its parts
Time(Hour, Minutes, Seconds) |
| Time() | 15:05:09.515 | The time right now |
| Conversions | ||
| Val("1/6/55") | 05/31/1955 23:00:00 | Converts the string to a date
The 1-hour difference is due to daylight saving time. |
| Val("1/6/55 2:00") | 06/01/1955 01:00:00 | 2 am on 1 June 1955
The 1-hour difference is due to daylight saving time. |
| Val("1-6-55 2:00") | nothing | Very sensitive to the format… ignored |
| Str(2484515) | 2484515 | If you supply a number, Str() will convert that number to a string. |
| Dim D As Date = 2484515
label1.text = Str(D) |
16/05/2002 01:00:00 | The number has changed to a date.
Str() converts it into local date format |
| Dim D As Date = 2484515
label1.text = D |
05/16/2002 | United States date format |
| CDate("1-6-55 2:00") | Error | “Wanted date, got string instead”
Not only sensitive, but offended... |