functional.yml

name: functional
scope: "both"
desc: "Contains functions for operating data in functional style"
desc_ru: "Содержит функции для работы с данными в функциональном стиле"
constants:
  - name: "IDENTITY"
    typeName: "function"
    type: 5
    value: "def(x) = x"
    desc: "function which returns passed argument"
    desc_ru: "функция, которая возвращает переданный в неё аргумент"
functions:
  - name: chain
    args: "data, functions..."
    desc: ""
    desc_ru: ""
  - name: combine
    args: "functions..."
    desc: "combines functions"
    desc_ru: "комбинирует функции (композиция)"
    example: |-
      use functional
      
      def f1() = 2
      def f2(a) = a*2
      def f3(a) = a/4
      
      f = combine(::f1, ::f2, ::f3)
      println f() // 1
      // same as
      f = def() = f3(f2(f1()))
      println f() // 1
    example_ru: |-
      use functional
      
      def f1() = 2
      def f2(a) = a*2
      def f3(a) = a/4
      
      f = combine(::f1, ::f2, ::f3)
      println f() // 1
      // равносильно
      f = def() = f3(f2(f1()))
      println f() // 1
  - name: dropwhile
    args: 'data, predicate'
    desc: 'skips elements while predicate function returns true'
    desc_ru: 'пропускает элементы пока функция-предикат возвращает true'
  - name: "filter"
    args: "data, predicate"
    desc: "filters array or object.\n\n`predicate` is a function which takes one argument for arrays or two arguments for objects"
    desc_ru: "фильтрует массив или объект и возвращает массив только с теми элементами, которые удовлетворяют предикату `predicate`.\n\n`predicate` - функция которая принимает один (для массивов) и два (для объектов) аргумента"
    example: |-
      use functional
      
      nums = [1,2,3,4,5]
      print filter(nums, def(x) = x % 2 == 0) // [2, 4]
  - name: flatmap
    args: "array, mapper"
    desc: "converts each element of an array to other array"
    desc_ru: "преобразует каждый элемент массива в массив элементов"
    example: |-
      use functional
      
      nums = [1,2,3,4]
      print flatmap(nums, def(x) {
        arr = newarray(x)
        for i = 0, i < x, i++
          arr[i] = x
        return arr
      }) // [1, 2, 2, 3, 3, 3, 4, 4, 4, 4]
  - name: foreach
    args: "data, consumer"
    desc: "invokes function `consumer` for each element of array or map `data`\n\nIf `data` - массив, то в функции consumer необходим один параметр, если объект - два (ключ и значение)."
    desc_ru: "для каждого элемента в массиве или объекте `data` вызывает функцию `consumer`\n\nЕсли `data` - массив, то в функции `consumer` необходим один параметр, если объект - два (ключ и значение)."
    example: |-
      use functional
      
      foreach([1, 2, 3], def(v) { print v })
      foreach({"key": 1, "key2": "text"}, def(key, value) {
        print key + ": " + value
      })
  - name: map
    args: "data, mapper..."
    desc: "converts elements of array or map. If `data` is array - `mapper` converts his elements, if `data` is object - you need to pass `keyMapper` - converts keys and `valueMapper` - converts values"
    desc_ru: "преобразует элементы массива или объекта.\n\nЕсли `data` - массив, то функция `mapper` преобразует значения, если объект - необходимо передать две функции: `keyMapper` - преобразует ключи и `valueMapper` - преобразует значения"
    example: |-
      use functional
      
      nums = [3,4,5]
      print map(nums, def(x) = x * x) // [9, 16, 25]
  - name: reduce
    args: "data, identity, accumulator"
    desc: "converts elements of an array or a map to one value, e.g. sum of elements or concatenation string. `accumulator` takes one argument for array and two arguments for object (key and value)."
    desc_ru: "преобразует элементы массива или объекта в одно значение, например сумма элементов или объединение в строку.\n\nЕсли `data` - массив, то в функции `accumulator` необходим один параметр, если объект - два (ключ и значение)"
    example: |-
      use functional
      
      nums = [1,2,3,4,5]
      print reduce(nums, 0, def(x, y) = x + y) // 15
  - name: sortby
    args: "array, function"
    desc: "sorts elements of an array or a map by `function` result"
    desc_ru: "сортирует элементы массива или объекта по данным в функции `function`"
    example: |-
      use functional
      
      data = [
        {"k1": 2, "k2": "x"},
        {"k1": 7, "k2": "d"},
        {"k1": 4, "k2": "z"},
        {"k1": 5, "k2": "p"},
      ]
      println sortby(data, def(v) = v.k1) // [{k1=2, k2=x}, {k1=4, k2=z}, {k1=5, k2=p}, {k1=7, k2=d}]
      println sortby(data, def(v) = v.k2) // [{k1=7, k2=d}, {k1=5, k2=p}, {k1=2, k2=x}, {k1=4, k2=z}]
  - name: groupby
    args: "data, function"
    desc: "groups elements of an array or a map by `function` result"
    desc_ru: "группирует элементы массива или объекта на основе результата функции `function`"
    since: 2.0.0
    example: |-
      use functional
      
      data = [
        {"k1": 2, "k2": "x"},
        {"k1": 4, "k2": "z"},
        {"k1": 5, "k2": "p"},
      ]
      println groupby(data, def(e) = e.k1) // {"2"=[{k1=2, k2=x}], "4"=[{k1=4, k2=z}], "5"=[{k2=p, k1=5}]}
      println groupby(data, def(e) = e.k2) // {"x"=[{k1=2, k2=x}], "z"=[{k1=4, k2=z}], "p"=[{k2=p, k1=5}]}
  - name: tomap
    args: "data, keyMapper, valueMapper = def(v) = v, merger = def(oldValue, newValue) = newValue"
    desc: "converts elements of an array or a map to a map based on `keyMapper` and `valueMapper` functions result. `merger` function resolves collisions"
    desc_ru: "преобразует элементы массива или объекта в объект, основываясь на результате функций `keyMapper` и `valueMapper`. Функция `merger` используется для разрешения коллизий"
    since: 2.0.0
    example: |-
      use functional
      
      data = ["apple", "banana"]
      println tomap(data, def(str) = str.substring(0, 1)) // {"a": "apple", "b": "banana"}
      println tomap(data, def(str) = str.substring(0, 1), ::toUpperCase) // {"a": "APPLE", "b": "BANANA"}
  - name: stream
    args: data
    desc: creates stream from data and returns `StreamValue`
    desc_ru: создаёт stream из данных и возвращает `StreamValue`
  - name: takewhile
    args: 'data, predicate'
    desc: 'takes elements while predicate function returns true'
    desc_ru: 'собирает элементы пока функция-предикат возвращает true'
types:
  - name: StreamValue
    functions:
      - name: filter
        args: func
        desc: filters elements based on predicate function result (true - remain, false - drop)
        desc_ru: фильтрует элементы на основе результата функции-предиката (true - оставить, false - убрать)
      - name: filterNot
        args: func
        desc: filters elements based on negated predicate function result (false - remain, true - drop)
        desc_ru: фильтрует элементы на основе обратного результата функции-предиката (false - оставить, true - убрать)
        since: 2.0.0
      - name: map
        args: func
        desc: converts each element
        desc_ru: преобразует каждый элемент
      - name: flatMap
        args: func
        desc: converts each element to array
        desc_ru: преобразует каждый элемент в массив
      - name: sorted
        args: func
        desc: sorts elements with comparator function
        desc_ru: сортирует элементы в соответствии с функцией-компаратором
      - name: sortBy
        args: func
        desc: applies function, then sorts elements
        desc_ru: применяет функцию, затем сортирует элементы
      - name: groupBy
        args: func
        desc: groups elements based on function result
        desc_ru: группирует элементы на основе результата выполнения функции
        since: 2.0.0
      - name: takeWhile
        args: func
        desc: takes elements while predicate function returns true
        desc_ru: собирает элементы пока функция-предикат возвращает true
      - name: dropWhile
        args: func
        desc: skips elements while predicate function returns true, returns remaining elements
        desc_ru: пропускает элементы пока функция-предикат возвращает true
      - name: peek
        args: func
        desc: executes function for each element and returns stream
        desc_ru: вызывает функцию для каждого элемента и возвращает stream
      - name: skip
        args: count
        desc: skips `count` elements
        desc_ru: пропускает указанное количество элементов
      - name: limit
        args: count
        desc: limits elements size
        desc_ru: ограничивает количество элементов
      - name: custom
        args: func
        desc: performs custom operation
        desc_ru: выполняет пользовательскую операцию над данными
        example: |-
          use std, functional
          
          println stream([1, 2, 3, 4])
           .custom(::reverse)
           .toArray()
          
          def reverse(container) {
            size = length(container)
            result = newarray(size)
            for i : range(size) {
              result[size - i - 1] = container[i]
            }
            return result
          }
      - name: reduce
        args: func
        desc: converts elements to one value
        desc_ru: преобразует элементы в одно значение
      - name: forEach
        args: func
        desc: executes function for each element
        desc_ru: вызывает функцию для каждого элемента
      - name: forEachIndexed
        args: func
        desc: executes function for each element and its index
        desc_ru: вызывает функцию для каждого элемента и его порядкового номера
        since: 2.0.0
      - name: joining
        args: delimiter = "", prefix = "", suffix = ""
        desc: joins elements into a string
        desc_ru: склеивает элементы в строку
      - name: toArray
        args: ""
        desc: returns array of elements
        desc_ru: возвращает массив элементов
      - name: toMap
        args: "keyMapper, valueMapper = def(v) = v, merger = def(oldValue, newValue) = newValue"
        desc: "converts elements to a map based on `keyMapper` and `valueMapper` functions result. `merger` function resolves collisions"
        desc_ru: "преобразует элементы в объект, основываясь на результате функций `keyMapper` и `valueMapper`. Функция `merger` используется для разрешения коллизий"
        since: 2.0.0
      - name: anyMatch
        args: predicate
        desc: "returns `true` if there is any element matching the given `predicate`, otherwise returns `false`"
        desc_ru: "возвращает `true`, если хотя бы один элемент удовлетворяет функции `predicate`, иначе возвращает `false`"
        since: 2.0.0
      - name: allMatch
        args: predicate
        desc: "returns `true` if all elements match the given `predicate`, otherwise returns `false`"
        desc_ru: "возвращает `true`, если все элементы удовлетворяют функции `predicate`, иначе возвращает `false`"
        since: 2.0.0
      - name: noneMatch
        args: predicate
        desc: "returns `true` if no elements match the given `predicate`, otherwise returns `false`"
        desc_ru: "возвращает `true`, если нет элементов, удовлетворяющих функции `predicate`, иначе возвращает `false`"
        since: 2.0.0
      - name: count
        args: ""
        desc: returns the elements count
        desc_ru: возвращает количество элементов