Functions

Functions in Perun2 do not cause any side effects. Their only purpose is to return a value of certain data type. The names of functions are insensitive to case size. User cannot define new functions.

structure	returns
[function name] ( [arg1 value] )	return value
[function name] ( [arg1 value], [arg2 value] )	return value
[function name] ( [arg1 value], [arg2 value], ... )	return value

Generic

Generic functions can operate on multiple data types.

First

name	arguments	returns
first	(value collection)	value

Find the first value of the collection. If the collection is empty, then an empty value is returned.

name	arguments	returns
last	(value collection)	value

Random

name	arguments	returns
random	()	number
	(number)	number
	(string)	string
	(value collection)	value

When called without any argument, it returns a random fractional value between 0 and 1. Function called with a floating-point argument behaves the same, but with different upper limit. If the argument is an integer, then returned is a random integer between 0 and this value minus one bound including. Function called with a string returns its random character. Finally, if the argument is a collection, then returned is a random element from it. Randomness in all cases is described either by the discrete uniform distribution or continuous uniform distribution.

Bool

Any

name	arguments	returns
any	(list)	bool

Check if a collection contains at least one element.

Any Inside

name	arguments	returns
anyinside	(definition)	bool

Check if current element is a directory and it contains at least one element generated by a definition.

Contains

name	arguments	returns
contains	(string, string)	bool
contains	(value collection, value)	bool

This function can be used for two purposes: to check whether a string (arg1) contains another string (arg2) or whether a collection contains a value.

Ends With

name	arguments	returns
endswith	(string, string)	bool

Check if a string (arg1) ends with another string (arg2).

Exist

name	arguments	returns
exist	(list)	bool

Check if all mentioned files and directories exist.

Exists

name	arguments	returns
exists	(string)	bool

Check if a mentioned file or directory exists.

Exist Inside

name	arguments	returns
existinside	(list)	bool

Check if current element is a directory and all files and directories with mentioned names exist inside it.

Exists Inside

name	arguments	returns
existinside	(string)	bool

Check if current element is a directory and a file or a directory with mentioned name exist inside it.

Find Text

name	arguments	returns
findtext	(string)	bool

Check if current element is a file and it contain certain text phrase (case sensitive).

Is Binary

name	arguments	returns
isbinary	(string)	bool

Check if a string consists of ones are zeros.

Is Digit

name	arguments	returns
isdigit	(string)	bool

Check if all characters of a string are digits.

Is Hex

name	arguments	returns
ishex	(string)	bool

Check if a string contains only hexadecimal characters (0-9|a-f|A-F).

Is Letter

name	arguments	returns
isletter	(string)	bool

Check if all characters of a string are letters.

Is Lower

name	arguments	returns
islower	(string)	bool

Check if all letters of a string are lowercase.

Is NaN

name	arguments	returns
isnan	(number)	bool

Check if a number is NaN.

Is Never

name	arguments	returns
isnever	(time)	bool

Check if a time is never. Never value is a time equivalent of numerical NaN. It represents wrong or missing moments in time.

Is Number

name	arguments	returns
isnumber	(string)	bool

Check if a string could be converted into a valid number. Potential suffixes are not taken into account. Function returns false if a string contains any character that is not a digit, dot nor minus sign.

Is Upper

name	arguments	returns
isupper	(string)	bool

Check if all letters of a string are uppercase.

Starts With

name	arguments	returns
startswith	(string, string)	bool

Check if a string (arg1) starts with another string (arg2).

Number

Absolute

name	arguments	returns
absolute	(number)	number

Absolute value of a number.

Ceil

name	arguments	returns
ceil	(number)	number

Return the smallest integer that is greater than or equal to a number.

Count

name	arguments	returns
count	(list)	number

Count elements in a collection.

Count Inside

name	arguments	returns
countinside	(definition)	number

Count elements defined by a definition inside a current element (provided it is a directory).

Floor

name	arguments	returns
floor	(number)	number

Return the greatest integer that is less than or equal to a number.

From Binary

name	arguments	returns
frombinary	(string)	number

Convert a string consisting of zeros and ones into a number. Return NaN if the string contains any other character. Fractional values are not supported.

From Hex

name	arguments	returns
fromhex	(string)	number

Convert a string with a hexadecimal number into a normal decimal number. Return NaN if the string contains any not allowed character. Fractional values are not supported.

Length

name	arguments	returns
length	(string)	number

Get length of a string.

Number

name	arguments	returns
number	(string)	number

Convert a string into a number. Return NaN in case of a failure. Suffixes are not taken into account and they cause a failure.

Power

name	arguments	returns
power	(number, number)	number

Return a number (arg1) to the power of another number (arg2).

Resemblance

name	arguments	returns
resemblance	(string, string)	number

This function returns a fractional value between 0 and 1. It performs the resemblance algorithm on its arguments. Returns zero if arguments do not share any common character. Returns one if a string (arg1) is already a substring of the other string (arg2) while following the rules of the Resembles operator for character equality.

Round

name	arguments	returns
round	(number)	number

Round a number to the nearest integer.

Shift Month

name	arguments	returns
shiftmonth	(time, number)	number
shiftmonth	(number, number)	number

Take a month as a number (arg1) and shift it by another number (arg2). Function can take a negative second argument and they all are treated as integers. Numbers can wrap around. For example, value 11 (November) shifted by 4 becomes 3 (March).

Shift Week Day

name	arguments	returns
shiftweekday	(time, number)	number
shiftweekday	(number, number)	number

Take a day of the week as a number (arg1) and shift it by another number (arg2). As in Shift Month, numbers are integers, can wrap around and be negative. For example, value 1 (Monday) shifted by -2 becomes 6 (Saturday).

Sign

name	arguments	returns
sign	(number)	number

If a number is negative, return -1. If a number is 0, return 0. Otherwise return 1.

Size

name	arguments	returns
size	(list)	number

Calculate the total size of all files and directories.

Sqrt

name	arguments	returns
sqrt	(number)	number

Square root of a number.

Truncate

name	arguments	returns
truncate	(number)	number

Cut off fractional part from a number.

Aggregate

Aggregate functions are a special kind of numeric functions. They all return a number and can take any amount of arguments (at least one). Arguments are restricted to only two data types: number and numeric list. Any NaN argument make the result NaN.

average	max	min
median	sum

Time

Christmas

name	arguments	returns
christmas	(number)	time

Return 24 December of certain year.

Clock

name	arguments	returns
clock	(number, number)	time
clock	(number, number, number)	time

Create a new clock. Arguments are the same as in the declaration of a clock constant. See data types.

Date

name	arguments	returns
date	(number, number, number)	time

Create a new date. Arguments are: day, month, year.

Easter

name	arguments	returns
easter	(number)	time

Return the day of Easter of certain year.

New Year

name	arguments	returns
newyear	(number)	time

Return the moment of certain New Year. Hours, minutes and seconds are included and set to 0.

Time

name	arguments	returns
time	(number, number)	time
	(number, number, number)
	(number, number, number, number, number)
	(number, number, number, number, number, number)

Create a new time. Arguments are the same as in the declaration of a time constant. See data types.

Period

Duration

name	arguments	returns
duration	(list)	period

Calculate the total duration of all files.

String

After

name	arguments	returns
after	(string, string)	string

Get the part of the base string (arg1) that stays after the first occurence of the string (arg2) inside the base string (arg1).

After Digits

name	arguments	returns
afterdigits	(string)	string

Get the part of the string that stays after the first consecutive series of digits.

After Letters

name	arguments	returns
afterletters	(string)	string

Get the part of the string that stays after the first consecutive series of letters.

Before

name	arguments	returns
before	(string, string)	string

Get the part of the base string (arg1) that stays before the first occurence of the string (arg2) inside the base string (arg1).

Before Digits

name	arguments	returns
beforedigits	(string)	string

Get the part of the string that stays before the first existing digit.

Before Letters

name	arguments	returns
beforeletters	(string)	string

Get the part of the string that stays before the first existing letter.

Binary

name	arguments	returns
binary	(number)	string

Represent a number in the binary form. Fractional values are not supported.

Capitalize

name	arguments	returns
capitalize	(string)	string

Make all words start with a capital letter. Remaining letters are transformed into lowercase.

Concatenate

name	arguments	returns
concatenate	(value, ...)	string

Merge multiple elements into one string.

Digits

name	arguments	returns
digits	(string)	string

Take all digits from a string.

Fill

name	arguments	returns
fill	(string, number)	string

If a string (arg1) is shorter than a desired length (arg2), then zeros are added at the beginning of the string to fill the difference. Use this function to convert integers into strings with constant length. For example: 001, 002, ... 021, 022.

Hex

name	arguments	returns
hex	(number)	string

Represent a number in the hexadecimal form with lowercase letters. Fractional values are not supported.

Join

name	arguments	returns
join	(list, string)	string

Combine all elements of a list (arg1) into one string using a separator (arg2).

Left

name	arguments	returns
left	(string, number)	string

Take certain amount of characters (arg2) from a string (arg1). This is done starting from left.

Letters

name	arguments	returns
letters	(string)	string

Take all letters from a string.

Lower

name	arguments	returns
lower	(string)	string

Change all letters in a string to lowercase.

Month Name

name	arguments	returns
monthname	(number)	string

Get English name of certain month. January is 1, December is 12.

Parent

name	arguments	returns
parent	(string)	string

Get absolute path to the location certain element directly is in.

Path

name	arguments	returns
path	(string)	string

If the function is called with one string argument, it returns absolute path to certain element.

Path

name	arguments	returns
path	(string, string...)	string

If the function contains at least 2 string arguments, it combines multiple filesystem path segments into one path. If certain element is an absolute path, it becomes a new base for the path and all previous arguments are ignored. An invalid or empty argument turns the final result into empty string.

Raw

name	arguments	returns
raw	(string)	string

Change all letters to their raw latin form. All diacritical and combining marks are removed from the characters. In addition, turn every ß to ss, every æ to ae and every œ to oe (and their uppercase variants). Letter case is preserved.

Repeat

name	arguments	returns
repeat	(string, number)	string

Repeat a string (arg1) certain amount of times (arg2).

Replace

name	arguments	returns
replace	(string, string, string)	string

Replace every occurence of a string (arg2) inside a string (arg1) with a new value (arg3).

Reverse

name	arguments	returns
reverse	(string)	string

Reverse a string.

Right

name	arguments	returns
right	(string, number)	string

Take certain amount of characters (arg2) from a string (arg1). This is done starting from right.

Roman

name	arguments	returns
roman	(number)	string

Express a number as roman literals. Works only for numbers smaller than 5 million. Large numbers use the vinculum system. Fractions are also expressed, but the smallest unit is the ounce (one twelfth).

Size

name	arguments	returns
size	(list)	string

Count total size of all mentioned files and directories.

String

name	arguments	returns
string	(bool)	string
	(number)
	(time)
	(period)

Convert certain value into a string. This function seems to be pointless as Perun2 performs automatic data type casts. However, there are still several use cases for it. For example, it is necessary to apply this function in order to differentiate string concatenation from arithmetic summation.

Substring

name	arguments	returns
substring	(string, number)	string
substring	(string, number, number)	string

This functions can be called in two ways: with two or three arguments. Two-argument subtring returns a string (arg1) excluding certain amount of characters (arg2) from the beginning. On the other hand, the same function called with three arguments returns certain amount of characters (arg3) from a string (arg1) starting at position (arg2). Like everywhere else, indexing is zero-based.

Trim

name	arguments	returns
trim	(string)	string

Remove whitespace characters from the beginning and end of the string.

Upper

name	arguments	returns
upper	(string)	string

Change all letters in a string to uppercase.

Week Day

name	arguments	returns
weekday	(number)	string

Get English name of certain day of the week. Monday is 1, Sunday is 7.

List

Characters

name	arguments	returns
characters	(string)	list

Transform a string into a list of characters.

Numbers

name	arguments	returns
numbers	(string)	numeric list

Find all integers inside a string.

Split

name	arguments	returns
split	(string, string)	list

Divide a string (arg1) by a separator (arg2).

Words

name	arguments	returns
words	(string)	list

Divide a string into words. Every word is a consecutive series of letters.