Skip to content

Overview

tags: - native-functions - built-in-functions - reference

tags: - native-functions - built-in-functions - reference# Native Functions

EverSharp provides over 100 built-in native functions for common operations. Functions are organized into categories based on their purpose.

Function Categories

Category Count Description
Mathematics 5 Arithmetic and mathematical operations
Date & Time 24 Date/time creation, manipulation, and calculations
Strings 15+ String manipulation and text operations
Arrays 40+ Array creation, transformation, and manipulation
Conversions 10 Type conversion functions
Utilities 10+ Logging, dynamic access, and helper functions

Mathematics

Arithmetic and mathematical operations.

Function Description
$Max(a, b) Returns the larger of two numbers
$Min(a, b) Returns the smaller of two numbers
$Abs(value) Returns the absolute value
$Round(value, decimals) Rounds to specified decimal places
$Sum(array) Sums all values in an array

Example:

max = $Max(10, 20); // 20
min = $Min(10, 20); // 10
abs = $Abs(-15); // 15
rounded = $Round(3.14159, 2); // 3.14
sum = $Sum([1, 2, 3, 4, 5]); // 15

→ See all mathematics functions

Date & Time

Date and time creation, manipulation, and calculations.

Function Description
$Now() Current UTC date and time
$Today() Current date (midnight)
$ToDate(string) Parse string to DateTime
$AddDays(date, days) Add days to date
$DifferenceInDays(date1, date2) Days between dates
$Year(date) Extract year component
$Month(date) Extract month component
$Day(date) Extract day component

Example:

now = $Now();
today = $Today();
futureDate = $AddDays(today, 30);
daysDiff = $DifferenceInDays(futureDate, today); // 30
year = $Year(now);

→ See all date/time functions

Strings

String manipulation and text operations. Most are instance methods.

Function Description
.ToUpper() Convert to uppercase
.ToLower() Convert to lowercase
.Trim() Remove leading/trailing whitespace
.Split(separator) Split into array
.Substring(start) Extract from index to end
.Substring(start, len) Extract substring of length
.Contains(substring) Check if contains substring
.Replace(old, new) Replace occurrences
$ToString(value) Convert to string

Example:

text = "  Hello World  ";
upper = text.ToUpper(); // "  HELLO WORLD  "
trimmed = text.Trim(); // "Hello World"
parts = trimmed.Split(" "); // ["Hello", "World"]
sub = trimmed.Substring(0, 5); // "Hello"
hasHello = text.Contains("Hello"); // true

→ See all string functions

Arrays

Array creation, transformation, filtering, and manipulation. Most are instance methods.

Function Description
$Array(...) Create array from values
.Filter(predicate) Filter elements
.Map(transform) Transform elements
.ReduceToNum(fn, init) Reduce to number
.OrderBy(selector) Sort ascending
.Find(predicate) Find first match
.Any(predicate) Check if any match
.Push(value) Add element to end
.Length Number of elements

Example:

numbers = [1, 2, 3, 4, 5];
evens = numbers.Filter((x) => x % 2 == 0); // [2, 4]
doubled = numbers.Map((x) => x * 2); // [2, 4, 6, 8, 10]
sum = numbers.ReduceToNum((a, x) => a + x, 0); // 15
sorted = [5, 2, 8, 1].OrderBy((x) => x); // [1, 2, 5, 8]

→ See all array functions

Conversions

Type conversion functions.

Function Description
$ToNumber(value) Convert to decimal
$ToString(value) Convert to string
$ToDate(value) Convert to DateTime
$ToDateOnly(value) Convert to DateOnly
.ToNumber() String instance method
.ToString() Value instance method

Example:

num = $ToNumber("42"); // 42
str = $ToString(123); // "123"
date = $ToDate("2024-01-15");
text = "100";
value = text.ToNumber(); // 100

→ See all conversion functions

Utilities

Logging, dynamic property access, and helper functions.

Function Description
$Log(message) Log to output
$GetValue(obj, prop) Get property by name
$SetValue(obj, prop, val) Set property by name
$IsInRange(min, max, val) Check if value in range
.AddProperty(name, value) Add property to object

Example:

$Log("Hello World");
obj = { name: "Alice" };
value = $GetValue(obj, "name"); // "Alice"
$SetValue(obj, "age", 30);
inRange = $IsInRange(1, 10, 5); // true

→ See all utility functions

Function Naming Conventions

$ Prefix Functions

Functions with $ prefix are standalone/global functions:

$Max(10, 20);
$Now();
$ToDate("2024-01-15");
$Log("message");

Instance Methods

Methods called on values (no $ prefix):

// String methods
text.ToUpper();
text.Split(",");

// Array methods
array.Filter((x) => x > 0);
array.Map((x) => x * 2);

// Number methods
number.ToString();

Parameter Patterns

Fixed Arity

Most functions have fixed parameter counts:

$Max(a, b); // Always 2 parameters
$Round(value, decimals); // Always 2 parameters
$AddDays(date, days); // Always 2 parameters

Variable Arity

Some functions accept variable parameters:

$Log(message); // 1+ parameters
$Log("Value: {0}", value); // Format string + args
$Array(1, 2, 3, 4, 5); // 0+ parameters

Lambda Parameters

Array methods that take lambdas:

// 1 parameter: element
array.Filter((x) => x > 0);
array.Find((x) => x == target);

// 2 parameters: element, index
array.Map((x, i) => x + i);
array.ForEach((x, i) => $Log(i + ": " + x));

// 3 parameters: accumulator, element, index
array.ReduceToNum((acc, x, i) => acc + x, 0);

Common Usage Patterns

Pattern 1: Chaining Array Operations

result = data
  .Filter((x) => x.isActive)
  .Map((x) => x.value)
  .OrderByDescending((x) => x)
  .Take(10);

Pattern 2: Date Calculations

today = $Today();
futureDate = $AddDays(today, 30);
age = $DifferenceInYears($Today(), birthDate);

Pattern 3: String Processing

text = "  hello world  ";
processed = text.Trim().ToUpper().Replace("WORLD", "EVERSHARP");

Pattern 4: Dynamic Object Access

propertyName = "premium";
value = $GetValue(policy, propertyName);
$SetValue(policy, "discount", 0.15);

Pattern 5: Validation

isValid = $IsInRange(18, 100, age) && email.Contains("@") && name.Trim() != "";

Error Handling

Functions may throw runtime exceptions:

// Type mismatch
// $Max("text", 10)                     // ERROR: Not a number

// Null value
// nullValue.ToUpper()                  // ERROR: Null reference

// Invalid format
// $ToDate("not a date")                // ERROR: Parse failed

Safe patterns:

// Check for null
if (value != null) {
  upper = value.ToUpper();
}

// Validate before conversion
if (text != null && text != "") {
  number = $ToNumber(text);
}

// Check array length
if (items.Length > 0) {
  first = items[0];
}

Performance Considerations

Prefer Native Functions

// Less efficient: Manual loop
sum = 0;
i = 0;
while (i < numbers.Length) {
  sum += numbers[i];
  i++;
}

// More efficient: Native function
sum = $Sum(numbers);

Chain Operations

// Less efficient: Multiple intermediate arrays
filtered = data.Filter((x) => x.isActive);
mapped = filtered.Map((x) => x.value);
sorted = mapped.OrderBy((x) => x);

// More efficient: Single chain
result = data
  .Filter((x) => x.isActive)
  .Map((x) => x.value)
  .OrderBy((x) => x);

Next Steps