# STRING Ciąg znaków. ## Pola ### TOINI ``` BOOL TOINI ``` Określa, czy wartość pola jest zapisywana do pliku INI i przywracana po ponownym uruchomieniu. ### VALUE ``` STRING VALUE ``` Aktualna wartość zmiennej. ## Metody ### ADD ``` STRING ADD(STRING text) ``` Dokleja argument do bieżącej wartości zmiennej (konkatenacja), zapisuje wynik i zwraca go. **Parametry** - `text` — tekst do dołączenia. **Zwraca**: nową wartość zmiennej. **Przykłady** ``` G_SLASTOBJECTS^ADD(VARSTEMP0); VARSMUSIC^ADD(".WAV"); S_0^ADD($1); ``` ### CHANGEAT ``` STRING CHANGEAT(INTEGER index, STRING replacement) ``` Zastępuje pojedynczy znak na pozycji `index` ciągiem `replacement`. Jeżeli `replacement` ma długość różną od `1`, długość ciągu po operacji zmienia się odpowiednio. Wywołanie z `index` poza zakresem nie zmienia wartości zmiennej. **Parametry** - `index` — pozycja znaku do zastąpienia (numerowana od `0`). - `replacement` — ciąg, którym zostanie zastąpiony znak. **Zwraca**: nową wartość zmiennej (lub niezmienioną wartość, jeśli `index` był poza zakresem). **Przykłady** ``` *VARARRAYNAME^CHANGEAT([VARCLONE-1], "NULL"); *VARENEMYSTATE^CHANGEAT([VARINT1-1], VARSTRING1); ``` ### COPYFILE ``` BOOL COPYFILE(STRING source, STRING destination) ``` Kopiuje plik w wirtualnym systemie plików gry (VFS) z lokalizacji `source` do `destination`. Metoda nie korzysta z wartości zmiennej, na której jest wywoływana — operuje wyłącznie na argumentach. **Parametry** - `source` — ścieżka pliku źródłowego w VFS. - `destination` — ścieżka pliku docelowego w VFS. **Zwraca**: [`BOOL`](BOOL.md) — `TRUE`, jeżeli kopiowanie się powiodło; `FALSE` w przeciwnym razie (np. gdy plik źródłowy nie istnieje lub wystąpił błąd I/O). **Przykłady** ``` VARSTEMP0^COPYFILE("$COMMON\ITEMS_DEF.DTA", "$COMMON\ITEMS0.DTA"); S1^COPYFILE(S1, S2); ``` ### CUT ``` STRING CUT(INTEGER index, INTEGER length) ``` Zastępuje wartość zmiennej fragmentem bieżącego ciągu, zaczynającym się od pozycji `index` i o długości `length`. Jeżeli długość przekracza dostępną liczbę znaków, fragment kończy się na końcu ciągu. Jeżeli `index` jest poza zakresem, zmienna przyjmuje wartość pustego ciągu. **Parametry** - `index` — początkowa pozycja fragmentu (numerowana od `0`). - `length` — długość fragmentu. **Zwraca**: nową wartość zmiennej. **Przykłady** ``` VARSTRING0^CUT(0, VARSTRING0^FIND("_")); ``` ### FIND ``` INTEGER FIND(STRING needle) INTEGER FIND(STRING needle, INTEGER offset) ``` Wyszukuje w bieżącej wartości zmiennej pozycję pierwszego wystąpienia podanego ciągu. Metoda nie modyfikuje wartości zmiennej. **Parametry** - `needle` — szukany ciąg. - `offset` — (opcjonalnie) pozycja, od której rozpoczyna się wyszukiwanie. Domyślnie `0`. **Zwraca**: pozycję pierwszego wystąpienia (numerowaną od `0`) lub `-1`, jeżeli ciąg nie został znaleziony. **Przykłady** ``` VARSTEMP0^FIND("IDLE"); SWYRAZ^FIND(S1); ``` ### GET ``` STRING GET() STRING GET(INTEGER index) STRING GET(INTEGER index, INTEGER length) ``` Zwraca fragment bieżącej wartości zmiennej. Metoda nie modyfikuje wartości zmiennej. - W wariancie bez argumentów zwracana jest cała wartość pola `VALUE`. - W wariantach z argumentami zwracany jest fragment zaczynający się od pozycji `index` i o długości `length` (domyślnie `1`). Jeżeli `index` jest poza zakresem, zwracany jest pusty ciąg. Jeżeli długość przekracza liczbę dostępnych znaków, fragment kończy się na końcu ciągu. **Parametry** - `index` — początkowa pozycja fragmentu (numerowana od `0`). - `length` — (opcjonalnie) długość fragmentu. Domyślnie `1`. **Zwraca**: wycięty fragment ciągu (lub całą wartość w wariancie bezargumentowym). **Przykłady** ``` VARSTEMP3^GET(7); VARENEMYNAME^GET(0, VARENEMYNAME^FIND("_")); SOBJNAME^GET(0, 1); ``` ### LENGTH ``` INTEGER LENGTH() ``` Zwraca długość bieżącej wartości zmiennej. Metoda nie modyfikuje wartości zmiennej. **Zwraca**: [`INTEGER`](INTEGER.md) — liczbę znaków w ciągu. **Przykłady** ``` VARSTEMP0^LENGTH(); ``` ### LOWER ``` STRING LOWER() ``` Zamienia wszystkie litery w bieżącej wartości zmiennej na małe. **Zwraca**: nową wartość zmiennej. ### REPLACEAT ``` STRING REPLACEAT(INTEGER index, INTEGER length, STRING replacement) ``` Zastępuje fragment bieżącego ciągu o długości `length`, zaczynający się od pozycji `index`, ciągiem `replacement`. Jeżeli długość fragmentu przekracza dostępne znaki, podmieniana jest reszta ciągu. Wywołanie z `index` poza zakresem nie zmienia wartości zmiennej. **Parametry** - `index` — początkowa pozycja podmienianego fragmentu (numerowana od `0`). - `length` — długość podmienianego fragmentu. - `replacement` — ciąg, który zostanie wstawiony w miejsce fragmentu. **Zwraca**: nową wartość zmiennej (lub niezmienioną wartość, jeśli `index` był poza zakresem). **Przykłady** ``` S3^REPLACEAT(0, 1, S1); VARSTMP2^REPLACEAT(8, 2, ["00"+VARIKRAINANO]); ``` ### RESETINI ``` STRING RESETINI() ``` Przywraca wartość zmiennej do wartości resetu zdefiniowanej w atrybutach obiektu w skrypcie. Silnik szuka wartości w kolejności: `DEFAULT` → `INIT_VALUE` → `VALUE`; używana jest pierwsza znaleziona. Jeśli żadna z nich nie jest ustawiona, wartość ustawiana jest na pusty ciąg. **Zwraca**: nową wartość zmiennej. ### SET ``` STRING SET(STRING value) ``` Ustawia wartość zmiennej. **Parametry** - `value` — nowa wartość. **Zwraca**: nową wartość zmiennej. **Przykłady** ``` SCENENAME^SET(PRZYGODA^GETCURRENTSCENE()); VARSTEMP0^SET(["BEHCLICK_"+SOBJECT|IDNAME]); VARSTEMP0^SET($1); ``` ### SUB ``` STRING SUB(INTEGER index, INTEGER length) ``` Usuwa z bieżącej wartości zmiennej fragment o długości `length`, zaczynający się od pozycji `index`. Pozostałe fragmenty (przed i za usuwanym) są scalane. Wywołanie z `index` poza zakresem nie zmienia wartości zmiennej. **Parametry** - `index` — początkowa pozycja usuwanego fragmentu (numerowana od `0`). - `length` — długość usuwanego fragmentu. **Zwraca**: nową wartość zmiennej (lub niezmienioną wartość, jeśli `index` był poza zakresem). **Przykłady** ``` VARSTEMP0^SUB(0, 5); VARSTEMP0^SUB(VARITEMP0, [VARSTEMP0^LENGTH()-VARITEMP0]); ``` ### UPPER ``` STRING UPPER() ``` Zamienia wszystkie litery w bieżącej wartości zmiennej na wielkie. **Zwraca**: nową wartość zmiennej. **Przykłady** ``` SDIALOGWAVENAME^UPPER(); SDIALOGPERSON^UPPER(); ``` ## Sygnały ### ONCHANGED Wywoływany, gdy wartość zmiennej zostaje zmieniona na inną niż dotychczasowa. ### ONBRUTALCHANGED Wywoływany przy każdym wywołaniu metody zmieniającej wartość, niezależnie od tego, czy nowa wartość różni się od poprzedniej. ### ONINIT Wywoływany w momencie inicjalizacji zmiennej.