298 lines
6.8 KiB
Markdown
298 lines
6.8 KiB
Markdown
# STRING
|
|
|
|
Character string.
|
|
|
|
## Fields
|
|
|
|
### TOINI
|
|
|
|
```
|
|
BOOL TOINI
|
|
```
|
|
|
|
Controls whether the field's value is persisted to an INI file and restored on the next run.
|
|
|
|
### VALUE
|
|
|
|
```
|
|
STRING VALUE
|
|
```
|
|
|
|
The current value of the variable.
|
|
|
|
## Methods
|
|
|
|
### ADD
|
|
|
|
```
|
|
STRING ADD(STRING text)
|
|
```
|
|
|
|
Appends the argument to the variable's current value (string concatenation), stores the result, and returns it.
|
|
|
|
**Parameters**
|
|
|
|
- `text` — the text to append.
|
|
|
|
**Returns**: the new value of the variable.
|
|
|
|
**Examples**
|
|
|
|
```
|
|
G_SLASTOBJECTS^ADD(VARSTEMP0);
|
|
VARSMUSIC^ADD(".WAV");
|
|
S_0^ADD($1);
|
|
```
|
|
|
|
### CHANGEAT
|
|
|
|
```
|
|
STRING CHANGEAT(INTEGER index, STRING replacement)
|
|
```
|
|
|
|
Replaces the single character at position `index` with the `replacement` string. If `replacement` is not exactly one character long, the resulting string length changes accordingly. Calling with an `index` outside the string's range leaves the variable unchanged.
|
|
|
|
**Parameters**
|
|
|
|
- `index` — position of the character to replace (`0`-based).
|
|
- `replacement` — the string to insert in place of the character.
|
|
|
|
**Returns**: the new value of the variable (or the unchanged value if `index` was out of range).
|
|
|
|
**Examples**
|
|
|
|
```
|
|
*VARARRAYNAME^CHANGEAT([VARCLONE-1], "NULL");
|
|
*VARENEMYSTATE^CHANGEAT([VARINT1-1], VARSTRING1);
|
|
```
|
|
|
|
### COPYFILE
|
|
|
|
```
|
|
BOOL COPYFILE(STRING source, STRING destination)
|
|
```
|
|
|
|
Copies a file inside the game's virtual file system (VFS) from `source` to `destination`. The method does not use the receiver variable's value — only the arguments matter.
|
|
|
|
**Parameters**
|
|
|
|
- `source` — path of the source file in the VFS.
|
|
- `destination` — path of the destination file in the VFS.
|
|
|
|
**Returns**: [`BOOL`](BOOL.md) — `TRUE` if the copy succeeded; `FALSE` otherwise (e.g. the source file does not exist or an I/O error occurred).
|
|
|
|
**Examples**
|
|
|
|
```
|
|
VARSTEMP0^COPYFILE("$COMMON\ITEMS_DEF.DTA", "$COMMON\ITEMS0.DTA");
|
|
S1^COPYFILE(S1, S2);
|
|
```
|
|
|
|
### CUT
|
|
|
|
```
|
|
STRING CUT(INTEGER index, INTEGER length)
|
|
```
|
|
|
|
Replaces the variable's value with a substring of the current value, starting at position `index` and of `length` characters. If the requested length exceeds the available characters, the substring stops at the end of the string. If `index` is out of range, the variable becomes an empty string.
|
|
|
|
**Parameters**
|
|
|
|
- `index` — starting position of the substring (`0`-based).
|
|
- `length` — length of the substring.
|
|
|
|
**Returns**: the new value of the variable.
|
|
|
|
**Examples**
|
|
|
|
```
|
|
VARSTRING0^CUT(0, VARSTRING0^FIND("_"));
|
|
```
|
|
|
|
### FIND
|
|
|
|
```
|
|
INTEGER FIND(STRING needle)
|
|
INTEGER FIND(STRING needle, INTEGER offset)
|
|
```
|
|
|
|
Searches the variable's current value for the first occurrence of the given string. This method does not modify the variable.
|
|
|
|
**Parameters**
|
|
|
|
- `needle` — the string to search for.
|
|
- `offset` — (optional) position from which the search starts. Defaults to `0`.
|
|
|
|
**Returns**: the position of the first occurrence (`0`-based), or `-1` if the string was not found.
|
|
|
|
**Examples**
|
|
|
|
```
|
|
VARSTEMP0^FIND("IDLE");
|
|
SWYRAZ^FIND(S1);
|
|
```
|
|
|
|
### GET
|
|
|
|
```
|
|
STRING GET()
|
|
STRING GET(INTEGER index)
|
|
STRING GET(INTEGER index, INTEGER length)
|
|
```
|
|
|
|
Returns a fragment of the variable's current value. This method does not modify the variable.
|
|
|
|
- Without arguments, returns the full value of the `VALUE` field.
|
|
- With arguments, returns a substring starting at `index` and of `length` characters (default `1`).
|
|
|
|
If `index` is out of range, an empty string is returned. If the requested length exceeds the available characters, the substring stops at the end of the string.
|
|
|
|
**Parameters**
|
|
|
|
- `index` — starting position of the substring (`0`-based).
|
|
- `length` — (optional) length of the substring. Defaults to `1`.
|
|
|
|
**Returns**: the extracted substring (or the full value in the no-argument form).
|
|
|
|
**Examples**
|
|
|
|
```
|
|
VARSTEMP3^GET(7);
|
|
VARENEMYNAME^GET(0, VARENEMYNAME^FIND("_"));
|
|
SOBJNAME^GET(0, 1);
|
|
```
|
|
|
|
### LENGTH
|
|
|
|
```
|
|
INTEGER LENGTH()
|
|
```
|
|
|
|
Returns the length of the variable's current value. This method does not modify the variable.
|
|
|
|
**Returns**: [`INTEGER`](INTEGER.md) — the number of characters in the string.
|
|
|
|
**Examples**
|
|
|
|
```
|
|
VARSTEMP0^LENGTH();
|
|
```
|
|
|
|
### LOWER
|
|
|
|
```
|
|
STRING LOWER()
|
|
```
|
|
|
|
Converts all letters in the variable's current value to lowercase.
|
|
|
|
**Returns**: the new value of the variable.
|
|
|
|
### REPLACEAT
|
|
|
|
```
|
|
STRING REPLACEAT(INTEGER index, INTEGER length, STRING replacement)
|
|
```
|
|
|
|
Replaces a fragment of the current string of `length` characters, starting at position `index`, with the `replacement` string. If the requested length exceeds the available characters, the rest of the string is replaced. Calling with an `index` outside the string's range leaves the variable unchanged.
|
|
|
|
**Parameters**
|
|
|
|
- `index` — starting position of the replaced fragment (`0`-based).
|
|
- `length` — length of the replaced fragment.
|
|
- `replacement` — the string that will replace the fragment.
|
|
|
|
**Returns**: the new value of the variable (or the unchanged value if `index` was out of range).
|
|
|
|
**Examples**
|
|
|
|
```
|
|
S3^REPLACEAT(0, 1, S1);
|
|
VARSTMP2^REPLACEAT(8, 2, ["00"+VARIKRAINANO]);
|
|
```
|
|
|
|
### RESETINI
|
|
|
|
```
|
|
STRING RESETINI()
|
|
```
|
|
|
|
Resets the variable's value to the reset value defined in the object's script attributes. The engine looks up the value in the following order: `DEFAULT` → `INIT_VALUE` → `VALUE`; the first one found is used. If none of them is set, the value is reset to an empty string.
|
|
|
|
**Returns**: the new value of the variable.
|
|
|
|
### SET
|
|
|
|
```
|
|
STRING SET(STRING value)
|
|
```
|
|
|
|
Sets the variable's value.
|
|
|
|
**Parameters**
|
|
|
|
- `value` — the new value.
|
|
|
|
**Returns**: the new value of the variable.
|
|
|
|
**Examples**
|
|
|
|
```
|
|
SCENENAME^SET(PRZYGODA^GETCURRENTSCENE());
|
|
VARSTEMP0^SET(["BEHCLICK_"+SOBJECT|IDNAME]);
|
|
VARSTEMP0^SET($1);
|
|
```
|
|
|
|
### SUB
|
|
|
|
```
|
|
STRING SUB(INTEGER index, INTEGER length)
|
|
```
|
|
|
|
Removes from the variable's current value a fragment of `length` characters, starting at position `index`. The remaining parts (before and after the removed fragment) are concatenated. Calling with an `index` outside the string's range leaves the variable unchanged.
|
|
|
|
**Parameters**
|
|
|
|
- `index` — starting position of the removed fragment (`0`-based).
|
|
- `length` — length of the removed fragment.
|
|
|
|
**Returns**: the new value of the variable (or the unchanged value if `index` was out of range).
|
|
|
|
**Examples**
|
|
|
|
```
|
|
VARSTEMP0^SUB(0, 5);
|
|
VARSTEMP0^SUB(VARITEMP0, [VARSTEMP0^LENGTH()-VARITEMP0]);
|
|
```
|
|
|
|
### UPPER
|
|
|
|
```
|
|
STRING UPPER()
|
|
```
|
|
|
|
Converts all letters in the variable's current value to uppercase.
|
|
|
|
**Returns**: the new value of the variable.
|
|
|
|
**Examples**
|
|
|
|
```
|
|
SDIALOGWAVENAME^UPPER();
|
|
SDIALOGPERSON^UPPER();
|
|
```
|
|
|
|
## Signals
|
|
|
|
### ONCHANGED
|
|
|
|
Fired when the variable's value is changed to one different from the previous one.
|
|
|
|
### ONBRUTALCHANGED
|
|
|
|
Fired on every call that sets the value, regardless of whether the new value differs from the previous one.
|
|
|
|
### ONINIT
|
|
|
|
Fired when the variable is initialised.
|