`String` Data Type

Holds a sequence of 8-bit Unicode (UTF-8) characters. A string can contain from zero to TBD characters.

Instructions

Default value: When you declare a variable of type String and do not initialize it, its default value is the empty string ("").
Type characters: When you put a dollar sign ($) at the end of a name, it declares it has the type String.

String literals and constants

String literal

Syntax

{ " [ char… ] " ]}…

A typical string literal starts and ends with double quotation symbols ("). If you write only two such symbols (""), this is known as an empty string.

A string can include a quotation symbol if you write two of them together. For example, """" is a string that contains one quotation symbol.

String constant

Syntax

{ $ name
| $ decimal
| $U hexadecimal
| $X hexadecimal
| $O octal
| $B binary }

A string constant starts with a dollar symbol ($). The remaining part can be a name or a number. Most string constants hold a string value of one character. But some named constants can hold longer strings.

The numbers can be in one of four bases: decimal (not marked), hexadecimal (starts with $U or $X), octal (starts with $O), or binary (starts with $B).

For example, the space character can be $32, $U20, $X20, $O40, or $B100000.

You can use an underscore (_) to divide long numbers into groups. For example, you can write the space character in binary as $B0010_0000.

Several non-printable characters have names. For example, you can write the space character as $SPACE, $SPC, or $S.

Some non-printable characters are known as control characters. But different platforms can use different control characters. For example, you can write the end-of-line character sequence as $N, which will hold $10 on Linux and $13$10 on Windows. Thus, we recommend that you use named constants to make your code easier to port.

Automatic string concatenation

You can write string literals and constants without operators between them. When you do, all such strings become concatenated at compile-time.

File path string

If you must write a file path in code, you must use the correct path separator. The problem is that this can be different on different platforms. Because of this, ViviFire has two special operators.

The operators / and \ give the path separator when put between string literals and/or constants. They are an alternative to the constants $PATHSEP and $PS. All of these give "/" on Linux and "\" on Windows. For example, "resources" / "graphics" gives "resources\graphics" on Windows.

Although the two operators are interchangeable, we recommend that you select one for all code in a project. You can use the directive @Option to cause an error if you try to use the one not selected. The applicable directives are:

@Option String Backslash
@Option String Slash

See @Option Directive for more information.

Shared methods and properties

String.CharAt(str As String, pos As Int32) As Char: Returns the character at the given position in a string. If pos is larger than the end of the string, the method raises RangeError. If you must do an operation for each character in a string, “For Each chr As Char In str” could give better results.
String.Default As String: Returns the default value, "".
String.Find(str As String, what As String, Optional start As Int32, length As Int32, flags As FindFlags) As Int32 String.Find(str As String, what As Char, Optional start As Int32, length As Int32, flags As FindFlags) As Int32: Returns the position of a substring or character (what) in a given string. If it cannot find the supplied argument, the value returned is «String.NotFound». You can optionally supply where to start (start), how many characters (length), and how to find the next index (flags). Values of FindFlags are: IgnoreCase and FromEnd.
String.Length(str As String) As Int32: Returns the number of characters in a string.
String.Lower(str As String) As String: Returns a string with upper-case letters changed to lower-case.
String.Part(str As String, start As Int32, Optional length As Int32) As String: Returns part of a string at a given position (start), and with a optional given length. If length is not given, the returned string is from start thru the end of the given string. If start is larger than the end of the given string, the method raises RangeError.
String.Reverse(s As String) As String: Returns a string with the characters written in the opposite sequence to those in the argument.
String.Upper(s As String) As String: Returns a string with lower-case letters changed to upper-case.

Examples

Declarations

Dim foo As String
Dim bar$

Different literals

Const banner = "images"/"banner.jpg"

String Data Type