Built-in functions include the following.
Functions that accept regex use
general | is | to | I/O |
file | number | string | regex |
general | regex |
is | to |
I/O | file |
number | string |
returns Boolean indicating whether a validation FUNCTION or REGEX returns true for all values in an ARRAY or HASH ...or returns null when given an empty ARRAY or HASH if no FUNCTION or REGEX used, compares based on truthiness |
returns Boolean indicating whether a validation FUNCTION or REGEX returns true for any value in an ARRAY or HASH ...or returns null when given an empty ARRAY or HASH if no FUNCTION or REGEX used, compares based on truthiness |
creates a new array with count of elements specified by a positive INTEGER; sets each element to null or to ANYTHING |
returns string representing time required to execute the FUNCTION, the number of times given by the COUNT (default 1) The FUNCTION must be one that takes no parameters. COUNT must be a positive integer. see also ticks() |
if passed one argument, tests each value of ARRAY or HASH for truthiness otherwise returns count of values that the FUNCTION or REGEX returns true for see also filter(), any(), all() |
executes a system command STRING, using a trusted source (not for use with user-provided data) returns a result or throws an exception see also execTH() |
executes a system command STRING, using a trusted source (not for use with user-provided data) returns a hash instead of a result or exception see also execT() 0.12.6 changes this to execTH() and deprecates using execTh() |
exits a script with an integer CODE (default 0), or with a system-specific generic code (was always 1 prior to 0.12.3) if not an integer (does not throw) as of 0.12.3, accepts a BOOLEAN in place of the code, true meaning success, returning 0, and false meaning failure and returning a system-specific generic code (1 on Linux) as of 0.12.3, accepts a second argument; only if code returned is non-zero, will write ANYTHING to standard error, appending a newline |
if passed one argument, tests each value of ARRAY or HASH for truthiness otherwise returns array or hash of values that the FUNCTION or REGEX returns true for may return empty array or hash see also count() |
returns first element of the ARRAY, STRING, or RANGE see also last() |
returns value folded by the FUNCTION from the ARRAY or RANGE example: accepts integer range in place of an ARRAY, as implicit series accepts an array of FUNCTIONS in place of FUNCTION, alternating between each for each value see also foldfrom(), map(), zip(), X(), mapX() |
returns value folded by a FUNCTION from 1 or more ARRAYS, starting with an INIT value FUNCTION parameter count == number of ARRAYS + 1 for the result (result as first parameter in FUNCTION) accepts integer ranges in place of ARRAYS, as implicit series accepts an array of FUNCTIONS in place of FUNCTION, alternating between each for each value see also fold(), map(), zip(), X(), mapX() |
groups ARRAY elements into an array of arrays, based on the return value of a FUNCTION or an INTEGER count (per grouping) also accepts negative INTEGER to group "from the right" if no FUNCTION or INTEGER used, gathers into 2 groups based on truthiness (as of 0.9.3, always 2 groups and always true first, false second, even if one or both are empty) see also groupby(), groupbyH() |
groups ARRAY elements into an array of arrays of arrays, based on the return value of a FUNCTION, including the value grouped upon if no FUNCTION used, gathers into 2 groups based on truthiness (always 2 groups and always true first, false second, even if one or both are empty) see also groupbyH(), group() |
groups ARRAY elements into a hash of arrays, based on the return value of a FUNCTION, using the values grouped upon as keys see also groupby(), group() |
checks if complete INDEX exists INDEX may be anything valid (could include array of values, ranges, etc.) returns Boolean if indexable, or null for OTHER |
returns array of keys from a HASH (in no guaranteed order), or the 1-based indices of an ARRAY, STRING, or RANGE note: for a RANGE, it's a simple array of [1, 2] |
returns last element of the ARRAY, STRING, or RANGE see also first() |
returns the length (as integer) of an ARRAY, HASH, STRING, or RANGE STRING length in code points since RANGE indexable, returns 2 for a range |
creates new array, string, or hash, removing the last element, or returns empty item if the length is already 0 ...or leaving out by KEY or array of KEYS, or RANGE does not alter the original ARRAY, STRING, or HASH may return empty array, string, or hash see also more() and rest() |
returns array (or hash) of values mapped to a FUNCTION from 1 or more ARRAYS or HASHES accepts integer ranges in place of ARRAYS, as implicit series accepts an array of FUNCTIONS and no-ops (indicated by underscore) in place of FUNCTION, alternating between each for each value of an array see also fold(), foldfrom(), zip(), X(), mapX() |
returns cross-mapped array of values mapped to a FUNCTION from 1 or more ARRAYS accepts integer ranges in place of ARRAYS, as implicit series anything not an array or range becomes an implicit 1-element array see also X(), map(), fold(), foldfrom(), zip() |
creates new array, hash, or string, adding 1 or more ITEMS or HASHES does not alter the original ARRAY, HASH, or STRING for a STRING, may add strings or code points for a HASH, throws on duplicate keys (use concatenation to overwrite keys if desired) see also less() and rest() |
returns first element from an ARRAY that is not null returns ALT_VALUE if no suitable value found (an exception if no ALT_VALUE specified) |
generates an ascending (or "positive") array of numbers from a RANGE and INCREMENT (default 1) for descending RANGE, returns empty array may use NUMBER as implicit 1-based range RANGE and INCREMENT not limited to integers see also series() |
creates new array or string, removing the first element, or returns empty item if the length is already 0 does not alter the original ARRAY or STRING may return empty array or string see also more() and less() |
reverses order of ARRAY or RANGE elements, or digits in a NUMBER reverses keys/values of HASH if possible; throws if not possible |
rotates ARRAY elements by the DISTANCE given (default 1) positive DISTANCE rotates to the "left" and negative to the "right" for an INTEGER, rotates within RANGE; if outside RANGE, passed through unaltered |
generates an array of numbers from a RANGE and INCREMENT (default 1 or -1) may use NUMBER as implicit 1-based range RANGE and INCREMENT not limited to integers see also pseries() |
waits the specified number of milliseconds |
returns a sorted array or range, comparing each element by a FUNCTION taking two variables and returning a Boolean such as f .a < .b alternatively, compares using the less than operator, taking a FUNCTION taking one variable and returing some value, or no function at all |
returns Unix ticks in nanoseconds see also benchmark() |
returns cross-mapped array of arrays from 1 or more ARRAYS accepts integer ranges in place of ARRAYS anything not an array or range becomes an implicit 1-element array see also mapX(), map(), fold(), foldfrom(), zip() |
returns new array built by interleaving ARRAYS alternatively, takes a FUNCTION to determine set of elements to append accepts integer ranges in place of ARRAYS see also map(), fold(), foldfrom(), X(), mapX() |
returns the absolute value of a NUMBER |
returns the arctangent of a NUMBER given in radians see also tan(), sine(), cos() |
returns the least integer equal to or greater than a NUMBER see also floor() |
returns the cosine of a NUMBER given in radians see also sine(), tan(), atan() |
returns the greatest integer equal to or less than a NUMBER see also ceiling() |
returns the greatest common divisor from a group of NUMBERS (may be from ARRAY) see also lcm() |
returns the least common multiple from a group of NUMBERS (may be from ARRAY) see also gcd() |
returns the maximum item from an ARRAY, HASH, RANGE, STRING, or FUNCTION for STRING, returns the maximum code point number for FUNCTION, returns the maximum parameter count (-1 for no maximum) see also min(), minmax() |
returns the mean (average) from an ARRAY, HASH, or RANGE of values see also mid() |
returns the mid-point from an ARRAY, HASH, or RANGE of values see also mean() |
returns the minimum item from an ARRAY, HASH, RANGE, STRING, or FUNCTION for STRING, returns the minimum code point number for FUNCTION, returns the minimum parameter count see also max(), minmax() |
returns the minimum to maximum range of items from an ARRAY, HASH, RANGE, STRING, or FUNCTION for STRING, returns the code point numbers for FUNCTION, returns the parameter counts (-1 for no maximum) see also max(), min() |
for an INTEGER, returns 0 if 0, a random number from 1 to the INTEGER if positive, or -1 to the INTEGER if negative for a non-empty ARRAY, HASH, or STRING, returns 1 element at random (code point for a STRING) all numbers within limits of a signed 64-bit integer |
rounds NUMBER to specified digit COUNT after decimal point (default 0) accepts negative COUNT to indicate not to add extra padding zeroes Prior to 0.11, rounding was always done with the round half even method. With 0.11, rounding mode defaults to round half away from zero, and a rounding mode can be set. see also truncate() |
simplifies NUMBER, removing trailing zeros |
returns the sine of a NUMBER given in radians see also cos(), tan(), atan() |
returns the tangent of a NUMBER given in radians see also atan(), sine(), cos() |
truncates NUMBER to specified digit COUNT after decimal point (default 0) accepts negative COUNT to indicate not to add extra padding zeroes see also round() |
Some functions, such as split() and replace(), are listed under regex functions, though they aren't just for use with regex.
converts UTF-8 byte or byte array into a string see also s2b(), s2cp(), cp2s(), s2s(), s2n() |
converts code points (integers) into a string accepts integer RANGE in place of array also accepts embedded arrays and ranges of integers (within INTEGER_ARRAY); could have an array of arrays of integers representing grapheme clusters see also s2cp(), s2s(), s2b(), b2s(), s2n() |
creates a string from ARRAY, using the specified DELIMITER string between each entry uses if no DELIMITER passed, defaults to zero-length string see also split(), cp2s() |
converts STRING to lowercase as of 0.12.5, accepts an INTEGER representing a code point see also ucase() and tcase() |
removes preceding Unicode spacing see also trim() and rtrim() |
converts STRING to normalization form NFC see also nfd(), nfkc(), nfkd() |
converts STRING to normalization form NFD see also nfc(), nfkc(), nfkd() |
converts STRING to normalization form NFKC see also nfc(), nfd(), nfkd() |
converts STRING to normalization form NFKD see also nfc(), nfd(), nfkc() |
removes trailing Unicode spacing see also trim() and ltrim() |
returns UTF-8 byte array see also b2s(), s2cp(), cp2s(), s2s(), s2n() |
returns code point (integer) or array of code points, or ALTERNATE value for an invalid INDEX see also cp2s(), s2s(), s2b(), b2s(), s2n() |
returns array of numbers from a STRING or a single number from an INTEGER (code point), assuming base 36 ... so that the letter A or a is 10 and Z or z is 35. see also s2cp(), cp2s(), s2s(), s2b(), b2s() |
returns string built by index, or ALTERNATE value for an invalid INDEX see also s2cp(), cp2s(), s2b(), b2s(), s2n() |
converts STRING to titlecase as of 0.12.5, accepts an INTEGER representing a code point see also ucase() and lcase() |
removes preceding/trailing Unicode spacing see also ltrim() and rtrim() |
converts STRING to uppercase as of 0.12.5, accepts an INTEGER representing a code point see also lcase() and tcase() |
The regex functions understand all regex types available in langur.
To generate a regex object for these functions, you use a regex literal (such as re/pattern/) or a compile function (such as reCompile()). You could also assign regex to a variable that may be passed to these functions. The regex is compiled before the functions see it.
For the pattern, some of these functions accept plain strings (not strictly regex functions).
These functions use
returns 1-based code point range for match for no match, returns null or ALT_RETURN value |
returns array of ranges (empty array if no matches) |
returns matching string for no match, returns null or ALT_RETURN value |
returns array of matches (empty array if no matches) |
returns Boolean indicating whether there is a match |
returns string with replacements made progressively by REPLACEMENT string or by FUNCTION used with REGEX, the REPLACEMENT string may contain submatches, using $1, $2, etc. if no REPLACEMENT string or FUNCTION passed, defaults to zero-length string (replace with nothing) may also use an array of replacement strings, functions, and no-ops, alternating between each in turn (except that using with REGEX doesn't allow multiple string replacements so far) |
returns array of strings split by either a REGEX or plain STRING delimiter if passed 1 argument, delimiter defaults to zero-length string (split into code point strings) accepts INTEGER to split by (into code point strings); negative INTEGER splits "from the right" see also join(), s2cp(), s2b(), s2n() |
returns array of submatch ranges (empty array if not a match) |
returns array of arrays of submatch ranges (empty array if no matches) |
returns array of submatches (empty array if not a match) |
returns hash of whole match and submatches (empty hash if not a match) includes whole match with key 0 includes named captures twice (once with string key and once with number key) |
returns array of arrays of submatches (empty array if no matches) |
returns array of hashes of whole matches and submatches (empty array if no matches) includes whole match with key 0 includes named captures twice (once with string key and once with number key) |
returns re2 regex compiled from a pattern STRING |
converts ANYTHING to a string, escapes re2 regex metacharacters and returns string |
What is often called "global" matching we're calling "progressive." You can limit the results of these functions by passing a maximum count.
functions | progressive? |
---|---|
matching, match, submatch, submatchH, index, subindex | no |
matches, submatches, submatchesH, indices, subindices, split, replace | yes |
These functions return a Boolean. They do not throw.
|
|
|
checks for built-in function |
checks for built-in or user-defined function |
|
|
note: may have zeros after a decimal point and still be an integer |
|
does not check for numeric strings |
checks for a positive number type does not check for numeric strings |
|
checks for an re2 regex |
checks for any type of regex available in langur |
|
These functions convert, or attempt to convert a value to another type. Some of them may throw exceptions.
generates a date-time value given a STRING without a FORMAT, attempts to parse as it does for date-time literals (ISO 8601) given a STRING with a FORMAT string, attempts to parse by the Go time package (Note that, having tested the time package with Go 1.14.1 on Linux, it does not parse all time zone abbreviations, such as EST, correctly. It not only fails to parse them, but does so silently.) given a DATETIME without a TIMEZONE, it is passed through unaltered TIMEZONE string may be anything recognized by the Go time package, such as "US/Arizona", or may be an empty string (local time zone) or "Z" (UTC), or a string offset, such as "-07:00" see also toHash(), toNumber(), toString() |
attempts to create a hash from a single array of keys and values in series, or from parallel arrays of keys and values, or from a DATETIME value as of 0.12.1, will pass through a HASH value as of 0.12.3, accepts ranges in place of arrays see also keys(), toDateTime() |
attempts to convert value to a number for a BOOLEAN, returns 1 for true and 0 for false for a DATETIME, returns Unix nanoseconds since the start of January 1, 1970 UTC as of 0.12.4, accepts a numeric RANGE, returning a prospective count for an integer range (if were to be converted to an array of elements) see also toString(), s2n(), toDateTime() |
converts to and returns string does not throw if no BASE given for a DATETIME with no FORMAT, returns ISO 8601/RFC 3339 timestamp see also toNumber(), toDateTime() |
reads a string from standard in may print a PROMPT string to standard out for each attempt may use validation via a FUNCTION taking one argument such as f len(.in) < 20 or a REGEX such as RE/^\d+$/ prints an ERR_STRING if validation fails (default empty string) tries the MAX number of times given (default 1; -1 == infinite) may return an ALT_VALUE on final failure instead of an exception |
writes a string of all arguments to standard out uses |
writes a string of all arguments to standard error uses |
writes a string of all arguments to standard out, appending one system newline uses |
writes a string of all arguments to standard error, appending one system newline uses |
New file permissions, if not passed, default to the file permissions mode, which defaults to 664 (in base 8). In langur, you would write this as 8x664 (NOT 0664 or 664, which would give the wrong number (as base 10)).
appends STRING to given file; creates file if it doesn't exist see also writefile() |
changes working directory of the current script has no effect on parent processes |
returns string from given file |
writes STRING to given file see also appendfile() |