Numerical Functions

Pikt offers a wide variety of built-in functions, both numerical and string.  An unusual feature of Pikt functions is that they are data-typed: their return value is signified by either the "$" (for string) or "#" (for number) prefix.  (Functions never return a preceding or previous value, so no functions are of the type @foo() or %foo().)  (Note: Whitespace between the function name and the opening left parenthesis is illegal.)

Note that many of the functions have synonymous names, in some cases abbreviations, in other cases names by which they are known in other popular programming languages.

In the function descriptions below, "x" signifies any expression that evaluates to either TRUE (non-zero) or FALSE (zero); "a" any string expression; "n" any numerical expression; and "F" a filehandle.

The numerical functions (functions that return a number value) include:

#abs(n)
#absval(n)
#absolutevalue(n)
        returns the absolute value of n

#age(a1,a2,a3)
#fileage(a1,a2,a3)
        returns the age in days since a1/a2/a3, whether a1 is a
        full month name or its three-letter equivalent, and
        whether a3 is a four-digit year (yyyy) or a time (hh:mm)
        (a2 must be a date)

#and(x1,x2,...)
        returns TRUE if expressions x1, x2, ... are all TRUE
        (non-zero); FALSE otherwise (if one or more expressions
        are FALSE or zero)

#ascii()
        [see #code()]

#avg(n1,n2,...)
#average(n1,n2,...)
#mean(n1,n2,...)
        returns the average (mean) of the values n1, n2, ...

#ceiling(n)
        returns n rounded up to the nearest integer

#code(a)
#ascii(a)
#ord(a)
        returns the ASCII value of the first char in a

#datevalue(n1,n2,n3)
        returns the time value for the date n3/n2/n1 (dd/mm/yyyy)

#day()
        returns the current calendar day (1-31)
#day(n)
        returns the calendar day (1-31) of the datevalue n

#daynumber()
        returns the current weekday (1-7)
#daynumber(a)
        returns the weekday (1-7) for the string a ("Sunday",
        "Monday", ...; or their three-letter abbreviations,
        "Sun", "Mon", ...)

#daysbetween(n1,n2)
        returns the number of days between the datevalues
        n1 and n2

#defined(x)
#defined(a)
#defined(n)
        for x, a, or n; returns TRUE (1) if x resolves to a value,
        or in the case of variables has appeared in a previous dat
        or set statement, or has a previous or preceding value;
        FALSE (0) otherwise; #defined(ERR), #defined(NIL),
        #defined("<<ERR>>"), and #defined("<<NIL>>") are
        always FALSE (0)

#eoi()
#endofinput()
        returns TRUE if there is no input, if at the last input
        line, or if in the end section; FALSE otherwise

#err()
        returns ERR

#error(a)
#error(n)
        returns TRUE (1), if evaluating a or n produces an error;
        FALSE (0) otherwise

#even(n)
        returns TRUE, if n is even; FALSE, if n is odd

#false()
        returns FALSE (0)

#fclose(F)
        closes file F; returns TRUE if successful, ERR if
        unsuccessful

#fileage()
        [see #age()]

#fileino(a)
        for path a, returns its inode

#filelinks(a)
        for path a, returns its link count

#fileuid(a)
        for path a, returns the uid of its owner

#filegid(a)
        for path a, returns the gid of its group owner

#fileatime(a)
        for path a, returns its atime (as a time value)

#filectime(a)
        for path a, returns its ctime (as a time value)

#filemtime(a)
        for path a, returns its mtime (as a time value)

#filesize(a)
        for path a, returns its size (in bytes)

#find()
        [see #search()]

#fopen(F,a1,a2)
        opens file a1 with mode a2 (any of "r", "w", or "a");
        returns TRUE if successful, ERR if unsuccessful

#grgid(a)
#grgid(n)
#groupgid(a)
#groupgid(n)
        for group name a, or gid n, returns its gid
        (as recorded in the system group file)

#hour()
        returns the current hour (0-23)
#hour(n)
        returns the hour portion (0-23)
        of the datevalue/timevalue n

#if(x,n1,n2)
        returns n1, if x is TRUE; else n2, if x is FALSE
#if(x,n)
        returns n, if x is TRUE; else the special numerical
        value NIL, if x is false

#index()
        [see #search()]

#inlen()
#inputlength()
        returns the length (number of chars) of the current
        input line; 0 if outside the input processing loop

#innum()
#inputnumber()
        returns the line number of the current input line;
        0 if still in the begin section; the line number of
        the last input line if in the end section

#int(n)
#integer(n)
        returns n rounded down to the nearest integer

#isalnum(a)
        returns TRUE, if the first char in a is alphanumeric

#isalpha(a)
        returns TRUE, if the first char in a is a letter

#iscntrl(a)
        returns TRUE, if the first char in a is a control char

#isdigit(a)
        returns TRUE, if the first char in a is a digit

#isgraph(a)
        returns TRUE, if the first char in a is any printing
        char, except space

#islower(a)
        returns TRUE, if the first char in a is a lower-case
        letter

#isprint(a)
        returns TRUE, if the first char in a is any printing
        char, including space

#ispunct(a)
        returns TRUE, if the first char in a is any printing
        char but neither a space nor alphanumeric

#isspace(a)
        returns TRUE, if the first char in a is a whitespace
        char

#isupper(a)
        returns TRUE, if the first char in a is an upper-case
        letter

#keys(a)
        returns the number of keys in the associative array
        a; maps those keys to a string var when used as
        'for <stringvar> in #keys(a)'; the keys are sequenced
        in the order encountered during the script run
#keys(a1,a2)
        returns the number of keys in the associative array
        a2; maps those keys to string var a1 when used as
        'foreach #keys(a1, a2)'; the keys are sequenced
        in the order encountered during the script run

#length(a)
        returns the length (number of chars) of string a

#level()
        returns the current alarm's level, 0 through 7
        (representing EMERG, ALERT, CRIT, ERR, WARNING,
        NOTICE, INFO, DEBUG)

#max(n1,n2,...)
#maximum(n1,n2,...)
        returns the maximum value among n1, n2, ...

#mean()
        [see #average()]

#median(n1,n2,...)
        returns the median value among n1, n2, ...

#members(a2,a3,a4,...)
        like #keys() (which see), except that returns the
        number of associative array keys in the sequence
        a2, a3, a4, ...; maps those keys to a string var
        when used as 'for <stringvar> in #members(a2, a3,
        a4, ...); the keys are sequenced in the order
        specified in the #members() function
#members(a1,a2,a3,a4,...)
        like #keys() (which see), except that returns the
        number of associative array keys in the sequence
        a2, a3, a4, ...; maps those keys to a1 when used as
        'foreach #members(a1, a2, a3, a4, ...); the keys are
        sequenced in the order specified in the #members()
        function

#min(n1,n2,...)
#minimum(n1,n2,...)
        returns the minimum value among n1, n2, ...

#minute()
        returns the current minute (0-59)
#minute(n)
        returns the minute portion (0-59)
        of the datevalue/timevalue n

#mode(n1,n2,...)
        returns the mode value among n1, n2, ...

#month()
        returns the current month (1-12)
#month(n)
        returns the month (1-12) of the datevalue n

#monthnumber()
        returns the current month (1-12)
#monthnumber(a)
        returns the month (1-12) for the string a ("January",
        "February", ...; or their three-letter abbreviations,
        "Jan", "Feb", ...)

#nil()
        returns NIL

#not(x)
        returns TRUE if x is FALSE (0); else FALSE if x is
        TRUE (non-zero)

#now()
        returns the current time value (number of seconds since
        the Unix Epoch, January 1, 1970)

#odd(n)
        returns TRUE, if n is odd; FALSE, if n is even

#or(x1,x2,...)
        returns TRUE if any of expressions x1, x2, ... are TRUE
        (non-zero); FALSE otherwise (if none of x1, x2, ... are
        TRUE or non-zero)

#ord()
        [see #code()]

#parse()
        [see #split()]

#passwduid()
        [see #pwuid()]

#passwdgid()
        [see #pwgid()]

#pclose(F)
        closes process F; returns TRUE if successful, ERR if
        unsuccessful

#pid(a)
#procid(a)
#processid(a)
        returns the process id (pid) of process a

#popen(F,a1,a2)
        opens process a1 with mode a2 (any of "r", "w", or "a");
        returns TRUE if successful, ERR if unsuccessful

#ppid(a)
#pprocid(a)
#pprocessid(a)
        returns the parent process id (ppid) of process a

#pwuid(a)
#pwuid(n)
#passwduid(a)
#passwduid(n)
        for user name a, or uid n, returns its uid
        (as recorded in the system passwd file)

#pwgid(a)
#pwgid(n)
#passwdgid(a)
#passwdgid(n)
        for user name a, or uid n, returns its gid
        (as recorded in the system passwd file)

#random()
        returns a random fraction 0 <= r < 1
#random(n)
        returns a random integer from 1 to n

#read(F)
        reads in the next line of input from the file handle F
        associated with some open file or process; the input
        line is assigned to the special variable $rdlin (also
        $rdline or $readline); returns the number of chars
        read, else ERR on error

#rkeys(a)
#rkeys(a1,a2)
#reversekeys(a)
#reversekeys(a1,a2)
        like #keys() (which see), except that the array keys
        are sequenced in alphabetically reverse sorted order

#rindex()
        [see #rsearch()]

#rfind()
        [see #rsearch()]

#round(n)
        returns n rounded up or down to the nearest integer
        (where #round(2.5) --> 3, #round(-2.5) --> -3)

#rsearch(a1,a2)
#rindex(a1,a2)
#rfind(a1,a2)
        return the index position (beginning at 1) of a2
        within string a1, with the search starting at the
        end of the string, else 0 if not found

#rule()
#rulenumber()
        returns 0 when called from within a Pikt script begin
        section, 1 when called within the first rule, 2 when
        called within the second rule, and so on; if there
        are x rules within a Pikt script and #rule() is called
        from within an end section, x+1 is returned

#search(a1,a2,n)
#index(a1,a2,n)
#find(a1,a2,n)
        returns the index position (beginning at 1) of a2
        within string a1, with the search starting at
        position n; else 0 if not found
#search(a1,a2)
#index(a1,a2)
#find(a1,a2)
        returns the index position (beginning at 1) of a2
        within string a1, with the search starting at the
        beginning of the string; else 0 if not found

#second()
        returns the current second (0-59)
#second(n)
        returns the second portion (0-59)
        of the datevalue/timevalue n

#skeys(a)
#skeys(a1,a2)
#sortkeys(a)
#sortkeys(a1,a2)
        like #keys() (which see), except that the array keys
        are sequenced in alphabetically sorted order

#split(a)
#parse(a)
        decomposes string a into parts assigned to the variables
        $1, $2, ..., where whitespace (space or tab) separates
        the constituent parts; returns the number of parts
#split(a1,a2)
#parse(a1,a2)
        decomposes string a1 into parts assigned to the
        variables $1, $2, ...; if a2 is not a regular
        expression, any of the chars in a2 serve as
        field separators for the decomposition;
        else if a2 is a regular expression containing
        one or more () pairs, the matching constituent
        parts are assigned to $1, $2, ..., and the entire
        expression match is assigned to $0;
        returns the number of parts, or matched parts
        in the regular expression case
#split(a1,a2,a3)
#parse(a1,a2,a3)
        decomposes string a2 into parts assigned to the variables
        a1[1], a1[2], a1[3], ...; a3 is the field separator(s) for
        the decomposition; returns the number of parts

#system(a)
        executes the command string a, returning its exit value

#timevalue(n1,n2,n3)
        returns the time value for the time n1:n2:n3 (hh:mm:ss)

#today()
        returns the time value of the current day's beginning
        (midnight)

#true()
        returns TRUE (1)

#trunc(n)
#truncate(n)
        returns n as an integer with its fractional part (if
        any) lopped off

#val(a)
#value(a)
        returns the numerical value of a; or ERR, if a doesn't
        resolve to a number

#weekday()
        returns the current weekday (1-7)
#weekday(n)
        returns the weekday (1-7) of the datevalue n

#write(F,a)
        writes string a to the file handle F associated with
        some open file or process; returns the number of
        chars written; else ERR on error

#year()
        returns the current year (as a four-digit number)
#year(n)
        returns the year (as a four-digit number) of the
        datevalue n

#yearday()
        returns the current yearday (1-366)
#yearday(n)
        returns the yearday (1-366) of the datevalue n

#yearweek()
        returns the current yearweek (1-53)
#yearweek(n)
        returns the yearweek (1-53) of the datevalue n


prev page 1st page next page
Home | FAQ | News | Intro | Samples | Tutorial | Reference | Software | DevNotes | Licensing | Authors | Pikt-Users | Pikt-Workers | Links | SiteIndex | ContactUs
Page best viewed at 1024x768.   Page last updated 2006-09-10.   This site is PIKT® powered.
PIKT® is a registered trademark of the University of Chicago.   Copyright © 1998-2006 Robert Osterlund.  All rights reserved.
Home FAQ News Intro Samples Tutorial Reference Software
PIKT Logo
PIKT Page Title