Package org.daiitech.naftah.builtin.functions

Class CollectionBuiltinFunctions

java.lang.Object
org.daiitech.naftah.builtin.functions.CollectionBuiltinFunctions
public final class CollectionBuiltinFunctions extends Object
Provides built-in functions used within the Naftah language for performing various arithmetic and logical operations with precision and efficiency.

This class contains static methods that implement fundamental operations such as addition, subtraction, multiplication, division, logical comparisons, bitwise operations, and element-wise collection operations. All functions are annotated to be recognized by the Naftah interpreter.

Note: This class cannot be instantiated.

Author:
Chakib Daii

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    private
    CollectionBuiltinFunctions()
    Private constructor to prevent instantiation.

  • Method Summary

    Modifier and Type
    Method
    Description
    static <T> Object
    add(T left, T right)
    Adds two values element by element of collection, map with themselves or with simple value.
    static boolean
    addElement(Object x, Object element)
    Adds an element to a collection or a map.
    static <T> Object
    and(T left, T right)
    Performs bitwise AND operation element by element of collection, map with themselves or with simple value.
    private static <T> void
    checkParam(T x)
    Checks if the parameter is a tuple, collection, map, or array.
    private static <T> void
    checkParams(T left, T right)
    Checks if at least one of the two parameters is a tuple, collection, map, or array.
    static void
    clearCollection(Object x)
    Clears all elements from a collection, map, or array.
    static <T> boolean
    containsElement(T x, Object element)
    Checks if a tuple, collection, map, or array contains a specific element.
    static <K, V> boolean
    containsKey(Map<K,V> map, K key)
    Checks if a map contains a specific key.
    static <T> Object
    divide(T left, T right)
    Divides the first value by the second value element by element of collection, map with themselves or with simple value.
    static <T> Object
    elementWiseAdd(T left, T right)
    Performs element-wise addition element by element of collection, map with themselves or with simple value.
    static <T> Object
    elementWiseDivide(T left, T right)
    Performs element-wise division element by element of collection, map with themselves or with simple value.
    static <T> Object
    elementWiseModulo(T left, T right)
    Performs element-wise modulo element by element of collection, map with themselves or with simple value.
    static <T> Object
    elementWiseMultiply(T left, T right)
    Performs element-wise multiplication element by element of collection, map with themselves or with simple value.
    static <T> Object
    elementWiseSubtract(T left, T right)
    Performs element-wise subtraction element by element of collection, map with themselves or with simple value.
    static <T> Object
    equals(T left, T right)
    Checks if two values are equal element by element of collection, map with themselves or with simple value.
    static <I extends Number, T>
    Object
    getElementAt(Collection<T> collection, I targetIndex)
    Gets an element from a collection by index.
    static <T> Object
    greaterThan(T left, T right)
    Checks if the first value is greater than the second element by element of collection, map with themselves or with simple value.
    static <T> Object
    greaterThanEquals(T left, T right)
    Checks if the first value is greater than or equal to the second element by element of collection, map with themselves or with simple value.
    static <T> Object
    lessThan(T left, T right)
    Checks if the first value is less than the second element by element of collection, map with themselves or with simple value.
    static <T> Object
    lessThanEquals(T left, T right)
    Checks if the first value is less than or equal to the second element by element of collection, map with themselves or with simple value.
    static <T> Object
    logicalAnd(T left, T right)
    Performs logical AND element by element of collection, map with themselves or with simple value.
    static <T> Object
    logicalNot(T x)
    Performs logical NOT on a collection or map.
    static <T> Object
    logicalOr(T left, T right)
    Performs logical OR element by element of collection, map with themselves or with simple value.
    static <T> Object
    modulo(T left, T right)
    Computes the modulo (remainder) of the first value divided by the second element by element of collection, map with themselves or with simple value.
    static <T> Object
    multiply(T left, T right)
    Multiplies two values element by element of collection, map with themselves or with simple value.
    static <T> Object
    negate(T x)
    Negates a collection or map.
    static NaftahBugError
    newNaftahNotCollectionOrMapArgumentError(boolean singleArgument)
    Creates a NaftahBugError indicating that one or more arguments are not valid collection, array, or map types.
    static <T> Object
    not(T x)
    Performs bitwise NOT element by element of collection, map with themselves or with simple value.
    static <T> Object
    notEquals(T left, T right)
    Checks if two values are not equal element by element of collection, map with themselves or with simple value.
    static <T> Object
    or(T left, T right)
    Performs bitwise OR operation element by element of collection, map with themselves or with simple value.
    static <T> Object
    postDecrement(T x)
    Performs post-decrement element by element of collection, map with themselves or with simple value.
    static <T> Object
    postIncrement(T x)
    Performs post-increment element by element of collection, map with themselves or with simple value.
    static <T> Object
    pow(T left, T right)
    Raises the first value to the power of the second value element by element of collection, map with themselves or with simple value.
    static <T> Object
    preDecrement(T x)
    Performs pre-decrement element by element of collection, map with themselves or with simple value.
    static <T> Object
    preIncrement(T x)
    Performs pre-increment element by element of collection, map with themselves or with simple value.
    static boolean
    removeElement(Object x, Object element)
    Removes an element from a collection or a map.
    static <I extends Number, T>
    Object
    removeElementAt(Collection<T> collection, I targetIndex)
    Removes an element from a collection at a given index.
    static <T> boolean
    retainElements(Collection<T> collection, Collection<T> otherCollection)
    Retains only the elements in a collection that are contained in another collection.
    static <I extends Number, T>
    void
    setElementAt(Collection<T> collection, I targetIndex, T newValue)
    Sets an element in a collection at a given index.
    static <T> Object
    subtract(T left, T right)
    Subtracts the second value from the first element by element of collection, map with themselves or with simple value.
    static <T> Object
    xor(T left, T right)
    Performs bitwise XOR operation element by element of collection, map with themselves or with simple value.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • CollectionBuiltinFunctions

      private CollectionBuiltinFunctions()
      Private constructor to prevent instantiation. Throws NaftahBugError if called.

  • Method Details

    • add

      public static <T> Object add(T left, T right)
      Adds two values element by element of collection, map with themselves or with simple value.
      Type Parameters:
      T - type of operands
      Parameters:
      left - first operand
      right - second operand
      Returns:
      collection element-wise sum

    • logicalAnd

      public static <T> Object logicalAnd(T left, T right)
      Performs logical AND element by element of collection, map with themselves or with simple value.
      Type Parameters:
      T - type of operands
      Parameters:
      left - first operand
      right - second operand
      Returns:
      collection logical AND results

    • logicalOr

      public static <T> Object logicalOr(T left, T right)
      Performs logical OR element by element of collection, map with themselves or with simple value.
      Type Parameters:
      T - type of operands
      Parameters:
      left - first operand
      right - second operand
      Returns:
      collection of logical OR results

    • subtract

      public static <T> Object subtract(T left, T right)
      Subtracts the second value from the first element by element of collection, map with themselves or with simple value.
      Type Parameters:
      T - type of operands
      Parameters:
      left - first operand
      right - second operand
      Returns:
      subtraction result

    • multiply

      public static <T> Object multiply(T left, T right)
      Multiplies two values element by element of collection, map with themselves or with simple value.
      Type Parameters:
      T - type of operands
      Parameters:
      left - first operand
      right - second operand
      Returns:
      multiplication result

    • pow

      public static <T> Object pow(T left, T right)
      Raises the first value to the power of the second value element by element of collection, map with themselves or with simple value.
      Type Parameters:
      T - type of operands
      Parameters:
      left - base
      right - exponent
      Returns:
      result of exponentiation

    • divide

      public static <T> Object divide(T left, T right)
      Divides the first value by the second value element by element of collection, map with themselves or with simple value.
      Type Parameters:
      T - type of operands
      Parameters:
      left - numerator
      right - denominator
      Returns:
      division result

    • modulo

      public static <T> Object modulo(T left, T right)
      Computes the modulo (remainder) of the first value divided by the second element by element of collection, map with themselves or with simple value.
      Type Parameters:
      T - type of operands
      Parameters:
      left - dividend
      right - divisor
      Returns:
      remainder after division

    • equals

      public static <T> Object equals(T left, T right)
      Checks if two values are equal element by element of collection, map with themselves or with simple value.
      Type Parameters:
      T - type of operands
      Parameters:
      left - first value
      right - second value
      Returns:
      collection of booleans

    • notEquals

      public static <T> Object notEquals(T left, T right)
      Checks if two values are not equal element by element of collection, map with themselves or with simple value.
      Type Parameters:
      T - type of operands
      Parameters:
      left - first value
      right - second value
      Returns:
      collection of booleans

    • lessThan

      public static <T> Object lessThan(T left, T right)
      Checks if the first value is less than the second element by element of collection, map with themselves or with simple value.
      Type Parameters:
      T - type of operands
      Parameters:
      left - first value
      right - second value
      Returns:
      collection of booleans

    • lessThanEquals

      public static <T> Object lessThanEquals(T left, T right)
      Checks if the first value is less than or equal to the second element by element of collection, map with themselves or with simple value.
      Type Parameters:
      T - type of operands
      Parameters:
      left - first value
      right - second value
      Returns:
      collection of booleans

    • greaterThan

      public static <T> Object greaterThan(T left, T right)
      Checks if the first value is greater than the second element by element of collection, map with themselves or with simple value.
      Type Parameters:
      T - type of operands
      Parameters:
      left - first value
      right - second value
      Returns:
      collection of booleans

    • greaterThanEquals

      public static <T> Object greaterThanEquals(T left, T right)
      Checks if the first value is greater than or equal to the second element by element of collection, map with themselves or with simple value.
      Type Parameters:
      T - type of operands
      Parameters:
      left - first value
      right - second value
      Returns:
      collection of booleans

    • and

      public static <T> Object and(T left, T right)
      Performs bitwise AND operation element by element of collection, map with themselves or with simple value.
      Type Parameters:
      T - type of operands
      Parameters:
      left - first value
      right - second value
      Returns:
      result of bitwise AND

    • or

      public static <T> Object or(T left, T right)
      Performs bitwise OR operation element by element of collection, map with themselves or with simple value.
      Type Parameters:
      T - type of operands
      Parameters:
      left - first value
      right - second value
      Returns:
      result of bitwise OR

    • xor

      public static <T> Object xor(T left, T right)
      Performs bitwise XOR operation element by element of collection, map with themselves or with simple value.
      Type Parameters:
      T - type of operands
      Parameters:
      left - first value
      right - second value
      Returns:
      result of bitwise XOR

    • elementWiseAdd

      public static <T> Object elementWiseAdd(T left, T right)
      Performs element-wise addition element by element of collection, map with themselves or with simple value.
      Type Parameters:
      T - type of operands
      Parameters:
      left - first collection or value
      right - second collection or value
      Returns:
      element-wise addition result

    • elementWiseSubtract

      public static <T> Object elementWiseSubtract(T left, T right)
      Performs element-wise subtraction element by element of collection, map with themselves or with simple value.
      Type Parameters:
      T - type of operands
      Parameters:
      left - first collection or value
      right - second collection or value
      Returns:
      element-wise subtraction result

    • elementWiseMultiply

      public static <T> Object elementWiseMultiply(T left, T right)
      Performs element-wise multiplication element by element of collection, map with themselves or with simple value.
      Type Parameters:
      T - type of operands
      Parameters:
      left - first collection or value
      right - second collection or value
      Returns:
      element-wise multiplication result

    • elementWiseDivide

      public static <T> Object elementWiseDivide(T left, T right)
      Performs element-wise division element by element of collection, map with themselves or with simple value.
      Type Parameters:
      T - type of operands
      Parameters:
      left - first collection or value
      right - second collection or value
      Returns:
      element-wise division result

    • elementWiseModulo

      public static <T> Object elementWiseModulo(T left, T right)
      Performs element-wise modulo element by element of collection, map with themselves or with simple value.
      Type Parameters:
      T - type of operands
      Parameters:
      left - first collection or value
      right - second collection or value
      Returns:
      element-wise modulo result

    • not

      public static <T> Object not(T x)
      Performs bitwise NOT element by element of collection, map with themselves or with simple value.
      Type Parameters:
      T - type of operand
      Parameters:
      x - collection or value
      Returns:
      result after applying bitwise NOT

    • preIncrement

      public static <T> Object preIncrement(T x)
      Performs pre-increment element by element of collection, map with themselves or with simple value.
      Type Parameters:
      T - type of operand
      Parameters:
      x - collection or value
      Returns:
      result after pre-increment

    • postIncrement

      public static <T> Object postIncrement(T x)
      Performs post-increment element by element of collection, map with themselves or with simple value.
      Type Parameters:
      T - type of operand
      Parameters:
      x - collection or value
      Returns:
      result after post-increment

    • preDecrement

      public static <T> Object preDecrement(T x)
      Performs pre-decrement element by element of collection, map with themselves or with simple value.
      Type Parameters:
      T - type of operand
      Parameters:
      x - collection or value
      Returns:
      result after pre-decrement

    • postDecrement

      public static <T> Object postDecrement(T x)
      Performs post-decrement element by element of collection, map with themselves or with simple value.
      Type Parameters:
      T - type of operand
      Parameters:
      x - collection or value
      Returns:
      result after post-decrement

    • negate

      public static <T> Object negate(T x)
      Negates a collection or map.
      Type Parameters:
      T - type of operand
      Parameters:
      x - collection or value
      Returns:
      result after negation

    • logicalNot

      public static <T> Object logicalNot(T x)
      Performs logical NOT on a collection or map.
      Type Parameters:
      T - type of operand
      Parameters:
      x - collection or value
      Returns:
      result after logical NOT

    • getElementAt

      public static <I extends Number, T> Object getElementAt(Collection<T> collection, I targetIndex)
      Gets an element from a collection by index.
      Parameters:
      collection - the collection to get from
      targetIndex - index of the element
      Returns:
      the element at the given index

    • setElementAt

      public static <I extends Number, T> void setElementAt(Collection<T> collection, I targetIndex, T newValue)
      Sets an element in a collection at a given index.
      Type Parameters:
      T - type of element
      I - type of index
      Parameters:
      collection - the collection to modify
      targetIndex - index to set
      newValue - new value to assign

    • removeElementAt

      public static <I extends Number, T> Object removeElementAt(Collection<T> collection, I targetIndex)
      Removes an element from a collection at a given index.
      Type Parameters:
      T - type of element
      I - type of index
      Parameters:
      collection - the collection to modify
      targetIndex - index of the element to remove

    • containsElement

      public static <T> boolean containsElement(T x, Object element)
      Checks if a tuple, collection, map, or array contains a specific element.
      Type Parameters:
      T - type of collection/map/array
      Parameters:
      x - collection, map, or array to check
      element - element to look for
      Returns:
      true if the element is found, false otherwise

    • containsKey

      public static <K, V> boolean containsKey(Map<K,V> map, K key)
      Checks if a map contains a specific key.
      Type Parameters:
      K - type of the key
      V - type of the value
      Parameters:
      map - the map to check
      key - the key to look for
      Returns:
      true if the map contains the key, false otherwise

    • addElement

      public static boolean addElement(Object x, Object element)
      Adds an element to a collection or a map.
      Parameters:
      x - collection or map to modify
      element - element to add
      Returns:
      true if the collection/map was modified

    • removeElement

      public static boolean removeElement(Object x, Object element)
      Removes an element from a collection or a map.
      Parameters:
      x - collection or map to modify
      element - element to remove
      Returns:
      true if the collection/map was modified

    • retainElements

      public static <T> boolean retainElements(Collection<T> collection, Collection<T> otherCollection)
      Retains only the elements in a collection that are contained in another collection.
      Parameters:
      collection - the collection to modify
      otherCollection - collection with elements to retain
      Returns:
      true if the collection was modified

    • clearCollection

      public static void clearCollection(Object x)
      Clears all elements from a collection, map, or array.
      Parameters:
      x - the collection, map, or array to clear

    • checkParams

      private static <T> void checkParams(T left, T right)
      Checks if at least one of the two parameters is a tuple, collection, map, or array. Throws a NaftahBugError with an Arabic message if the check fails.
      Type Parameters:
      T - type of operands
      Parameters:
      left - first value to check
      right - second value to check
      Throws:
      NaftahBugError - if neither left nor right is a collection, map, or array

    • checkParam

      private static <T> void checkParam(T x)
      Checks if the parameter is a tuple, collection, map, or array. Throws a NaftahBugError with an Arabic message if the check fails.
      Type Parameters:
      T - type of operand
      Parameters:
      x - value to check
      Throws:
      NaftahBugError - if x is not a collection, map, or array

    • newNaftahNotCollectionOrMapArgumentError

      public static NaftahBugError newNaftahNotCollectionOrMapArgumentError(boolean singleArgument)
      Creates a NaftahBugError indicating that one or more arguments are not valid collection, array, or map types.

      If singleArgument is true, the error message specifies that a single argument must be a collection, array, or associative array (map). Otherwise, the message specifies that at least one of the two arguments must be of those types.

      Arabic message:

      • For a single argument: "يجب أن يكون المعامل مصفوفة أو مجموعة أو مصفوفة ترابطية."
      • For multiple arguments: "يجب أن يكون على الأقل أحد المعاملين مصفوفة أو مجموعة أو مصفوفة ترابطية ."
      Parameters:
      singleArgument - true if the error refers to a single argument; false if it refers to multiple arguments
      Returns:
      a NaftahBugError with the appropriate descriptive message