Формулы

Язык формул Creatium спроектирован таким образом, чтобы его можно было быстро освоить и начать использовать за максимально короткий период времени, при этом он дает большие возможности для работы с данными, которые никак иначе не доступны.

В этой статье мы разберем основы формул.

• Типы данных
  • Числа (number)
  • Строки (string)
  • Бинарные значения (boolean)
  • Массивы (array)
  • Объекты (object)
  • Даты (date)
  • Тип null (null)
• Переменные
• Доступ к элементам массива
• Доступ к значениям объекта
• Операторы
• Функции
• Комментарии

Типы данных

Числа (number)

Целые числа: 123, -34, 0 и т.д.

Дробные числа: 10.22, 0.01 и т.д.

Поддерживается математическая запись для очень больших и очень маленьких чисел:

1.602176565e-19, 6.02214129e+23 и т.д.

Строки (string)

Заключаются в одинарные (') или в двойные кавычки ("). Разного рода типографские кавычки (вроде ‘, ’, ‟, ”, и т.д.) не принимаются.

Примеры: "Hello!", "123", 'Test' и т.д.

Если внутри строки встречается такая же кавычка, как та, что используется для формирования строки, перед ней нужно поставить знак \.

Пример: "Это просто \"чудо\" какое-то". Или заключить строку в кавычки другого типа, чтобы не было конфликта кавычек одного типа: 'Это просто "чудо" какое-то'.

Бинарные значения (boolean)

Или true или false, всего 2 возможных значения. Обычно true означает нечто положительное, а false — нечто отрицательное. Да/нет, включено/выключено, в наличии/отсутвует и так далее.

Массивы (array)

Массив или список — это набор значений, разделенных запятыми, заключенный в квадратные скобки: [1, 2, 3], ["a", "b", "c"] и т.д.

Массив может содержать значения разных типов: [1, "b", false], включая вложенные массивы: [1, [12, 13], ["a", "b"]].

Объекты (object)

Объект — это набор пар ключ-значение, разделенных запятыми, заключенный в фигурные скобки. Значение может быть любого типа, а ключем может быть только строка. Между ключем и значением всегда ставится двоеточие: {"x": 12, "y": 44}, {"type": "house", "price": 1200} и т.д.

Если в названии ключа используются только латинские буквы, цифры (но не в самом начале) и символ _, то ключ можно не заключать в скобки: {name: "Hohn", age: 34}.

Как и массивы, объекты могут содержать другие вложенные объекты. Ключи в объекте не должны повторяться, но если такое случается, то “верным” значением считается последнее. То есть в объекте {x: 1, x: 2} значением ключа x будет 2.

Даты (date)

Даты записываются между двумя знаками #, в формате “год-месяц-день”: #2022-04-22#, #1994-05-04# и т.д. Ведущий ноль обязателен, то есть #1994-5-4# это уже неправильный формат.

Дата может включать так же и время:

#2022-04-22 14:05#

#2022-04-22 14:05:15# (с секундами)

#2022-04-22 14:05:15.245# (с миллисекундами)

Если не указано иное, то по умолчанию используется время по Гринвичу. Можно дополнительно указать и часовой пояс:

#2022-04-22 14:30 +05# (Нью-Йорк)

#2022-04-22 14:30 -03# (Москва)

Можно указать часовой пояс, опустив время:

#2022-04-22 -03# (00:00 по Москве)

Больше примеров

`#2022-04#` (только год и месяц, то же что `#2022-04-01 00:00#`)

`#2022-07-02T15:22:35.313Z#` (формат ISO 8601)

`#2022-04-22 14:30:15 -09:30#` (часовой пояс с минутами**)**

Тип null (null)

Означает отсутствующее значение. Единственным возможным значением этого типа данных является null.

Переменные

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

Название переменной может содержать латинские буквы, цифры и знак “_”, но не может начинаться с цифры. Несколько примеров названий переменных: memberId, url, test123.

Доступ к элементам массива

Если в переменной хранится массив, доступ к элементам осуществляется следующим образом: array[0], где 0 это номер элемента.

Обратите внимание, что нумерация начинается с 0! Первый элемент, это элемент под номером 0, второй элемент под номером 1 и так далее.

Допустим, у нас есть переменная prices, содержащая массив [25, 33, 11]. Получить второе значение массива можно следующим образом: prices[1].

Так же есть удобный способ получения последнего элемента: prices[-1], то есть при использовании отрицательного номера, элементы считаются с конца.

Доступ к значениям объекта

Похожим образом осуществляется и доступ к значениям объекта, только вместо номера в квадратных скобках мы передаем строку: object["a"], где "a" это ключ.

Допустим, у нас есть переменная man, которая содержит объект { "firts name": "John", "age": 34 }. Получить значение “first name” этого объекта можно следующим образом: man["first name"].

А так получаем значение “age”: man["age"]. Если ключ содержит только латинские буквы, цифры и символ “_”, то синтаксис можно упростить: man.age.

Операторы

Оператор — это простейшая конструкция языка.

Сложение и вычитание: `+`, `-`

• 2 + 2 ⇒ 4
• 6 - 3 ⇒ 3

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

• 5 - 2 + 5 ⇒ 8
• 5 - (2 + 5) ⇒ -2

Оператор сложения нельзя использовать со строками. Для этого есть специальный оператор объединения строк (&).

Оба оператора умеют работать с датой. В этом случае они прибавляют или вычитают миллисекунды.

• #2012-04-21 14:12:00# + 5 ⇒ #2012-04-21 14:12:00.005#

В сутках 86400000 миллисекунд (1000 миллисекнуд * 60 секунд * 60 минут * 24 часа), так можно прибавлять или вычитать дни:

• #2012-04-21 14:12:00# + 86400000 ⇒ #2012-04-22 14:12:00#
• #2012-04-21 14:12:00# - 86400000 ⇒ #2012-04-20 14:12:00#

Умножение и деление: *, /

• 25 * 4 ⇒ 100
• 10 / 5 ⇒ 2

Приоритет умножения и деления выше, чем у сложения, то есть умножение всегда выполняется первым.

• 2 + 2 * 2 ⇒ 6
• 2 * 2 + 2 ⇒ 6

Но тут тоже можно использовать скобки:

• (2 + 2) * 2 ⇒ 8

Операторы сравнения: ==, !=, >, >=, <, <=

Оператор “равно”: ==

• 10 == 20 ⇒ true
• "10" == 20 ⇒ false
• [1, 2, 3] == [1, 2, 3] ⇒ true
• [1, 2, 3] == [1, 3, 2] ⇒ false

Оператор “не равно”: !=

• 2 != 4 ⇒ true
• "4" != 4 ⇒ true
• true != true ⇒ false

Оператор “больше”: >

• 56 > 12 ⇒ true
• "b" > "a" ⇒ true

Оператор “больше или равно”: >=

Работает как оператор “больше”, но допускает так же равенство.

Оператор “меньше”: <

• 45 < 111 ⇒ true
• "e" < "z" ⇒ true

Оператор “больше или равно”: >=

Работает как оператор “меньше”, но допускает так же равенство.

Остаток от деления: %

• 10 % 3 ⇒ 1
• 5 % 7 ⇒ 5
• 7 % 5 ⇒ 2

Объединение строк: &

• "abc" & "def" ⇒ "abcdef"
• 24 & 55 ⇒ "2455"

Логический оператор and

Возвращает true если И левое И правое выражение равняются true.

• 15 > 10 and 15 < 20 ⇒ true
• 125 > 10 and 125 < 20 ⇒ false

Логический оператор or

Возвращает true если левое ИЛИ правое выражение равняются true.

• 15 > 10 or 15 < 20 ⇒ true
• 125 > 10 or 125 < 20 ⇒ true

Значение по умолчанию: ??

Позволяет указать значение, которое будет использована, если переменная, элемент массива или свойство объекта равно null.

• null ?? "default" ⇒ "default"
• 123 ?? "default" ⇒ 123

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

• array[1] ?? "something" ⇒ "something", если array[1] не существует, или равен null
• object.key ?? "something" ⇒ "something", если object.key не существует, или равен null

Функции

Список функций смотрите во вложенной статье.

Комментарии

В код формулы можно вставлять комментарии двумя способами.

Первый — конструкция /* комментарий */, которая может быть многострочной, а может занимать только часть строки.

Пример:

myDate + /* сутки */ 86400000

Часть кода /* сутки */ будет проигнорирована при выполнении формулы.

Второй — кострукция // комментарий, которая превращает в комментарий всю оставшуюся часть строки, и которую удобно использовать при перечислении элементов массива или значений объектов.

Пример:

sum([
        10,
        20,
        // 30,
        40,
])

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