built-in functions

Built-in functions include the following....

general is to I/O
file number string regex

general functions

function parameters description / return values
argMax
  1. function (built-in or user-defined)
returns integer count of maximum arguments accepted by function (-1 for no set limit; -2 for not callable)
argMin
  1. function (built-in or user-defined)
returns integer count of minimum arguments accepted by function (-2 for not callable)
benchmark
  1. function (taking no parameters)
  2. integer count (optional; default 1)
returns string representing time required to execute the given function (with no parameters), the number of times given by the count
bestTag
  1. preferred tags array
  2. available tags array
takes 2 arrays of language tag strings (IETF BCP 47); picks closest available and returns hash with results (including fields such as "tag", "index", and "confidence")
execT
  1. system command string to execute
executes the given system command string, using a trusted source
not for use with user-provided data
exit
  1. integer code (optional; default 0)
exits the script with the given error code, or 1 if not an integer
first
  1. array, string, or range
returns first element of the value given
see also last()
fold
  1. function
  2. array
returns value folded by the given function from the given array
foldfrom
  1. function
  2. initialization value (fold from)
  3. arrays...
return value folded by the given function from the given arrays
given function parameter count == number of arrays + 1 for the result (result as first parameter in given function)
good
  1. function or regex
  2. array
  3. alternate (optional)
returns first element from an array that the given function or regex returns true for
returns alternate if no suitable value found (an exception if no alternate specified)
see also nn() and ns()
keyExists
  1. hash
  2. hashable value
returns Boolean indicating whether a specific hashable value exists in the given hash
keys
  1. hash
returns array of keys from the given hash (in no guaranteed order)
last
  1. array, string, or range
returns last element of the value given
see also first()
len
  1. array, hash, or string
returns the length (as integer) of an array, hash, or string (in code points)
map
  1. function
  2. values (arrays or hashes)...
returns array (or hash) of values mapped to the given function from the given arrays or hashes (one type only)
nn
  1. array
  2. alternate (optional)
returns first element from an array that is not null
returns alternate if no suitable value found (an exception if no alternate specified)
see also ns() and good()
ns
  1. array
  2. alternate (optional)
returns first element from an array that is not special (not null, an infinity, or NaN)
returns alternate if no suitable value found (an exception if no alternate specified)
see also nn() and good()
pop
  1. array or string
removes the last element of an array or string or does nothing if the length is 0
may return empty array or string
does not alter the original array or string
see also push() and rest()
push
  1. array or string
  2. items...
adds items to end of array or string
for a string, may add strings or code points
does not alter the original array or string
rest
  1. array or string
removes the first element of an array or string or does nothing if the length is 0
may return empty array or string
does not alter the original array or string
see also push() and pop()
reverse
  1. array or range
returns the reversed array or range
future development: to reverse a string by Unicode rules
(To reverse a string by code points, use a descending range with an index.)
series
  1. range
  2. increment (optional; defaults to 1 or -1)
generates an array of numbers from a range and increment
range and increment not limited to integers
sort
  1. function
  2. array
returns a sorted array from the given array, comparing by the given function (taking two variables and returning a Boolean in the form of f .a < .b)
where
  1. function or regex
  2. array or hash
returns array (or hash) of values that the given function or regex returns true for, or empty array or hash

is functions

These functions return a Boolean.

function checks for
isArray array
isBool Boolean
isBoolOrNull Boolean or null
isBuiltIn built-in function
isCallable built-in or user-defined function
isHash hash
isInfinity +/-Infinity
isInteger integer
may have trailing zeros and still be an integer
isNaN NaN
isNull null
isNumber number
excludes NaN and Infinity
also does not check for numeric strings
isNumType number type
includes NaN and Infinity
does not check for numeric strings
isPosNumType positive number type
includes positive Infinity
isRange range
isRe re2 regex
isRegex any type of regex available in langur
isSpecial special value (null, NaN, or Infinity)
isString string

to functions

These functions convert, or attempt to convert a value to another type. Some of them may throw exceptions.

function parameters description / return values
toBool
  1. anything
The effect of toBool() is different than the "truthiness" used in logical operations.
  • true, "true": true
  • false, "false": false
  • null, "null", NaN: false
  • 0, "0": false
  • empty regex: false
  • empty array: false
  • empty hash: false
  • trimmed number string: converted to number and tested
  • other: true
does not throw
toBoolOrNull
  1. anything
  • true, "true": true
  • false, "false": false
  • null, "null", NaN: null
  • 0, "0": false
  • empty regex: false
  • empty array: false
  • empty hash: false
  • trimmed number string: converted to number and tested
  • other: null
does not throw
toHash
  1. array1
  2. array2 (optional)
attempts to create a hash from a single array of keys and values in series, or from parallel arrays of keys and values
see also keys()
may throw
toNumber
  1. value
  2. base (optional)
attempts to convert value to a number
excludes NaN and Infinity
base may be used with a number string
see also toNumberType() and toString()
may throw
toNumType
  1. value
  2. base (optional)
attempts to convert value to a number type
includes NaN and Infinity
base may be used with a number string
see also toNumber() and toString()
may throw
toString
  1. anything
  2. base (optional)
converts to and returns string; optionally converts number to given base string
see also toNumber()
only throws if a number base conversion fails (if no base given, doesn't throw)

I/O functions

function parameters description / return values
read all parameters to read() optional
  1. prompt string
  2. validation function or regex
  3. validation error string
  4. max attempts integer (default 1; -1 == infinite)
  5. alternate return (instead of exception on failure)
reads string from standard in, and may validate according to a function such as f len(.input) < 20 or a regex such as RE/^\d+$/ to allow integers only.
write
  1. args...
writes a string of all arguments to standard out
writeErr
  1. args...
writes a string of all arguments to standard error
writeln
  1. args...
writes a string of all arguments to standard out, appending a newline
writelnErr
  1. args...
writes a string of all arguments to standard error, appending a newline

file functions

function parameters description / return values
appendfile
  1. file name (including path)
  2. string to write
  3. permissions (optional)
appends string to given file; creates file if it doesn't exist
see also writefile()
readfile
  1. file name (including path)
returns string from given file
writefile
  1. file name (including path)
  2. string to write
  3. permissions (optional)
writes string to given file
see also appendfile()

number functions

function parameters description / return values
abs
  1. number
returns the absolute value of a number
ceiling
  1. number
returns the least integer equal to or greater than a number
floor
  1. number
returns the greatest integer equal to or less than a number
round
  1. number
  2. round to (optional; default 0)
rounds number to specified digits after decimal point
to < 0 means to simplify (remove trailing zeros)
see also truncate()
simplify
  1. number
simplifies number, removing trailing zeros
truncate
  1. number
  2. truncate to (optional; default 0)
truncates number to specified digits after decimal point
to < 0 means to simplify (remove trailing zeros)
see also round()

string functions

The split() and replace() functions are listed under regex functions, though they aren't just for use with regex.

function parameters description / return values
cpToString
  1. code point (integer) or array of code points
converts code point(s) into a string
see also stringToCp()
join
  1. delimiter string
  2. array of strings
joins array of strings into a single string
see also split()
lcase
  1. string
converts to lowercase
see also ucase() and tcase()
stringToCp
  1. string
  2. index (optional)
  3. alternate (optional; for invalid index)
returns code point (integer) or array of code points, or alternate value
see also cpToString()
tcase
  1. string
converts to titlecase
see also ucase() and lcase()
trim
  1. string
removes preceding/trailing Unicode spacing
ucase
  1. string
converts to uppercase
see also lcase() and tcase()

regex

The regex functions understand all regex types available in langur.

To generate a regex object for these functions, you use a regex literal or a compile function (such as reCompile() for re2). You could also assign regex to a variable that may be passed to these functions. The regex is compiled before the functions see it.

In place of a string to test, these functions accept anything and convert it to a string if necessary.

The split() and replace() functions also accept plain strings to split on or replace (not strictly regex functions).

functions progressive?
matching, match, submatch, index, subindex no
maches, submatches, indices, subindices, split, replace yes

What is often called "global" matching we're calling "progressive." You can limit the results of these functions by passing a maximum count.

function parameters description / return values
index
  1. regex
  2. anything
  3. alternate (optional)
returns 1-based code point range for match or null for no match or alternate return value
indices
  1. regex
  2. anything
  3. max (optional)
progressive match indices
returns array of ranges (empty array if no matches)
match
  1. regex
  2. anything
  3. alternate (optional)
returns matching string or null, or alternate return value
matches
  1. regex
  2. anything
  3. max (optional)
progressive match
returns array of matches (empty array if no matches)
matching
  1. regex
  2. anything
returns Boolean
replace
  1. anything (source)
  2. regex or plain string (find)
  3. replacement string
  4. max (optional)
returns string with replacements made progressively
split
  1. regex or plain string (delimiter)
  2. anything
  3. max (optional)
returns array of strings split by either a regex pattern or plain string
subindex
  1. regex
  2. anything
returns array of submatch ranges (empty array if not a match)
subindices
  1. regex
  2. anything
  3. max (optional)
progressive submatch indices
returns array of arrays of submatch ranges (empty array if no matches)
submatch
  1. regex
  2. anything
returns array of submatches (empty array if not a match)
submatches
  1. regex
  2. anything
  3. max (optional)
progressive submatches
returns array of arrays of submatches (empty array if no matches)
reCompile
  1. regex pattern string
compiles re2 regex
reEsc
  1. anything
escapes re2 regex metacharacters
returns string