Package org.daiitech.naftah.builtin

Class Builtin

java.lang.Object
org.daiitech.naftah.builtin.Builtin
public final class Builtin 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 printing. 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
    Builtin()
    Private constructor to prevent instantiation.

  • Method Summary

    Modifier and Type
    Method
    Description
    static <T extends Number>
    Number
    abs(T x)
    The (abs) function is used to calculate the absolute value of the given number, i.e., removing the negative sign if present.
    static <T> Object
    add(T left, T right)
    Adds two values and returns their sum.
    static <T> Object
    and(T left, T right)
    The (and) function performs a bitwise AND operation on the given numbers.
    static <T extends Number>
    Number
    ceil(T x)
    The (ceil) function returns the smallest integer greater than or equal to the given number.
    static <T> Object
    divide(T left, T right)
    Divides the first value by the second and returns the quotient.
    static <T> Object
    elementWiseAdd(T left, T right)
    Performs element-wise addition of two values.
    static <T> Object
    elementWiseDivide(T left, T right)
    Performs element-wise division of two values.
    static <T> Object
    elementWiseModulo(T left, T right)
    Performs element-wise modulo of two values.
    static <T> Object
    elementWiseMultiply(T left, T right)
    Performs element-wise multiplication of two values.
    static <T> Object
    elementWiseSubtract(T left, T right)
    Performs element-wise subtraction of two values.
    static <T> boolean
    equals(T left, T right)
    The (equals) function compares two values to check if they are equal.
    static <T extends Number>
    Number
    floor(T x)
    The (floor) function returns the largest integer less than or equal to the given number.
    static String
    getType(Object obj)
    Returns a string representing the type of the provided object according to the Naftah type system.
    static <T> boolean
    greaterThan(T left, T right)
    The (greaterThan) function checks if the first value is greater than the second.
    static <T> boolean
    greaterThanEquals(T left, T right)
    The (greaterThanEquals) function checks if the first value is greater than or equal to the second.
    static boolean
    instanceOf(Object obj, JavaType javaType)
    Checks whether the given object is an instance of the specified JavaType.
    static <T extends Number>
    boolean
    isZero(T x)
    The (isZero) function checks if the given number is zero.
    static <T> boolean
    lessThan(T left, T right)
    The (lessThan) function checks if the first value is less than the second.
    static <T> boolean
    lessThanEquals(T left, T right)
    The (lessThanEquals) function checks if the first value is less than or equal to the second.
    static <T> Object
    logicalAnd(T left, T right)
    Logical AND operation with short-circuit evaluation.
    static <T> Object
    logicalNot(T x)
    The (logicalNot) function returns the logical negation of the given value.
    static <T> Object
    logicalOr(T left, T right)
    Logical OR operation with short-circuit evaluation.
    static <T extends Number>
    Number
    max(T left, T right)
    The (max) function is used to compare two numbers and return the larger one.
    static <T extends Number>
    Number
    min(T left, T right)
    The (min) function is used to compare two numbers and return the smaller one.
    static <T> Object
    modulo(T left, T right)
    Calculates the remainder of the division of the first value by the second.
    static <T> Object
    multiply(T left, T right)
    Multiplies two values and returns the product.
    static <T extends Number>
    Number
    negate(T x)
    The (negate) function returns the given number after changing it to its negative value.
    static <T> Object
    not(T x)
    The (not) function performs a bitwise NOT operation on the given number.
    static <T> boolean
    notEquals(T left, T right)
    The (notEquals) function compares two values to check if they are not equal.
    static <T> Object
    or(T left, T right)
    The (or) function performs a bitwise OR operation on the given numbers.
    static Number
    parseDynamicNumber(String text, DynamicNumber radix)
    Parses a textual number according to a specified dynamic numeric system (radix) and returns the most appropriate numeric type.
    static <T> Object
    postDecrement(T x)
    The (postDecrement) function decreases the given number by one after using it in the expression.
    static <T> Object
    postIncrement(T x)
    The (postIncrement) function increases the given number by one after using it in the expression.
    static <T> Object
    pow(T left, T right)
    Raises a value to a given power.
    static <T> Object
    preDecrement(T x)
    The (preDecrement) function decreases the given number by one before using it in the expression.
    static <T> Object
    preIncrement(T x)
    The (preIncrement) function increases the given number by one before using it in the expression.
    static void
    print(Object o)
    Prints the string representation of the given object to the output.
    static <T extends Number>
    Number
    round(T x)
    The (round) function is used to round a decimal number to the nearest integer.
    static <T extends Number>
    Number
    shiftLeft(T x, T positions)
    The (shiftLeft) function performs a bitwise left shift on the given number by a specified number of positions.
    static <T extends Number>
    Number
    shiftRight(T x, T positions)
    The (shiftRight) function performs a bitwise right shift on the given number by a specified number of positions.
    static <T extends Number>
    int
    signum(T x)
    The (signum) function is used to determine the sign of the given number: returns -1 if the number is negative, 0 if zero, and 1 if positive.
    static Number
    size(Object obj)
    Computes the size of an object in a generic manner.
    static <T extends Number>
    Number
    sqrt(T x)
    The (sqrt) function is used to calculate the square root of the given number.
    static <T> Object
    subtract(T left, T right)
    Subtracts the second value from the first and returns the difference.
    static String
    toString(Object o)
    Returns the string representation of the given object.
    static <T extends Number>
    Number
    unsignedShiftRight(T x, T positions)
    The (unsignedShiftRight) function performs an unsigned bitwise right shift on the given number by a specified number of positions.
    static <T> Object
    xor(T left, T right)
    The (xor) function performs a bitwise XOR operation on the given numbers.

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • Builtin

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

  • Method Details

    • print

      public static void print(Object o)
      Prints the string representation of the given object to the output. If the object is null, prints a predefined NULL representation.
      Parameters:
      o - the object to print; can be any object

    • toString

      public static String toString(Object o)
      Returns the string representation of the given object. If the object is null, returns a predefined NULL string.
      Parameters:
      o - the object to convert to string
      Returns:
      a string representation of the object, or a NULL representation if the object is null

    • add

      public static <T> Object add(T left, T right)
      Adds two values and returns their sum.
      Type Parameters:
      T - the type of the operands
      Parameters:
      left - the first value
      right - the second value
      Returns:
      the sum of left and right

    • logicalAnd

      public static <T> Object logicalAnd(T left, T right)
      Logical AND operation with short-circuit evaluation.

      Returns the second operand if the first operand is "truthy"; otherwise returns the first operand.

      Supports numbers, booleans, characters, and strings. Uses custom "truthy" rules via isTruthy() to determine truthiness:

      • Numbers: non-zero values are truthy.
      • Booleans: true is truthy, false is falsy.
      • Characters: non-null, non-zero characters are truthy.
      • Strings: non-empty strings are truthy.
      Type Parameters:
      T - the type of operands (Number, Boolean, Character, String)
      Parameters:
      left - the first value
      right - the second value
      Returns:
      the second operand if the first is truthy, otherwise the first operand

    • logicalOr

      public static <T> Object logicalOr(T left, T right)
      Logical OR operation with short-circuit evaluation.

      Returns the first operand if it is "truthy"; otherwise returns the second operand.

      Supports numbers, booleans, characters, and strings. Uses custom "truthy" rules via isTruthy() to determine truthiness:

      • Numbers: non-zero values are truthy.
      • Booleans: true is truthy, false is falsy.
      • Characters: non-null, non-zero characters are truthy.
      • Strings: non-empty strings are truthy.
      Type Parameters:
      T - the type of operands (Number, Boolean, Character, String)
      Parameters:
      left - the first value
      right - the second value
      Returns:
      the first "truthy" operand, or the second operand if the first is falsy

    • subtract

      public static <T> Object subtract(T left, T right)
      Subtracts the second value from the first and returns the difference.
      Type Parameters:
      T - the type of the operands
      Parameters:
      left - the minuend
      right - the subtrahend
      Returns:
      the difference between left and right

    • multiply

      public static <T> Object multiply(T left, T right)
      Multiplies two values and returns the product.
      Type Parameters:
      T - the type of the operands
      Parameters:
      left - the first factor
      right - the second factor
      Returns:
      the product of left and right

    • pow

      public static <T> Object pow(T left, T right)
      Raises a value to a given power.

      Computes the result of raising the first operand (base) to the second operand (exponent). Supports numbers and compatible numeric types.

      Type Parameters:
      T - the type of the operands
      Parameters:
      left - the base value
      right - the exponent value
      Returns:
      the result of left raised to the power of right

    • divide

      public static <T> Object divide(T left, T right)
      Divides the first value by the second and returns the quotient.
      Type Parameters:
      T - the type of the operands
      Parameters:
      left - the dividend
      right - the divisor
      Returns:
      the quotient of left divided by right

    • modulo

      public static <T> Object modulo(T left, T right)
      Calculates the remainder of the division of the first value by the second.
      Type Parameters:
      T - the type of the operands
      Parameters:
      left - the dividend
      right - the divisor
      Returns:
      the remainder after dividing left by right

    • max

      public static <T extends Number> Number max(T left, T right)
      The (max) function is used to compare two numbers and return the larger one. This operation is useful for determining the higher value when comparing two numeric values.
      Type Parameters:
      T - The type of number, must be Number or a subclass
      Parameters:
      left - The first number to compare
      right - The second number to compare
      Returns:
      The larger number between left and right

    • min

      public static <T extends Number> Number min(T left, T right)
      The (min) function is used to compare two numbers and return the smaller one. This operation is useful for determining the lower value when comparing two numeric values.
      Type Parameters:
      T - The type of number, must be Number or a subclass
      Parameters:
      left - The first number to compare
      right - The second number to compare
      Returns:
      The smaller number between left and right

    • pow

      public static <T extends Number> Number pow(T base, T exponent)
      The (pow) function is used to raise a base number to an integer exponent. This operation is useful in mathematical calculations requiring exponential repetition such as squares or cubes.
      Type Parameters:
      T - The type of the base, must be Number or a subclass
      Parameters:
      base - The base number to be raised
      exponent - The power to which the base is raised (integer)
      Returns:
      The result of raising the base to the specified power

    • round

      public static <T extends Number> Number round(T x)
      The (round) function is used to round a decimal number to the nearest integer. This operation is useful in calculations requiring precise integers.
      Type Parameters:
      T - The type of decimal number, must be Number or a subclass
      Parameters:
      x - The decimal number to round
      Returns:
      The number rounded to the nearest integer

    • floor

      public static <T extends Number> Number floor(T x)
      The (floor) function returns the largest integer less than or equal to the given number. This operation is useful in calculations that require rounding down numbers.
      Type Parameters:
      T - The type of number, must be Number or a subclass
      Parameters:
      x - The number to floor
      Returns:
      The largest integer less than or equal to the given number

    • ceil

      public static <T extends Number> Number ceil(T x)
      The (ceil) function returns the smallest integer greater than or equal to the given number. This operation is useful in calculations that require rounding up numbers.
      Type Parameters:
      T - The type of number, must be Number or a subclass
      Parameters:
      x - The number to ceil
      Returns:
      The smallest integer greater than or equal to the given number

    • negate

      public static <T extends Number> Number negate(T x)
      The (negate) function returns the given number after changing it to its negative value. This operation is useful in calculations that require reversing the numeric sign.
      Type Parameters:
      T - The type of number, must be Number or a subclass
      Parameters:
      x - The number to negate
      Returns:
      The given number after changing it to its negative value

    • sqrt

      public static <T extends Number> Number sqrt(T x)
      The (sqrt) function is used to calculate the square root of the given number. This operation is useful in calculations that require finding a number whose square equals the original number.
      Type Parameters:
      T - The type of number, must be Number or a subclass
      Parameters:
      x - The number to calculate the square root of
      Returns:
      The square root of the given number

    • abs

      public static <T extends Number> Number abs(T x)
      The (abs) function is used to calculate the absolute value of the given number, i.e., removing the negative sign if present. This operation is useful in calculations that require a positive value always.
      Type Parameters:
      T - The type of number, must be Number or a subclass
      Parameters:
      x - The number to calculate the absolute value for
      Returns:
      The absolute value of the given number

    • signum

      public static <T extends Number> int signum(T x)
      The (signum) function is used to determine the sign of the given number: returns -1 if the number is negative, 0 if zero, and 1 if positive.
      Type Parameters:
      T - The type of number, must be Number or a subclass
      Parameters:
      x - The number to determine its sign
      Returns:
      -1 if negative, 0 if zero, 1 if positive

    • isZero

      public static <T extends Number> boolean isZero(T x)
      The (isZero) function checks if the given number is zero. Returns true if the number is zero, false otherwise.
      Type Parameters:
      T - The type of number, must be Number or subclass
      Parameters:
      x - The number to check
      Returns:
      true if x is zero, false otherwise

    • equals

      public static <T> boolean equals(T left, T right)
      The (equals) function compares two values to check if they are equal. Returns true if both are equal, false otherwise.
      Type Parameters:
      T - The type of the objects being compared
      Parameters:
      left - The first object
      right - The second object
      Returns:
      true if left equals right, false otherwise

    • notEquals

      public static <T> boolean notEquals(T left, T right)
      The (notEquals) function compares two values to check if they are not equal. Returns true if they are different, false otherwise.
      Type Parameters:
      T - The type of the objects being compared
      Parameters:
      left - The first object
      right - The second object
      Returns:
      true if left does not equal right, false otherwise

    • lessThan

      public static <T> boolean lessThan(T left, T right)
      The (lessThan) function checks if the first value is less than the second. Returns true if left is less than right, false otherwise.
      Type Parameters:
      T - The type of the objects being compared
      Parameters:
      left - The first object
      right - The second object
      Returns:
      true if left < right, false otherwise

    • lessThanEquals

      public static <T> boolean lessThanEquals(T left, T right)
      The (lessThanEquals) function checks if the first value is less than or equal to the second. Returns true if left ≤ right, false otherwise.
      Type Parameters:
      T - The type of the objects being compared
      Parameters:
      left - The first object
      right - The second object
      Returns:
      true if left ≤ right, false otherwise

    • greaterThan

      public static <T> boolean greaterThan(T left, T right)
      The (greaterThan) function checks if the first value is greater than the second. Returns true if left > right, false otherwise.
      Type Parameters:
      T - The type of the objects being compared
      Parameters:
      left - The first object
      right - The second object
      Returns:
      true if left > right, false otherwise

    • greaterThanEquals

      public static <T> boolean greaterThanEquals(T left, T right)
      The (greaterThanEquals) function checks if the first value is greater than or equal to the second. Returns true if left ≥ right, false otherwise.
      Type Parameters:
      T - The type of the objects being compared
      Parameters:
      left - The first object
      right - The second object
      Returns:
      true if left ≥ right, false otherwise

    • and

      public static <T> Object and(T left, T right)
      The (and) function performs a bitwise AND operation on the given numbers. Returns the result of the bitwise AND between the two numbers.
      Type Parameters:
      T - The type of the objects being operated on
      Parameters:
      left - The first number
      right - The second number
      Returns:
      The result of bitwise AND operation

    • or

      public static <T> Object or(T left, T right)
      The (or) function performs a bitwise OR operation on the given numbers. Returns the result of the bitwise OR between the two numbers.
      Type Parameters:
      T - The type of the objects being operated on
      Parameters:
      left - The first number
      right - The second number
      Returns:
      The result of bitwise OR operation

    • xor

      public static <T> Object xor(T left, T right)
      The (xor) function performs a bitwise XOR operation on the given numbers. Returns the result of the bitwise exclusive OR between the two numbers.
      Type Parameters:
      T - The type of the objects being operated on
      Parameters:
      left - The first number
      right - The second number
      Returns:
      The result of bitwise XOR operation

    • elementWiseAdd

      public static <T> Object elementWiseAdd(T left, T right)
      Performs element-wise addition of two values.

      Applies addition to each element individually for numbers, strings, simple values, arrays, and compatible collections.

      Type Parameters:
      T - the type of operands
      Parameters:
      left - the first value
      right - the second value
      Returns:
      the element-wise sum of left and right

    • elementWiseSubtract

      public static <T> Object elementWiseSubtract(T left, T right)
      Performs element-wise subtraction of two values.
      Type Parameters:
      T - the type of operands
      Parameters:
      left - the first value
      right - the second value
      Returns:
      the element-wise difference of left and right

    • elementWiseMultiply

      public static <T> Object elementWiseMultiply(T left, T right)
      Performs element-wise multiplication of two values.
      Type Parameters:
      T - the type of operands
      Parameters:
      left - the first value
      right - the second value
      Returns:
      the element-wise product of left and right

    • elementWiseDivide

      public static <T> Object elementWiseDivide(T left, T right)
      Performs element-wise division of two values.
      Type Parameters:
      T - the type of operands
      Parameters:
      left - the first value
      right - the second value
      Returns:
      the element-wise quotient of left and right

    • elementWiseModulo

      public static <T> Object elementWiseModulo(T left, T right)
      Performs element-wise modulo of two values.
      Type Parameters:
      T - the type of operands
      Parameters:
      left - the first value
      right - the second value
      Returns:
      the element-wise remainder of left divided by right

    • not

      public static <T> Object not(T x)
      The (not) function performs a bitwise NOT operation on the given number. Returns the result of flipping all bits in the number.
      Type Parameters:
      T - The type of the object being operated on
      Parameters:
      x - The number to negate
      Returns:
      The bitwise NOT of the number

    • shiftLeft

      public static <T extends Number> Number shiftLeft(T x, T positions)
      The (shiftLeft) function performs a bitwise left shift on the given number by a specified number of positions. Used in binary calculations to increase the value.
      Type Parameters:
      T - The type of the number
      Parameters:
      x - The number to shift
      positions - The number of positions to shift left
      Returns:
      The shifted number

    • shiftRight

      public static <T extends Number> Number shiftRight(T x, T positions)
      The (shiftRight) function performs a bitwise right shift on the given number by a specified number of positions. Used in binary calculations to decrease the value.
      Type Parameters:
      T - The type of the number
      Parameters:
      x - The number to shift
      positions - The number of positions to shift right
      Returns:
      The shifted number

    • unsignedShiftRight

      public static <T extends Number> Number unsignedShiftRight(T x, T positions)
      The (unsignedShiftRight) function performs an unsigned bitwise right shift on the given number by a specified number of positions. The sign bit is ignored. Used to handle numbers without sign extension.
      Type Parameters:
      T - The type of the number
      Parameters:
      x - The number to shift
      positions - The number of positions to shift right
      Returns:
      The shifted number

    • preIncrement

      public static <T> Object preIncrement(T x)
      The (preIncrement) function increases the given number by one before using it in the expression.
      Type Parameters:
      T - The type of the object to increment
      Parameters:
      x - The object to increment
      Returns:
      The incremented value before use

    • postIncrement

      public static <T> Object postIncrement(T x)
      The (postIncrement) function increases the given number by one after using it in the expression.
      Type Parameters:
      T - The type of the object to increment
      Parameters:
      x - The object to increment
      Returns:
      The original value before incrementing

    • preDecrement

      public static <T> Object preDecrement(T x)
      The (preDecrement) function decreases the given number by one before using it in the expression.
      Type Parameters:
      T - The type of the object to decrement
      Parameters:
      x - The object to decrement
      Returns:
      The decremented value before use

    • postDecrement

      public static <T> Object postDecrement(T x)
      The (postDecrement) function decreases the given number by one after using it in the expression.
      Type Parameters:
      T - The type of the object to decrement
      Parameters:
      x - The object to decrement
      Returns:
      The original value before decrementing

    • negate

      public static <T> Object negate(T x)
      The (negate) function returns the arithmetic negation of the given value.

      It inverts the numeric sign of the value. For example: 

      
 negate(5)  → -5
 negate(-2) → 2
      Type Parameters:
      T - The type of the object to negate
      Parameters:
      x - The object whose sign should be inverted
      Returns:
      The negated value

    • logicalNot

      public static <T> Object logicalNot(T x)
      The (logicalNot) function returns the logical negation of the given value.

      It inverts a boolean value. For example: 

      
 logicalNot(true)  → false
 logicalNot(false) → true
      Type Parameters:
      T - The type of the object to logically negate
      Parameters:
      x - The object to negate
      Returns:
      The logical negation of the given value

    • parseDynamicNumber

      public static Number parseDynamicNumber(String text, DynamicNumber radix)
      Parses a textual number according to a specified dynamic numeric system (radix) and returns the most appropriate numeric type.

      This method handles numeric strings containing Arabic digits and converts them to Ascii digits before parsing. The returned Number type depends on the input value and the specified radix.

      Example usage:

      
 DynamicNumber radix = DynamicNumber.DECIMAL;
 Number n = parseDynamicNumber("١٢٣", radix); // returns 123 as Integer
      Parameters:
      text - the textual representation of the number; may contain Arabic digits
      radix - the dynamic numeric system used for parsing (e.g., decimal, hexadecimal)
      Returns:
      the parsed Number, type determined dynamically (Integer, Long, Double, etc.)
      Throws:
      NullPointerException - if text or radix is null
      NumberFormatException - if the text cannot be parsed as a valid number in the given radix

    • size

      public static Number size(Object obj)
      Computes the size of an object in a generic manner.

      The meaning of "size" depends on the object type:

      • Array: length of the array
      • Collection (List, Set): number of elements
      • Map: number of entries
      • String: length of the string
      • Number or Boolean: 1
      • Other Objects: number of non-static fields

      Example usage:

      
 List<String> list = List.of("a", "b", "c");
 Number size = size(list); // returns 3

 int[] arr = {1, 2, 3, 4};
 Number arrSize = size(arr); // returns 4
      Parameters:
      obj - the object whose size is to be determined; may be null
      Returns:
      the size as a Number; 0 for null objects

    • getType

      public static String getType(Object obj)
      Returns a string representing the type of the provided object according to the Naftah type system.

      This method internally uses JavaType to capture both raw and generic type information, providing a human-readable description of the type. Useful for dynamic type inspection and error reporting.

      Example usage:

      
 String typeStr = getType(List.of("a", "b")); // "java.util.List<java.lang.String>"
      Parameters:
      obj - the object to inspect; may be null
      Returns:
      a string describing the object's type; "null" if the object is null

    • instanceOf

      public static boolean instanceOf(Object obj, JavaType javaType)
      Checks whether the given object is an instance of the specified JavaType.

      This method performs type checking similar to the Java instanceof operator, but also compares generic type parameters if available. It ensures that the object's raw type is assignable from the target type and that generic parameters match exactly.

      Example usage:

      
 JavaType pairType = JavaType.of(new TypeReference<Pair<String, Integer>>() {});
 Pair<String, Integer> pair = new Pair<>("hello", 42);
 boolean result = instanceOf(pair, pairType); // true
      Parameters:
      obj - the object to check; may be null
      javaType - the target JavaType to check against; may be null
      Returns:
      true if obj is an instance of javaType (including generic parameters), false otherwise