Документация QSP
Сайт Форум

Эта страница только для чтения. Вы можете посмотреть исходный текст, но не можете его изменить. Сообщите администратору, если считаете, что это неправильно.
[[help:regexp|Назад: Регулярные выражения]]

====== Кортежи ======

**QSP** позволяет упаковывать несколько значений в одну переменную, а затем извлекать их оттуда. Упакованные данные называются “**кортеж**”.

Чтобы создать кортеж, нужно присвоить переменной, имя которой начинается с символа ''%%%%%'', группу значений, перечисленных в квадратных скобках через запятую. Пример:

<sxh qsp>
! создаём кортеж
%personage = ["Петя", 27, 182, 92, "боксёр"]
</sxh>

Когда мы создаём кортеж, это называется **упаковкой** данных. Обратный процесс называется **распаковкой**:

<sxh qsp>
! распаковываем данные из кортежа
$name, age, height, weight, $sports = %personage
</sxh>

Кортежи можно помещать и в отдельные ячейки массивов:

<sxh qsp>
%personage[0] = ["Петя", 27, 182, 92, "боксёр"]
%personage[1] = ["Вася", 32, 162, 57, "жокей"]
%personage[2] = ["Маша", 19, 158, 42, "фигуристка"]
%personage[3] = ["Даша", 24, 202, 81, "баскетболистка"]
</sxh>

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

<sxh qsp>
%unit = [187, 94, 'steel', [0, 2]]
</sxh>

Допустимо использовать круглые скобки ''%%()%%'' для перечисления значений кортежа, однако рекомендуется использовать именно квадратные скобки ''%%[]%%'' для улучшения читаемости кода.

<sxh qsp>
%q = (65,'ddd')  
%q = () & ! пустой кортеж  
%q = (56, (32,'sdsd'), 3)
</sxh>

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

<sxh qsp>
%q = 65,'ddd'  
local %q = 65,'ddd',33
</sxh>

===== Операции с кортежами =====

==== Объединение кортежей (конкатенация) & ====

Для объединения кортежей в один кортеж нужно использовать операцию конкатенации. Общая запись:

<sxh qsp>
[%новый_кортеж] = ([%кортеж_1] & [%кортеж_2] & ...)
</sxh>

В данном случае ставить скобки обязательно. Только так плеер поймёт, что это операция конкатенации, а не перечисление команд через амперсанд ''%%&%%''.

Пример:

<sxh qsp>
%tpl = ([1, 2] & [3, 4])
! в переменную %tpl будет записан кортеж [1, 2, 3, 4]
</sxh>

==== Увеличение значений кортежа + ====

Общая запись:

<sxh qsp>
[%новый_кортеж] = [%кортеж_1] + [значение]
</sxh>

При выполнении данной операции к каждому элементу кортежа ''%%[%кортеж_1]%%'' будет прибавлен элемент ''%%[значение]%%''. ''%%[значение]%%'' может быть кортежем, тогда каждый элемент ''%%[%кортеж_1]%%'' будет сложен с кортежем ''%%[%значение]%%''. Примеры:

<sxh qsp>
%tuple = [4, 10, 16]
%a = %tuple + 2
! %a будет равно [6, 12, 18]

[4, 10] + ['b', 'x'] & ! [4 + ['b', 'x'], 10 + ['b', 'x']]
! [['4b','4x'], ['10b','10x']]
</sxh>

==== Уменьшение значений кортежа - ====

Общая запись:

<sxh qsp>
[%новый_кортеж] = [%кортеж_1] - [#значение]
</sxh>

При выполнении данной операции из каждого элемента кортежа ''%%[%кортеж_1]%%'' будет вычтен элемент ''%%[#значение]%%''. ''%%[#значение]%%'' может быть только числом. Все остальные варианты приведут к ошибке о несоответствии типов данных. Примеры:

<sxh qsp>
%tuple = [4, 10, 16]
%a = %tuple - 2
! %a будет равно [2, 8, 14]

[4, 10] - ['b', 'x'] & ! ошибка о несоответствии типов данных
</sxh>

==== Увеличение значений кортежа * ====

Общая запись:

<sxh qsp>
[%новый_кортеж] = [%кортеж_1] * [#значение]
</sxh>

При выполнении данной операции каждый элемент кортежа ''%%[%кортеж_1]%%'' будет умножен на значение элемента ''%%[#значение]%%''. ''%%[#значение]%%'' может быть только числом. Все остальные варианты приведут к ошибке о несоответствии типов данных. Примеры:

<sxh qsp>
%tuple = [4, 10, 16]
%a = %tuple * 2
! %a будет равно [8, 20, 32]

[4, 10] * 'b' & ! ошибка о несоответствии типов данных
</sxh>

==== Сокращение значений кортежа / ====

Общая запись:

<sxh qsp>
[%новый_кортеж] = [%кортеж_1] / [#значение]
</sxh>

При выполнении данной операции каждый элемент кортежа ''%%[%кортеж_1]%%'' будет поделён на значение элемента ''%%[#значение]%%''. ''%%[#значение]%%'' может быть только числом. Все остальные варианты приведут к ошибке о несоответствии типов данных. Примеры:

<sxh qsp>
%tuple = [4, 10, 16]
%a = %tuple / 2
! %a будет равно [2, 5, 8]

[4, 10] / 'b' & ! ошибка о несоответствии типов данных
</sxh>

==== Отрицание кортежей (''-'' унарный минус) ====

Общая запись:

<sxh qsp>
[%новый_кортеж] = -[%кортеж_1]
</sxh>

Эта операция эквивалентна умножению кортежа на -1. Т.е. значения всех элементов кортежа будут умножены на -1. Примеры:

<sxh qsp>
%tpl = -[2] & ! [-2]
-[5,6,7] & ! [-5,-6,-7]
! a = 12
-[a, a+2, a+4] & ! [-12,-14,-16]
-[5,6,7]+3 & ! [-2,-3,-4]
-([5,6,7]+3) & ! [-8,-9,-10]
-[1,[2,-3],-4] & ! [-1,[-2,3],4]
</sxh>


==== Операции с присваиванием ====

Операции с присваиванием ''%%+=%%'', ''%%-=%%'', ''%%*=%%'' и ''%%/=%%'' применимы для кортежей.

Только в операции ''%%+=%%'' можно добавлять к элементам кортежей значения любых типов. В операциях ''%%-=%%'', ''%%*=%%'' и ''%%/=%%'' можно использовать только целые значения.

Примеры:

<sxh qsp>
%tuple = [5, 10, 15]
%tuple /= 5
! %tuple будет равно [1, 2, 3]
%tuple *= 10
! %tuple будет равно [10, 20, 30]
%tuple -= 10
! %tuple будет равно [0, 10, 20]
%tuple += 13
! %tuple будет равно [13, 23, 33]
</sxh>

===== Сравнение кортежей =====

Любые [[help:expressions|операции сравнения]] можно использовать и для сравнения кортежей. При этом:

  * Кортежи сравниваются поэлементно, и большим оказывается тот кортеж, элемент которого оказался большим. Примеры: <sxh qsp>
%one = [12, 13, 14]
%two = [12, 13, 99]
! %one < %two т.к. 14 < 99
%three = [13]
! %three > %one т.к. 13 > 12
</sxh>
  * Любой непустой кортеж, всегда больше пустого кортежа. Отсюда следует, что если кортежи разной длины, можно представить недостающие элементы более короткого кортежа, как пустые элементы, а они всегда меньше непустых. Примеры: <sxh qsp>
%one = [12]
%two = ['']
%empty = []
! %one > %empty
! %two > %empty

%three = [12, '']
! %three > %one
</sxh>
  * при сравнении кортежа с числом или строкой, число или строка воспринимаются движком как кортеж из одного элемента: <sxh qsp>
%one = [12, 13]
! %one > 12
! %one < 13
! [] < 0 т.к. [0] - не пустой кортеж
</sxh>
===== Функции и операторы, работающие с кортежами =====

  * ''%%LEN([%кор])%%'' - возвращает число элементов кортежа ''%%[%кор]%%''. <sxh qsp>
*pl LEN([5,7,'a']) &! на экране будет число 3
</sxh>
  * ''%%ISNUM([%кор])%%'' - проверяет, можно ли преобразовать ''%%[%кор]%%'' в число. Функция возвращает ''%%0%%'' (ложь) или ''%%1%%'' (истина). <sxh qsp>
ISNUM([' 9999 ']) &! 1
ISNUM([' -888'])  &! 1
ISNUM(['777a6'])  &! 0
ISNUM(['']) &! 0, т.к пустая строка не содержит числа
ISNUM(['1', '1']) &! 0, т.к. кортеж из двух значений
ISNUM([1, 1]) &! 0, т.к. кортеж из двух значений
</sxh>
  * ''%%VAL([%кор])%%'' - переводит кортеж ''%%[%кор]%%'' в соответствующее число. Если преобразование невозможно, возвращает ''%%0%%''. <sxh qsp>
val(['123']) & ! увидим 123
val(['']) & ! увидим 0
val(['1', 1]) & ! увидим 0
</sxh>
  * ''%%$STR([%кор])%%'' - переводит кортеж в строку. <sxh qsp>
*pl $STR([5,7,'a']) &! на экране увидим [5,7,'a']
</sxh>
  * ''%%%ARRPACK([$имя_массива], [#начальный_индекс], [#количество])%%'' - упаковывает массив ''[$имя_массива]'' в кортеж.
    * Можно указать, сколько элементов ''[#количество]'' упаковать в кортеж, и с какого элемента ''[#начальный_индекс]'' начинать упаковку. Параметры опциональны, по умолчанию ''[#начальный_индекс]'' равен нулю, а ''[#количество]'' соответствует размеру массива.
    * Функция возвращает кортеж с упакованными значениями. 
    * Примеры: <sxh qsp>
LOCAL type, name = %ARRPACK('args')
! Из массива char берём пять элементов, начиная со второго, и упаковываем в кортеж:
%unit[123] = %ARRPACK('char', 2, 5)
</sxh>
  * ''%%UNPACKARR [$имя_массива], [%кортеж], [#начальный_индекс], [#количество]%%'' - распаковывает значения из кортежа ''[%кортеж]'' в массив ''[$имя_массива]''. 
    * Можно указать, сколько элементов ''[#количество]'' распаковать, и с какого элемента ''[#начальный_индекс]'' начинать распаковку. Параметры опциональны, по умолчанию ''[#начальный_индекс]'' равен нулю, а ''[#количество]'' соответствует длине кортежа.
    * Пример: <sxh qsp>
UNPACKARR 'A', ['тест','нескольких','значений',67, ['вложенный кортеж']]
! $A[0] будет содержать 'тест'
! $A[1] будет содержать 'нескольких'
! $A[2] будет содержать 'значений'
! A[3] будет содержать 67
! %A[4] будет содержать ['вложенный кортеж']
</sxh>
    * оператор позволяет извлечь из кортежа одно значение по указанному индексу: <sxh qsp>
%tpl = ['тест','нескольких','значений',67, ['вложенный кортеж']]
UNPACKARR 'A', %tpl, 3, 1
! в A будет 67
</sxh>

===== Индексация ячеек массивов через кортежи =====

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

<sxh qsp>
! многомерный массив:
$map[1,2] = 'space'
$map[1,3] = 'space'
$map[5,7] = 'tree'
$map[0,-1] = 'hero'
*pl $map[x,y]

! можно, но не рекомендуется,
! писать так:
$map[[1,2]] = 'space'
$map[[1,3]] = 'space'
$map[[5,7]] = 'tree'
$map[[0,-1]] = 'hero'
*pl $map[[x,y]]
</sxh>

Почитать про многомерные массивы можно в соответствующем подразделе раздела [[help:arrays|“Массивы”]].

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

===== Кортеж из одного значения =====

В **QSP** 5.9.0 появилась возможность создавать кортежи из одного значения. Например:

<sxh qsp>
%tuple = [-1]
*pl %tuple & ! [-1]
</sxh>

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

<sxh qsp>
$line_map[[-1]] = 'personage'
*pl $line_map[[-1]]
</sxh>

===== Возвращение нескольких значений из функции =====

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

<sxh qsp>
!foo
%result = [12, 45]

!start
x, y = @foo()
</sxh>

===== Ограничения кортежей =====

  * Используя лишь одну пару квадратных скобок нельзя создать кортеж из более чем двадцати элементов. Пример попытки создать кортеж из 21 элемента: <sxh qsp>
%tpl = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21]
! это приведёт к ошибке: Неверное число аргументов операции/функции
</sxh> Однако вы можете создать кортеж, сколько угодно большой длины, используя конкатенацию: <sxh qsp>
%tpl = ([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20] & [21])
</sxh> **Настоятельно не рекомендуется** создавать кортежи большой длины.
  * Кортежи нельзя изменять. То есть, например, в кортеже из трёх элементов нельзя заменить второй элемент. Нужно распаковать кортеж в переменные, изменить одну из переменных и снова упаковать в кортеж: <sxh qsp>
%pos_in_space = [12, -3, 9]
x, y, z = %pos_in_space
y = -13
%pos_in_space = [x, y, z]
</sxh>
  * Нельзя извлечь из кортежа одно конкретное значение, например, второе. Зато можно извлекать одно или несколько первых значений. В этом случае из набора переменных, в которые распаковывается кортеж, имя последней должно начинаться с символа ''%%%%%'', так как в эту переменную будет упаковываться оставшаяся часть кортежа: <sxh qsp>
%personage = ["Петя", 27, 182, 92, "боксёр"]
$name, %tale = %personage
*pl $name &! 'Петя'
$name, age, height, %tale = %personage
*pl "Имя: <<$name>>, возраст: <<age>>, рост: <<height>>."
weight, $sports = %tale
*pl $sports
</sxh>
  * Как и в строках, предел объёмов данных для кортежа 2 Гигабайта или **2147483648** элементов. Величина кортежа не может превысить объём оперативной памяти.

[[help:conditional|Вперёд: Условия]]
Документация QSPСайтФорум

Инструменты пользователя

Инструменты сайта

Инструменты страницы

Документация QSP
Сайт Форум
