Иногда нам становится неудобно хранить множество однотипных значений в разных переменных. Например, у нас есть двадцать "одноручных мечей" и для каждого мы прописали урон в двадцати разных переменных:

меч_одноручный_1 = 23
меч_одноручный_2 = 34
меч_одноручный_3 = 27
...
меч_одноручный_19 = 7
меч_одноручный_20 = 41

Даже для того, чтобы просто вывести на экран данную характеристику для каждого меча, нам придётся написать двадцать строчек кода, почти ничем не отличающихся:

*pl "Меч одноручный №1. Урон: "+$str(меч_одноручный_1)
*pl "Меч одноручный №2. Урон: "+$str(меч_одноручный_2)
*pl "Меч одноручный №3. Урон: "+$str(меч_одноручный_3)
...
*pl "Меч одноручный №19. Урон: "+$str(меч_одноручный_19)
*pl "Меч одноручный №20. Урон: "+$str(меч_одноручный_20)

И всё бы ничего, но что если нам нужно найти среди всех этих переменных ту, которая содержимт максимальное число (мы ведь хотим пользоваться самым хорошим мечом)? Тут нам придётся городить огромную конструкцию условий, которая сравнивает каждую переменную со всеми остальными, и объём необходимого нам кода возрастает многократно.

Да, есть некоторые варианты решения этих двух задач без использования массивов, но они тоже весьма сложны. Куда как проще работать с однотипными данными, если они представлены в форме массива.

Если переменную мы можем вообразить в виде отдельной маленькой коробки, в которую можно положить лишь одно значение, то массив — это большой шкаф, со множеством пронумерованных ящиков (ячеек), в каждый из которых мы можем положить по одному значению.

Массив - в QSP это последовательный набор однотипных значений, записанных под одним общим именем. Например, вместо того, чтобы помещать урон каждого одноручного меча в отдельную переменную, мы заводим один массив, и размещаем каждое значение урона в отдельных ячейках этого самого одного единственного массива:

меч_одноручный[0] = 23 & ! нумерация ячеек массива начинается с нуля
меч_одноручный[1] = 34
меч_одноручный[2] = 27
...
меч_одноручный[18] = 7
меч_одноручный[19] = 41 & ! значение для двадцатого меча лежит в ячейке под номером 19

Как видно из примера, чтобы записать значение в отдельную ячейку массива, мы должны:

• написать имя массива
• затем без пробелов, не отступая от имени массива, в квадратных скобках написать номер ячейки, в которую хотим поместить значение
• затем поставить знак = (операция присвавивания)
• и уже после знака равно написать нужное значение.

В нашем примере массив называется "меч_одноручный", а в квадратных скобках мы указываем номера ячеек этого массива.

Записывая значения хотя бы в одну ячейку массива, мы тем самым создаём (инициализируем) весь массив.

• Ячейки массива так же называются элементами.
• Каждый массив состоит из множества элементов, и у каждого элемента есть собственный номер.
• Номера элементов начинаются с нуля и не повторяются.
• Нумерация элементов массива не прерывается. То есть, например, не может в массиве существовать четвёртый элемент, но отсутствовать второй и третий элемент. Если мы создадим только нулевой и первый, а так же четвёртый, элементы массива, второй и третий элементы будут созданы автоматически:

  	mass[0]=13
  	mass[1]=19
  	mass[4]=23
  	! элементы mass[2] и mass[3] созданы автоматически и хранят значения по умолчанию
  

• Максимальный возможный номер ячейки массива 2147483647.

Массив можно представлять себе как список значений. Если вам нужно хранить только одно значение, достаточно обычной переменной, но если вам нужно сохранить множество значений, как некий список, то обязательно используйте массив. Например, вы можете вести список имён всех встреченных персонажей:

$встреченные_неписи[0]="Домовёнок Нафаня"
$встреченные_неписи[1]="Девочка Оля"
$встреченные_неписи[2]="Лариса Петровна"
$встреченные_неписи[3]="Баба Яга"

В данном примере мы помещали в массив строковые значения. Чтобы поместить в ячейку массива строковое значение, нужно поставить перед именем массива символ $.

То же самое и в случае, когда мы хотим получить значение из ячейки массива: если мы хотим получить числовое значение ячейки массива, символ $ перед именем массива не ставится; если мы хотим получить строковое значение ячейки массива, нужно поставить символ $ перед именем массива.

Примеры:

$яблоки[0]='антоновка'
$яблоки[1]='белый налив'
$яблоки[2]='астраханское'
$яблоки[3]='ранетка'
$яблоки[4]='симиренко'

сорт_яблока[0] = 1
сорт_яблока[1] = 2
сорт_яблока[2] = 4

*pl $яблоки[сорт_яблока[номер_яблока]]

В одном массиве допускается хранить и строковые, и числовые значения, однако строго рекомендуется хранить в одном массиве только значения одного типа: либо строковые, либо числовые, — во избежание возможных багов.

В одной ячейке массива можно хранить либо только строковое, либо только числовое значение! Если вы запишете в ячейку, хранящую строкове значение, числовое — это числовое значение "затрёт" строковое. И наоборот.

Преимущество работы с массивами по сравнению с обычными переменными раскрывается тогда, когда нам приходится много раз повторять одну и ту же операцию над однотипными значениями.

В примере из начала статьи мы помещали наносимый одноручным мечом урон для двадцати разных мечей в двадцать отдельных переменных и видели, что даже такая простая операция, как вывод значений всех этих переменных на экран требует огромного количества кода. Совсем другое дело, когда мы поместили наши данные в массив, ведь мы можем перебрать весь массив с помощью простого цикла:

меч_одноручный[0] = 23 & ! нумерация ячеек массива начинается с нуля
меч_одноручный[1] = 34
меч_одноручный[2] = 27
...
меч_одноручный[18] = 7
меч_одноручный[19] = 41 & ! значение для двадцатого меча лежит в ячейке под номером 19

! выводим на экран список с помощью цикла
loop i=0 while i<20 step i+=1:
	*pl "Меч одноручный №<<i+1>>. Урон: "+$str(меч_одноручный[i])
end

В этом примере для вывода на экран всех значений из всех двадцати ячеек массива нам потребовалось написать всего три строчки кода.

А вот как выглядит поиск одноручного меча с наибольшим значением урона:

pos = arrpos('меч_одноручный',max('меч_одноручный'))
*pl "Наибольший урон имеет Меч одноручный №<<pos+1>>: "+$str(меч_одноручный[pos])

В обоих этих примерах вместо указания конкретного номера ячейки массива, при получении данных из массива, мы подставляли значение переменной. Именно эта возможность позволяет так легко и быстро обрабатывать множество данных в массивах, и делает работу с ними более удобной, чем с обычными переменными.

Выше мы писали, что ячейки массивов нумеруются подряд, начиная с нуля, и нумерация эта не прерывается. Номер ячейки массива называется числовым индексом ячейки массива.

! ячейки массивов индексируются через числа
$любимый_сорт[3] = $яблоки[2]
любимое_число[19] = 5
$item_loc[0] = 'лес'

Важно! Настоятельно не рекомендуется использовать большие числовые индексы без необходимости.

QSP позволяет создавать для элементов массивов не только числовые, но и строковые индексы. Иными словами массивы могут индексироваться через строки. Примеры:

! ячейки массивов индексируются через строки
$любимый_сорт['Иван'] = $яблоки[2]
любимое_число['Алексей'] = 5
$item_loc['палка'] = 'лес'

Регистр символов в строковом индексе массива значения не имеет:

$любимый_сорт['иван']='Антоновка'
*pl $любимый_сорт['ИВАН'] & ! выведет строку Антоновка
``` 

Есть небольшая хитрость в том, как назначаются строковые индексы ячейкам массивов. Когда вы инициализируете (создаёте; объявляете) новую ячейку массива со строковым индексом, происходит следующее:
	* Плеер создаёт новую ячейку с новым числовым индексом, следующим по порядку. Например, если в массиве уже были созданы три ячейки, создаётся ячейка с числовым индексом ''**3**''.
	* Затем плеер "прикрепляет" указанный строковый индекс к числовому.

Поэтому, если вы создаёте ячейку со строковым индексом, вы можете получать из неё значения в том числе и по числовому индексу:

<sxh qsp>
яблоки['у Паши']=37
яблоки['у Даши']=19
яблоки['у Лёши']=11
*pl яблоки[0] & ! выведет на экран число 37
*pl яблоки[1] & ! выведет на экран число 19
*pl яблоки[2] & ! выведет на экран число 11

Настоятельно рекомендуется использовать для индексирования или только числовые индексы, или только строковые индексы.

Текстовые индексы позволяют обойти ограничение массивов на начало нумерации только с нуля:

$item['-2']='Палка'
$item['-1']='Дрель'
$item['0']='Радиоактивный пепел'

В QSP есть возможность создавать многомерные массивы, используя для этого специальные индексы:

$map[1,2]='лес'
$map[1,3]='лес'
$map[2,2]='лес'
$map[4,0]='река'

В данном примере в квадратных скобках вместо номера ячейки мы указываем числа, перечисляемые через запятую. Таким образом мы создаём ячейки двумерного массива.

Числа в квадратных скобках — это строка значений, или кортеж. Далее по тексту мы будем называть их строкой значений.

Используя для индексации элементов массивов строку значений, мы можем создавать трёхмерные, четырёхмерные, и вообще сколькиугодно-мерные массивы:

$space[0,-2,9]='космический корабль'
value_time[12,33,1,366]=137
макрокосмос_миллиардов_микрокосм[12,34,12,98,76,30,11,19,137,90]=991112

Для многомерных индексов можно использовать не только числовые значения, но и строковые:

данные['таблица_данных',0,1]=73
яблоки['Паша','левый карман']=91
яблоки['Миша','правый карман']=10
$map[12,14,'слой_подземелья']="стена"

Есть небольшая хитрость в том, как назначаются многомерные индексы ячейкам массивов. Когда вы инициализируете (создаёте; объявляете) новую ячейку массива с многомерным индексом, происходит следующее:

• Плеер создаёт новую ячейку с новым числовым индексом, следующим по порядку. Например, если в массиве уже были созданы семь ячеек, создаётся ячейка с числовым индексом 7.
• Затем плеер "прикрепляет" указанный многомерный индекс к числовому.

Поэтому, если вы создаёте ячейку с многомерным индексом, вы можете получать из неё значения в том числе и по числовому индексу:

яблоки['у Паши','левый карман']=37
яблоки['у Паши','правый карман']=5
яблоки['у Лёши','левый карман']=11
яблоки['у Лёши','правый карман']=19
*pl яблоки[0] & ! выведет на экран число 37
*pl яблоки[1] & ! выведет на экран число 5
*pl яблоки[2] & ! выведет на экран число 11
*pl яблоки[3] & ! выведет на экран число 19

Настоятельно рекомендуется использовать для индексирования или только числовые индексы, или только многомерные индексы.

На самом деле каждая переменная в QSP является массивом, состоящим из одной единственной ячейки:

яблоки = 0
!эквивалентно
яблоки[0] = 0

Таким образом вы всегда можете получить или присвоить данные нулевой ячейке массива, просто указав его имя:

! присваиваем нулевой ячейке массива '$COUNTER' строковое значение
$counter='счётчик'
*pl $counter[0] & ! проверяем
! присваиваем нулевым ячейкам массивов red, green, blue значения
set red[0],green[0],blue[0]=234,198,77
*pl "red: <<red>>, green: <<green>>, blue: <<blue>>" & ! проверяем

Существует упрощённый синтаксис чтения последнего и добавления нового элемента в массив. Для этого квадратные скобки пишутся без указания индекса:

• при записи значения в массив будет создан новый элемент сразу за последним. Например:

  	! Если массив был пустой, то
  	$objs[] = 'Напильник' &! $objs[0] = 'Напильник'
  	$objs[] = 'Топор'     &! $objs[1] = 'Топор'
  	$objs[] = 'Доска'     &! $objs[2] = 'Доска'
  	``` 
  	*  при получении значенияиз массива будет выбран последний элемент. Например: <sxh qsp>
  	*pl $objs[] &! 'Доска' из примера выше
  

• KILLVAR [$имя_массива], [индекс_элемента] - удаление элемента с индексом [индекс_элемента] из массива с названием [$имя_массива]. Название массива всегда нужно писать в кавычках. Пример:

  	! удаление по числовому индексу
  	killvar 'яблоко',3
  	! удаление элемента по строковому индексу
  	killvar '$item_loc','палка'
  	! удаление элемента по многомерному индексу
  	killvar '$space',(0,-2,9)
  

  • Если индекс элемента не указан, то удаляется весь массив.

    		! удаляем массив $map целиком
    		killvar '$map'
    

  • Если оператор вызван без аргументов, то удаляются все массивы и переменные в игре!

    		! удаляем все массивы и переменные
    		KILLVAR
    

  • При удалении элемента все следующие за ним элементы сдвигаются на позицию вверх.

    		a[0]=4
    		a[1]=3
    		a[2]=23
    		a[3]=15
    		KILLVAR 'a',1
    		!теперь массив выглядит так:
    		a[0]=4
    		a[1]=23
    		a[2]=15
    

• KILLALL - оператор эквивалентен конструкции "KILLVAR & KILLOBJ", то есть удаляет все переменные, массивы в игре, а так же очищает Окно предметов. Обычно применяется в начале игры, чтобы при возврате в начальную локацию после неудачного прохождения какого-то этапа игры обнулить все переменные (в противном случае, может оказаться, что запертые двери уже открыты, жена похищена до свадьбы, а Баба-Яга уже отдала кому-то нужный клубочек).
• COPYARR [$приёмник],[$источник],[#начало],[#количество] - копирование в массив-приёмник [#количество] элементов из массива-источника начиная с элемента под номером [#начало]. Размер массива-приёмника при копировании не имеет значения.
  • Параметр [#количество] является необязательным. По умолчанию - до конца массива-источника.
  • Параметр [#начало] является необязательным. По умолчанию - 0.
  • Не имеет значения, указываете ли вы $ перед названием массива или нет. Копируются элементы и со строковыми, и с числовыми значениями.
  • Примеры:

    		COPYARR '$a','$b'
    		COPYARR 'a','b'
    		COPYARR $arrname1,$arrname2,10,5
    		COPYARR 'a<<$arrname1>>','a<<$arrname2>>'
    

• ARRSIZE([$имя_массива]) - функция возвращает число элементов массива с названием [$имя_массива].
  • Не имеет значения, указываете ли вы $ перед названием массива или нет. Подсчитывается общее число ячеек и со строковыми, и с числовыми значениями.
  • Примеры:

    		n = ARRSIZE('a')
    		n = ARRSIZE('$a')
    		!Результат будет одинаковый
    

• ARRITEM([$имя_массива],[индекс_элемента]) — возвращает значение элемента массива с названием [$имя_массива] по указанному индексу. То есть функция извлекает значение из указанной ячейки массива. Примеры:

  		! выводим значение элемента с индексом 3
  		*pl $arritem('$mass', 3)
  		! выводим значение элемента с текстовым индексом
  		*pl $arritem('$mass', 'Петя')
  		! выводим значение элемента с многомерным индексом
  		*pl $arritem('$mass', (-2, 9, 0))
  

  Эта функция может быть полезна для извлечения значений, если имя массива заранее не известно. Пример:

  		! выводим содержимое нескольких массивов без использования ''**DYNAMIC**'':
  		$array_name[]='mass_1'
  		$array_name[]='mass_2'
  		$array_name[]='mass_3'
  		$array_name[]='mass_4'
  		$array_name[]='mass_5'
  		! внешний цикл перебирает имена массивов
  		loop local j=0 while j<arrsize('$array_name') step j+=1:
  			! внутренний цикл выводит содержимое массивов
  			loop local i=0 while i<arrsize($array_name[j]) step i+=1:
  				*pl arritem($array_name[j], i)
  			end
  		end
  

• ARRPOS([$имя_массива],[значение],[#начало]) - возвращает номер элемента массива с названием [$имя_массива], равного значению [значение]. Поиск начинается с элемента под номером [#начало]; индексация элементов массива ведётся с нуля. Если указанное значение не найдено, функция возвращает -1.
  • Параметр [#начало] может отсутствовать, при этом он принимается равным 0.
  • Примеры:

    		!Поиск строки 'This' в текстовом массиве "$A"
    		ARRPOS('$A','This',0)
    		!Поиск числа 65 в массиве "A" (первые два элемента массива игнорируются)
    		ARRPOS('A',65,2)
    		!Поиск строки 'test' среди значений массива "$B"
    		ARRPOS('$B','test')
    

  • Функция возвращает только числовой индекс элемента. Строковый или многомерный индекс с помощью данной функции получить нельзя.
• MAX([выр1],[выр2], …) - возвращает максимальное из значений выражений-аргументов. Если передан один аргумент, то считается, что указано имя массива:

  	MAX('a') &! вернёт максимальное из числовых значений элементов массива "a"
  	MAX('$b') &! вернёт максимальное из текстовых значений элементов массива "$b"
  

• MIN([выр1],[выр2], …) - возвращает минимальное из значений выражений-аргументов. Если передан один аргумент, то считается, что указано имя массива:

  	MIN('a') &! вернёт минимальное из числовых значений элементов массива "a"
  	MIN('$b') &! вернёт минимальное из текстовых значений элементов массива "$b"
  

• ARRCOMP([$имя_массива],[$шаблон],[#начало]) - возвращает номер элемента массива [$имя_массива], соответствующего регулярному выражению [$шаблон]. Поиск начинается с элемента с номером [#начало]; индексация элементов массива ведётся с нуля. Если указанное значение не найдено, функция возвращает -1.
  • Поиск работает только по текстовым массивам (символ $ в названии массива можно опустить).
  • Параметр [#начало] может отсутствовать, при этом он принимается равным 0.
  • Примеры:

    		!Поиск строки 'This' среди элементов массива "$A"
    		ARRCOMP('$A','This',0)
    		!'Поиск строки, соответствующей регулярному выражению "abc\d+"
    		(первые два элемента массива игнорируются)'
    		ARRCOMP('$A','abc\d+',2)
    		!'аналогично предыдущему примеру, но поиск осуществляется
    		по всем элементам массива'
    		ARRCOMP('$A','.*string.*',0) 
    		ARRCOMP('$A','This') &! эквивалентно 1му варианту
    

  • Функция возвращает только числовой индекс элемента. Строковый или многомерный индекс с помощью данной функции получить нельзя.

Вперёд: Строки