Skip to content

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 7 Arithmetic and mathematical operations
Date & Time 26 Date/time creation, manipulation, and calculations
Strings 18+ String manipulation and text operations
Arrays 40+ Array creation, transformation, and manipulation
Conversions 12 Type conversion functions
Utilities 12+ 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
$Pow(base, exponent) Raises a number to a power
$Ln(value) Returns the natural logarithm
$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
power = $Pow(2, 3); // 8
ln = $Ln(2.718281828); // about 1
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
.ToDateUTC() Parse instance value as UTC DateTime
.ToShortDateString() Format value as short date
.GetTimeZoneAbbreviation(name) Get timezone abbreviation
$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
.RemoveNonAlpha() Remove non-alphabetic characters
.GetCountryNameFromISOCode() Convert ISO code to country name
.ToStringSafe() Safe string conversion
$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
.ToStringSafe() Safe null-tolerant string
$ToDate(value) Convert to DateTime
.ToDateUTC() Convert value to UTC 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
$HasProperty(obj, prop) Check whether a property exists
$SetValue(obj, prop, val) Set property by name
$IsInRange(min, max, val) Check if value in range
$IsNumber(value) Check if a value can be treated as number
.AddProperty(name, value) Return a new object with extra property
.HasProperty(name) Check whether an object has a property

Example:

$Log("Hello World");
obj = { name: "Alice" };
value = $GetValue(obj, "name"); // "Alice"
exists = obj.HasProperty("name"); // true
isNumeric = $IsNumber("42.5"); // true
$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