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 (""), then 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, then all such strings become concatenated at compile-time.

File path string

If you must write a file path in code, then 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:

See @Option Directive for more information.

Shared methods and properties

String.CharAt(str As String, pos As Int) As Char
Returns the character at the given position in a string. If pos is larger than the end of the string, then the method raises RangeError. If you must do an operation for each character in a string, then “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 Int, length As Int, flags As FindFlags) As Int
String.Find(str As String, what As Char, Optional start As Int, length As Int, flags As FindFlags) As Int
Returns the position of a substring or character (what) in a given string. If it cannot find the supplied argument, then 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 Int
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 Int, Optional length As Int) As String
Returns part of a string at a given position (start), and with a optional given length. If length is not given, then the returned string is from start thru the end of the given string. If start is larger than the end of the given string, then 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"

See also